Створюємо свої кнопки для редактора записів WordPress

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

До речі, ви можете самостійно увімкнути приховані MCE-кнопки. Зазвичай це кнопки таблиця стилів, нижче, SUP. Якщо навіть приховані кнопки після увімкнення не відповідають вашим очікуванням і вимогам, ви можете створити плагін для роботи з TinyMCE. У цьому пості ми розберемося з основами створення нових кнопок у редакторі для WordPress та написанні для цієї мети плагіна під TinyMCE.

| Завантажити вихідні |

Дивіться також:

• Як додати свої стилі у WordPress редакторі TinyMCE
• Як додати свої стилі до візуального редактора записів WordPress
• Як змінити ширину та стиль редактора WordPress у повноекранному режимі
• Покращуємо вигляд редактора коду WordPress за допомогою CodeMirror
• Як ефективно використовувати редактор wp_editor

Перш ніж почати

Як уже було сказано, ми створимо новий TinyMCE-плагін, завданням якого стане додавання нових кнопок за нашим бажанням. Які саме кнопки ми додамо? Для початку це будуть 2 кнопки: dropcap и Останні повідомлення, завданням яких стане перемикання між літерами та відображення недавніх постів.

Код для створення кнопок наведено нижче. Створимо нову папку під назвою wptuts-editor-buttons (можете вибрати і назву на свій смак) усередині папки з вашою темою за промовчанням або іншою активною темою (наприклад, я використав тему оформлення TwentyTwelve). Потім створимо 2 файли: wptuts.php для коду PHP та wptuts-plugin.js для додавання JavaScript. І, нарешті, відкрийте файл functions.php та увімкніть до складу новий файл wptuts.php.

Не забудьте вказати конкретний шлях у коді:

require( 'wptuts-editor-buttons/wptuts.php' );

Потім треба підготувати код для 2 кнопок:

dropcap

Тут треба звичайну букву "обернути" в код із заздалегідь заданим HTML-класом span для стилізації зображення букв. CSS-код наведений нижче, застосуйте його для свого файлу у темі оформлення під назвою style.css:

/* Add this code in style.css */
.dropcap {
    float: left;
    font-size: 80px;
    padding-right: 7px;
    line-height: 72px;
}

Останні повідомлення

Тут ми зробимо шорт-код для додавання списку останніх постів; просто відкрийте файл wptuts.php і додайте до нього наступний код:

add_shortcode( 'recent-posts', 'wptuts_recent_posts' );
function wptuts_recent_posts( $atts ) {
    extract( shortcode_atts( array(
        'numbers' => '5',
    ), $atts ) );
    $rposts = new WP_Query( array( 'posts_per_page' => $numbers, 'orderby' => 'date' ) );
    if ( $rposts->have_posts() ) {
        $html = '<h3>Recent Posts</h3><ul class="recent-posts">';
        while( $rposts->have_posts() ) {
            $rposts->the_post();
            $html .= sprintf(
                '<li><a href="%s" title="%s">%s</a></li>',
                get_permalink($rposts->post->ID),
                get_the_title(),
                get_the_title()
            );
        }
        $html .= '</ul>';
    }
    wp_reset_query();
    return $html;
}

Ми виходимо з припущення, що користувачі натискають кнопку Останні повідомлення, і потім браузер видаватиме спливаюче вікно із запитом, скільки саме недавніх постів ми хочемо відобразити. Отримавши це число, редактор заповнить цим аргументом наведений шорт-код. Наприклад, якщо ми хочемо відобразити 7 нещодавніх постів, вам потрібен наведений шорт-код:

[recent-posts numbers="7"/]

Реєструємо новий плагін дня TinyMCE

Виходячи з того, що ми маємо новий плагін, перейдемо до інтеграції редактора TinyMCE з цим плагіном. Ось цей код:

add_action( 'init', 'wptuts_buttons' );
function wptuts_buttons() {
    add_filter( "mce_external_plugins", "wptuts_add_buttons" );
    add_filter( 'mce_buttons', 'wptuts_register_buttons' );
}
function wptuts_add_buttons( $plugin_array ) {
    $plugin_array['wptuts'] = get_template_directory_uri() . '/wptuts-editor-buttons/wptuts-plugin.js';
    return $plugin_array;
}
function wptuts_register_buttons( $buttons ) {
    array_push( $buttons, 'dropcap', 'showrecent' ); // dropcap', 'recentposts
    return $buttons;
}

