От автора: текстовый редактор является ключевым элементом WordPress. С его помощью в визуальном текстовом редакторе (WYSIWYG) можно создавать и управлять как текстом, так и изображениями и видеоматериалами.
В визуальном редакторе есть текстовый режим, с помощью которого можно вставлять или редактировать HTML код. Визуальный редактор в WordPress работает на WYSIWYG редакторе TinyMCE, он хорошо справляется, как и с отображением самого контента, так и с отображением кнопок своего интерфейса, как на картинке ниже:
Спасибо TinyMCE API и WordPress за то, что мы можем добавить свой собственный функционал во встроенный визуальный редактор. На самом деле мы научимся создавать и регистрировать собственные TinyMCE плагины, которые для работы с текстом будут использовать отдельный CSS класс.
Создание плагина TinyMCE
Создайте папку wp-content/plugins/tinymce-custom-class на сайте. Здесь будут храниться файлы нашего плагина. В этой папке создайте файл tinymce-custom-class.php и добавьте в него следующий код:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
/** * Plugin Name: TinyMCE Custom Class * Plugin URI: //sitepoint.com * Version: 1.0 * Author: Tim Carr * Author URI: //www.n7studios.co.uk * Description: TinyMCE Plugin to wrap selected text in a custom CSS class, within the Visual Editor * License: GPL2 */ class TinyMCE_Custom_Class { /** * конструктор. Запускается при получении объекта плагина. */ function __construct() { } } $tinymce_custom_class = new TinyMCE_Custom_Class; |
Метаданные в комментариях нужны для WordPress. В конструкторе мы будем регистрировать действия и фильтры.
WordPress TinyMCE фильтры
В TinyMCE есть два ключевых фильтра, с помощью которых можно зарегистрировать элемент в панели инструментов визуального редактора:
mce_external_plugins: используется для загрузки внешних плагинов TinyMCE mce_buttons: используется для добавления или удаления кнопок на панели инструментов TinyMCE
Перед вызовом фильтров необходимо убедиться, что мы находимся на странице административных панелей. Добавьте код ниже в конструктор:
|
1 2 3 |
if ( is_admin() ) { add_action( 'init', array( &$this, 'setup_tinymce_plugin' ) ); } |
Теперь сделаем еще пару проверок, добавим функцию setup_tinymce_plugin:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
/** * Проверяет, может ли пользователь редактировать посты и страницы, а также пользоваться визуальным редактором * Если да, добавляет пару фильтров, чтобы мы могли зарегистрировать наш плагин */ function setup_tinymce_plugin() { // Проверяет, может ли залогинившийся пользователь редактировать посты и //страницы // Если нет, плагин TinyMCE не регистрируется if ( ! current_user_can( 'edit_posts' ) && ! current_user_can( 'edit_pages' ) ) { return; } // Проверяем подключен ли визуальный редактор для залогинившегося //пользователя // Если нет, плагин TinyMCE не регистрируется if ( get_user_option( 'rich_editing' ) !== 'true' ) { return; } // Устанавливаем фильтры add_filter( 'mce_external_plugins', array( &$this, 'add_tinymce_plugin' ) ); add_filter( 'mce_buttons', array( &$this, 'add_tinymce_toolbar_button' ) ); } |
Код выше проверяет, может ли текущий залогинившийся пользователь редактировать посты и страницы. Если нет, нет причин регистрировать наш плагин, так как пользователь не имеет доступа к визуальному редактору.
Далее мы проверяем, подключен ли для пользователя визуальный редактор. Выключить его можно в панели Пользователи > Ваш профиль. Еще раз, если пользователь не использует визуальный редактор, то мы выходим из функции, дальше нет смысла что-то делать.
Если мы прошли все проверки, то будут зарегистрированы два фильтра mce_external_plugins и mce_buttons. Первый предназначен для регистрации в TinyMCE файлов JS, которые будут взаимодействовать с визуальным редактором. Давайте вызовем этот фильтр внутри нашего класса:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/** * Adds a TinyMCE plugin compatible JS file to the TinyMCE / Visual Editor instance * * @param array $plugin_array Array of registered TinyMCE Plugins * @return array Modified array of registered TinyMCE Plugins */ function add_tinymce_plugin( $plugin_array ) { $plugin_array['custom_class'] = plugin_dir_url( __FILE__ ) . 'tinymce-custom-class.js'; return $plugin_array; } |
Мы зарегистрировали файл JavaScript в массиве $plugin_array, в котором содержатся все JavaScript плагины для TinyMCE. Второй фильтр предназначен для регистрации кнопок. Точно так же добавим вызов фильтра:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/** * Adds a button to the TinyMCE / Visual Editor which the user can click * to insert a custom CSS class. * * @param array $buttons Array of registered TinyMCE Buttons * @return array Modified array of registered TinyMCE Buttons */ function add_tinymce_toolbar_button( $buttons ) { array_push( $buttons, 'custom_class' ); return $buttons; } |
Мы зарегистрировали программное имя для нашей кнопки (custom_class).
Создаем плагин JavaScript
При вызове фильтра mce_external_plugins мы ссылаемся на JS файл. Т.е. необходимо создать этот самый файл и написать его код. В коде будет указано, как отображать нашу кастомную кнопку, и что делать по клику на нее. В папке плагина создайте новый файл tinymce-custom-class.js со следующим кодом:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
(function() { tinymce.PluginManager.add( 'custom_class', function( editor, url ) { // Добавляем кнопку в визуальный редактор editor.addButton('custom_class', { title: 'Insert CSS Class', cmd: 'custom_class', image: url + '/icon.png', }); // Что делать при клике на кнопку editor.addCommand('custom_class', function() { alert('Button clicked!'); }); }); })(); |
Данная функция выполняет следующие действия:
Она обращается к классу TinyMCE Plugin Manager. Данный класс используется для добавления действий к плагинам. Другими словами, мы добавляем наш плагин в коллекцию TinyMCE с помощью функции add.
В аргументах функции add указываем экземпляр визуального редактора editor. Кнопка регистрируется с помощью функции addButton. В параметрах данной функции указывается название кнопки, команда и путь к иконке.
В конце с помощью функции addCommand наша команда регистрируется. При нажатии на кнопку будет всплывать модальное окно.
В папку плагина нужно добавить иконку кнопки icon.png:
Сохраните код и активируйте плагин в панели плагинов в WordPress. Затем создайте или отредактируйте существующие пост или страницу, и вы заметите вашу новую кнопку:
По клику на нее всплывет сообщение «Button clicked!»:
Задаем команду для запуска
Заменим alert на prompt, спросим у администратора, какой CSS класс необходимо добавить к выбранному тексту:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
(function() { tinymce.PluginManager.add( 'custom_class', function( editor, url ) { // Добавляем кнопку в визуальный редактор editor.addButton('custom_class', { title: 'Insert CSS Class', cmd: 'custom_class', image: url + '/icon.png', }); // По клику на кнопку добавляем команды editor.addCommand('custom_class', function() { // Проверяем, выделен ли текст var text = editor.selection.getContent({ 'format': 'html' }); if ( text.length === 0 ) { alert( 'Please select some text.' ); return; } // Просим ввести название CSS класса var result = prompt('Enter the CSS class'); if ( !result ) { // пользователь отменил операцию - выход return; } if (result.length === 0) { // пользователь ничего не ввел - выход return; } // вставляем текст обратно, обернув его тегом <span> editor.execCommand('mceReplaceContent', false, '' + text + ''); }); }); })(); |
Этот код выполняет пару вполне понятных проверок: на выделенный текст, на то, ввел ли пользователь имя класса, и не отменил ли он свое действие.
Если проверки пройдены, запускается функция execCommand, которая оборачивает выделенный текст в тег span с введенным именем класса.
Если все прошло гладко, переключитесь в текстовый режим. Теперь наш текст обернут тегом span:
Заключение
Мы создали плагин для WordPress, который добавляет кнопки в визуальный редактор TinyMCE. В ходе создания мы ознакомились с фильтрами, которые используются для интеграции TinyMCE, а также написали JS код, который, собственно, и добавляет кнопку и выполняет все действия по клику на нее.
Загрузить все исходники можно на GitHub или по прямой ссылке.
Автор: Tim Carr
Источник: //www.sitepoint.com/
Редакция: Команда webformyself.
Комментарии (2)