Текстовий редактор WordPress: як додати користувальницький функціонал?

325

Від автора: текстовий редактор є ключовим елементом WordPress. З його допомогою у візуальному редакторі (WYSIWYG) можна створювати і керувати текстом, так і зображеннями та відеоматеріалами.

У візуальному редакторі є текстовий режим, за допомогою якого можна вставляти або редагувати HTML-код. Візуальний редактор в WordPress працює на WYSIWYG редактор TinyMCE, він добре справляється, як і з відображенням самого контенту, так і з відображенням кнопок свого інтерфейсу, як на картинці нижче:

Текстовий редактор WordPress: як додати користувальницький функціонал?

Спасибі TinyMCE API і WordPress за те, що ми можемо додати свій власний функціонал у вбудований візуальний редактор. Насправді ми навчимося створювати і реєструвати власні TinyMCE плагіни, які для роботи з текстом будуть використовувати окремий CSS клас.

Створення плагіна TinyMCE

Створіть папку wp-content/plugins/tinymce-custom-class на сайті. Тут будуть зберігатися файли нашого плагіна. У цій папці створіть файл tinymce-custom-class.php і додайте в нього наступний код:

/**
* Plugin Name: TinyMCE Custom Class
* Version: 1.0
* Author: Tim Carr
* Author URI: http://www.n7studios.co.uk
* Description: TinyMCE Plugin to wrap selected text in a custom CSS class, within the Visual Editor
* Ліцензія: 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

Перед викликом фільтрів необхідно переконатися, що ми знаходимося на сторінці адміністративних панелей. Додайте код нижче в конструктор:

if ( is_admin() ) {
add_action( ‘init’, array( &$this, ‘setup_tinymce_plugin’ ) );
}

Тепер зробимо ще пару перевірок, додамо функцію setup_tinymce_plugin:

/**
* Перевіряє, чи може користувач редагувати пости і сторінки, а також користуватися візуальним редактором
* Якщо так, додає пару фільтрів, щоб ми могли зареєструвати наш плагін
*/
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 файлів, які будуть взаємодіяти з візуальним редактором. Давайте викличемо цей фільтр всередині нашого класу:

/**
* 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. Другий фільтр призначений для реєстрації кнопок. Точно так само додамо виклик фільтра:

/**
* 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 з таким кодом:

(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: як додати користувальницький функціонал?

Збережіть код активувати плагін в панелі плагінів WordPress. Потім створіть або відредагуйте існуючі посаду або сторінку, і ви помітите вашу нову кнопку:

Текстовий редактор WordPress: як додати користувальницький функціонал?

По кліку на неї з’явиться повідомлення «Button clicked!»:

Текстовий редактор WordPress: як додати користувальницький функціонал?

Задаємо команду для запуску

Замінимо alert на prompt, запитаємо у адміністратора, який CSS клас необхідно додати до вибраного тексту:

(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;
}
// вставляємо текст назад, обернувши його тегом
editor.execCommand(‘mceReplaceContent’, false, ” + text + “);
});
});
})();

Цей код виконує пару цілком зрозумілих перевірок: на виділений текст, на те, ввів користувач ім’я класу, і не скасував він свою дію.

Якщо перевірки пройдено, запускається функція execCommand, яка обертає виділений текст в тег span із введеним ім’ям класу.

Якщо все пройшло гладко, перейдіть в текстовий режим. Тепер наш текст обгорнутий тегом span:

Текстовий редактор WordPress: як додати користувальницький функціонал?

Висновок

Ми створили плагін для WordPress, який додає кнопки в візуальний редактор TinyMCE. У ході створення ми ознайомилися з фільтрами, які використовуються для інтеграції TinyMCE, а також написали JS код, який, власне, і додає кнопку і виконує всі дії по кліку на неї.

Завантажити всі вихідні коди можна на GitHub або за прямим посиланням.