Тут є параметр mce_external_plugins для підключення нового плагіна TinyMCE. Нам треба передати значення ID для плагіна (wptuts) та абсолютна URL-адреса до файлу wptuts-plugin.js. Параметр mce_buttons використовується для повідомлення редактору TinyMCE інформації про те, які кнопки в редакторі хочемо відображати. Значення ковпачок и showrecent - Це параметри для кнопок. Запам'ятайте ці параметри та значення, вони нам знадобляться надалі.

Налаштовуємо плагін для TinyMCE

Загалом, я вважаю, що для розробки нових "фішок" та плагінів завжди треба звірятися з документацією. У редактора TinyMCE є своя Wikiяка вам допоможе. У нас є наступний код для ініціалізації:

(function() {
    tinymce.create('tinymce.plugins.Wptuts', {
        /**
         * Initializes the plugin, this will be executed after the plugin has been created.
         * This call is done before the editor instance has finished it's initialization so use the onInit event
         * of the editor instance to intercept that event.
         *
         * @param {tinymce.Editor} ed Editor instance that the plugin is initialized in.
         * @param {string} url Absolute URL to where the plugin is located.
         */
        init : function(ed, url) {
 
        },
 
        /**
         * Creates control instances based in the incomming name. This method is normally not
         * needed since the addButton method of the tinymce.Editor class is a more easy way of adding buttons
         * but you sometimes need to create more complex controls like listboxes, split buttons etc then this
         * method can be used to create those.
         *
         * @param {String} n Name of the control to create.
         * @param {tinymce.ControlManager} cm Control manager to use inorder to create new control.
         * @return {tinymce.ui.Control} New control instance or null if no control was created.
         */
        createControl : function(n, cm) {
            return null;
        },
 
        /**
         * Returns information about the plugin as a name/value array.
         * The current keys are longname, author, authorurl, infourl and version.
         *
         * @return {Object} Name/value array containing information about the plugin.
         */
        getInfo : function() {
            return {
                longname : 'Wptuts Buttons',
                author : 'Lee',
                authorurl : 'http://wp.tutsplus.com/author/leepham',
                infourl : 'http://wiki.moxiecode.com/index.php/TinyMCE:Plugins/example',
                version : "0.1"
            };
        }
    });
 
    // Register plugin
    tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();

Не забудьте додати цей код до файлу wptuts-plugin.js. Наведений вище код виконує 2 основні завдання:

1. По-перше, визначити новий плагін для TinyMCE можна за рахунок методу створювати. Поведінка плагіна визначається за рахунок функцій ініціалізації и createControl. Інформація про плагін "оголошена" у функції отримати інформацію. У плагіна буде назва Wptuts та значення ID wptuts.
2. І нарешті додаємо новий плагін у менеджер плагінів під TinyMCE.

Створюємо кнопки

У функції ініціалізації ми створюємо нові наші кнопки. Ось код для цього завдання:

(function() {
    tinymce.create('tinymce.plugins.Wptuts', {
        init : function(ed, url) {
            ed.addButton('dropcap', {
                title : 'DropCap',
                cmd : 'dropcap',
                image : url + '/dropcap.jpg'
            });
 
            ed.addButton('showrecent', {
                title : 'Add recent posts shortcode',
                cmd : 'showrecent',
                image : url + '/recent.jpg'
            });
        },
        // ... Hidden code
    });
    // Register plugin
    tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();

Використовуючи метод addButton для об'єкту ed, ми "повідомляємо" поточному редактору, що хочемо створити нові кнопки. Цей метод приймає 2 аргументи:

• Перший – це значення ID для кнопки. Він має бути таким самим, як ми вже раніше визначили, інакше нічого нормально працювати не буде.
• Другий - об'єкт з інформацією про саму кнопку:
  • Заголовок кнопки
  • Найважливіше: завдання, яке реалізує ця кнопка. Подивіться на властивість CMD, у нього значення showrecent. Тут передається значення ID, що виконується щоразу, коли відбувається виклик процедури.
  • Зображення для кнопки. Зверніть увагу, що параметр URL містить абсолютну адресу папки для розміщення плагіна, і вони повинні бути схожі, щоб легше було "зв'язати" кнопку та графіку для її відображення. Потрібно переконатися, що графіка для кнопки розміщена в папці і шлях до неї прописаний у параметрі зображення.

Тепер перевірте редактор WordPress і подивіться, як відображаються кнопки (хоча зараз вони поки що нічого не роблять):

Додаємо команди для кнопок

Визначивши імена команд для кнопок, які їх виконуватимуть, ми ще не визначили, що саме ці команди запускають, і як саме ці кнопки працюють. На цьому етапі ми налаштуємо дії кнопок. У функції ініціалізації додайте наступний код:

(function() {
    tinymce.create('tinymce.plugins.Wptuts', {
        init : function(ed, url) {
            ed.addButton('dropcap', {
                title : 'DropCap',
                cmd : 'dropcap',
                image : url + '/dropcap.jpg'
            });
 
            ed.addButton('showrecent', {
                title : 'Add recent posts shortcode',
                cmd : 'showrecent',
                image : url + '/recent.jpg'
            });
 
            ed.addCommand('dropcap', function() {
                var selected_text = ed.selection.getContent();
                var return_text = '';
                return_text = '<span class="dropcap">' + selected_text + '</span>';
                ed.execCommand('mceInsertContent', 0, return_text);
            });
 
            ed.addCommand('showrecent', function() {
                var number = prompt("How many posts you want to show ? "),
                    shortcode;
                if (number !== null) {
                    number = parseInt(number);
                    if (number > 0 && number <= 20) {
                        shortcode = '[recent-post number="' + number + '"/]';
                        ed.execCommand('mceInsertContent', 0, shortcode);
                    }
                    else {
                        alert("The number value is invalid. It should be from 0 to 20.");
                    }
                }
            });
        },
        // ... Hidden code
    });
    // Register plugin
    tinymce.PluginManager.add( 'wptuts', tinymce.plugins.Wptuts );
})();

метод ed.addCommand допоможе нам додати нову команду. Вам потрібно передати значення команди, її ID та функцію зворотного виклику, яка буде здійснюватися за рахунок виклику методу ed.execCommand. Врахуйте, що ed представляє об'єкт tinyMCE.activeEditor. Давайте подивимося на луна-функції:

• Командою ковпачок ми вибрану букву перетворюємо на буквицю за рахунок кнопки DropCap. Завдання це вирішується за допомогою методу ed.selection.getContent. Отримане зображення буквиці "загортається" в елемент span. Не забудьте налаштувати значення класу для елемента рівним ковпачок. І ще ми маємо повний текст, який вставляється назад у редактор. У редакторі TinyMCE є команда за промовчанням під назвою mceInsertContent для вставки конкретного контенту редактор. Потім контент "передається" за допомогою аргументу для методу mceInsertContent.
• Аналогічне відбувається із командою showrecentподібною до команди ковпачок. Відображається діалог, який запитує користувача, скільки недавніх постів відображатиметься, і потім це значення додається до відповідного синтаксису шорт-коду.

Реєструємо CSS-код для кнопок (за бажанням)

Замість додавання "чистого" тексту до контенту, коли спрацьовує та чи інша кнопка в редакторі, ми можемо візуалізувати процес за рахунок додавання до кнопок кастомного CSS. Ви можете вибрати найкращий стиль для певного типу контенту. Наприклад, стиль для кнопки dropcap буде таким же, як відображається на front-end. Код CSS можна винести у верхню частину посту, а потім розмістити цей код у файлі editor-style.css (Погляньте також add_editor_style для подробиць).

Що стосується шорт-кодів, то у них може і не бути HTML-елементів. Як же тоді ми їх стилізуємо та оформимо? У цій ситуації результату досягти складніше, але нічого неможливого тут теж немає (за замовчуванням у нас є кнопка для WordPress під назвою "Додайте медіаСкладнощі тут можуть виникнути при "загортанні" шорт-коду в структуру елемента HTML з подальшою стилізацією у щось візуально зрозуміле і приємне. На цих складних процедурах в цьому пості ми зупинятися не будемо.

Результати

І ось нарешті результати відображатимуться приблизно в наступному вигляді:

А ось для інтерфейсних:

І ось як працює кнопка Останні повідомлення:

Як бачите, ми вивчили основні кроки та налаштування для додавання нових кнопок у візуальному редакторі. Базова функціональність у цих кнопках реалізована, а розширення можливостей може бути трохи складним процесом, але ми тут такі питання не розглядали. І як завжди — у коментарях розповідайте, як удалося вам реалізувати наведений нами приклад на практиці.

Довідка:

• TinyMCE_Custom_Buttons

Джерело: WP.tutsplus.com

Олексій Шевченко

редактор wpcafe

Вивчає сайтобудування з 2008 року. Практикуючий вебмайстер, який спеціалізується на створенні сайтів на WordPress. Задати питання Олексію можна на https://profiles.wordpress.org/wpthemeus/