Як увімкнути підтримку власних плагінів TinyMCE у темі Publii

Однією з головних переваг Publii є можливість повністю працювати із сайтом локально та не залежати від серверних технологій. Проте стандартних можливостей редактора TinyMCE часто недостатньо для створення власних інструментів редагування. Саме тому багато розробників створюють власні плагіни, які додають нові кнопки, блоки контенту, автоматизують оформлення статей або реалізують специфічні функції.

Після створення першого плагіна нерідко виникає питання: чому Publii його не бачить? Причина досить проста — за замовчуванням тема може не дозволяти перевизначення конфігурації редактора та виконання власного JavaScript-коду. Для цього потрібно внести невеликі зміни до конфігураційного файлу теми.

Де знаходиться конфігураційний файл

Кожна тема Publii містить файл config.json, який визначає можливості теми, підтримку окремих функцій редактора та різних розширень. Саме в цьому файлі потрібно знайти або створити розділ extensions.

Щоб дозволити використання власних плагінів TinyMCE та зміну параметрів редактора, достатньо додати або змінити наступний фрагмент конфігурації:

"extensions": {
    "postEditorConfigOverride": true,
    "postEditorCustomScript": true
}

Якщо розділ extensions уже існує, потрібно лише додати або змінити ці два параметри.

Для чого потрібен параметр postEditorConfigOverride

Параметр

"postEditorConfigOverride": true

дозволяє темі використовувати файл tinymce.override.json.

Саме цей файл відповідає за налаштування редактора TinyMCE. У ньому можна:

• підключати власні плагіни;
• змінювати панелі інструментів;
• налаштовувати меню редактора;
• створювати власні контекстні меню;
• змінювати будь-які параметри TinyMCE.

Якщо цей параметр вимкнений, Publii просто ігноруватиме файл tinymce.override.json, навіть якщо він присутній у темі.

Для чого потрібен параметр postEditorCustomScript

Другий параметр

"postEditorCustomScript": true

дозволяє завантажувати файл tinymce.script.js.

Саме він є точкою входу для всього власного JavaScript-коду редактора. У ньому можна реєструвати TinyMCE-плагіни, змінювати поведінку редактора, виконувати додаткову ініціалізацію або запускати власний завантажувач плагінів.

Якщо цей параметр вимкнений, файл tinymce.script.js взагалі не буде виконуватися, а всі власні плагіни залишаться недоступними.

Чому необхідно використовувати обидва параметри

Досить часто розробники активують лише один із цих параметрів і дивуються, чому система працює лише частково.

Насправді вони виконують різні функції. postEditorCustomScript відповідає за запуск JavaScript-коду, а postEditorConfigOverride — за перевизначення конфігурації редактора TinyMCE. Лише одночасне використання цих двох параметрів відкриває всі можливості для розширення редактора.

Як це працює на практиці

Після активації обох параметрів структура теми може виглядати приблизно так:

config.json
tinymce.script.js
tinymce.override.json
assets/
    editor-plugins/
        plugins.json
        plugin-1/
        plugin-2/
        plugin-3/

У такій архітектурі кожен файл виконує власне завдання.

Файл config.json дозволяє використовувати додаткові можливості теми.

tinymce.script.js запускається під час відкриття редактора та виконує JavaScript-код.

tinymce.override.json містить усі налаштування TinyMCE.

Файл plugins.json описує перелік доступних плагінів.

Безпосередньо каталоги плагінів містять реалізацію кожного окремого розширення.

Саме такий підхід використовується в Publii UTPF Loader. Після запуску tinymce.script.js Loader автоматично читає файл plugins.json, знаходить усі доступні плагіни, реєструє їх у TinyMCE, а налаштування панелей інструментів беруться з tinymce.override.json.

У результаті для додавання нового плагіна достатньо скопіювати його папку, додати запис до plugins.json та прописати кнопку в tinymce.override.json. Сам файл tinymce.script.js при цьому змінювати вже не потрібно.

Практичні висновки

Перед розробкою власних плагінів обов'язково перевірте файл config.json. Якщо в ньому не активовані параметри postEditorConfigOverride та postEditorCustomScript, редактор TinyMCE не зможе використовувати ні власні налаштування, ні власні JavaScript-модулі. Після їх увімкнення відкривається можливість створювати модульну систему плагінів, яка легко масштабується та не потребує внесення змін до ядра Publii.

Висновок

Лише два параметри у файлі config.json відкривають практично необмежені можливості для розширення редактора TinyMCE в Publii. Вони дозволяють використовувати власні JavaScript-модулі, змінювати конфігурацію редактора, підключати нові плагіни та будувати сучасну модульну архітектуру. Якщо ви плануєте розвивати власну екосистему плагінів або використовувати Publii UTPF Loader, саме з налаштування цих параметрів варто починати.