Создание плагина CKEditor 5 в экосистеме Drupal 10

Drupal 10 добавил в ядро модуль wysiwyg CKEditor 5. Т.е. уже из «коробки» у вас есть редактор html кода.

API CKEditor 4 и 5 версий значительно отличаются, потому все проекты добавляющие кнопки и функционал в CKEditor 4, который можно установить как contrib модуль и в Drupal 10, не работают для CKE 5й версии.

Именно одна из таких задач переделки плагина с 4 версии на 5ю у меня и возникла.

Для конкретики, я буду рассматривать именно свой опыт — плагин c5bb (CKEditor 5 Bootstrap Buttons) опубликован на drupal.org, можете скачать исходники от туда.

Что делает плагин:

  • Добавляет инструмент для редактирования ссылок типа <a class = «btn» >, считая их бутстраповскими кнопками.
  • Позволяет выбрать ряд настроек для кнопки-ссылки, а также добавить в тело кнопки коды иконок коллекций fontawesome и glyphon. Т.е. все те же фичи, что предоставлял плагин для 4й версии CKEditor — ckeditor_bootstrap_buttons.

В итоге, в HTML формируется структура вида (демонстрация максимально расширенной версии) :

Задача объёмная и состоит из двух блоков: Drupal и CKE Plugin.

DRUPAL часть

Кроме стандартных вещей, добавления зависимости модуля от ckeditor5, модуль должен объявить плагин CKE. Это можно сделать разными путями, через аннотацию, создания плагина в каталоге /src и описания через module.ckeditor5.yml файл.

Какие то вещи можно выполнить только одним путём, какие то могут выполнятся разными способами. Т.к. в моём плагине нет нужны в настройках конфигурации, то я могу всю друпальную часть ограничить объявлениями через yml файл.

c5bb.ckeditor5.yml файл

Этот файл монтирует ваш плагин (js code для CKE 5 API) в экосистему Drupal, делая его доступным для установленного CKE 5 и настроек текстовых форматов.

Следующая строка имеет формат — «имя каталога плагина» . «имя JS класса».

В секции настроек drupal нужно указать имя билда библиотеки плагина — library (объявлена в c5bb.libraries.yml) и можно указать библиотеку — admin_library, которая подключается на странице администрирования (настройки текстовых форматов).

c5bb.libraries.yml файл

В моем случае библиотека для админки включает в себя только небольшой файл стилей, который определяет картинку для иконки в инструментах.

И очень важная секция ckeditor5.yml описателя — elements.

Запись <a> — означает, что плагин может самостоятельно создавать тег <a>, тогда как <a class href target> — показывает, что плагин может задавать атрибуты «class href target» к существующему тегу <a>. Если не укажите отдельно <a>, то валидатор при настройке инструментов wysiwyg будет требовать, чтобы ваш или какой то другой плагин «умел» создавать теги <a>.

Такой плагин есть в наборе — это Link (инструмент ссылка в CKE 5). Не указав <a> в elements, вы не сможете добавить кнопку вашего плагина без Link (или иного плагина, что умеет создавать <a>) в панель инструментов.

Тоже касается и <em>, который как видите не добавлен в текущей версии, но его надо будет добавить, чтобы не зависеть от инструмента Italic.

CKE Plugin часть

Эта может требовать некоторых hard скилов, таких например как работу с npm и ts (typescript).

Билд плагина (сборка js кода) выполняется с из папки модуля. В корне модуля вы найдете файлы package.json и webpack.config.js.

Они практически одинаковы для любых ваших проектов, если вы не отступаете от принятой структуры CKE5 плагина в экосистеме Drupal.

Установите npm (npm i).

И далее можно будет собирать плагин командой npm run build или запустить слежение для автобилда при изменениях в коде — npm run watch.

При билде создаётся папка /js/build, где будут сборки всех ваши плагинов из каталога /js/ckeditor5_plugins.

Т.е там может быть вообще то несколько плагинов. У каждого плагина должен быть свой файл /src/index.js

Сборщик здесь не умеет работать с ts, т.е. знаний js достаточно для написания плагина. Если вам потребуется ts, вы можете поработать над сборщиком и составом пакетов. Но в любом случае исходники CKEditor 5 написаны на ts, и читать код вам будет удобнее, имея соответствующие знания.

А подглядывать в исходники придется, т.к. документация хоть и обширна, но не полна. Там бывают полезные комментарии и примеры кода.

Документация по CKE5 API:
https://ckeditor.com/docs/ckeditor5/latest/api/index.html

Структура плагина CKE5.

Можно выделить три элемента, которые будут присутствовать почти в любом плагине:

  • UI,
  • Редактирование,
  • Реализация CKE комманд.

index.js файл ссылается на два первых элемента, а те используют третий. Нужно определить два метода:

bbuttonui.js файл — реализация интерфейса компонента. Здесь объявляется кнопка в тулбаре и форма, на которой пользователь выбирает параметры компонента, обрабатывается поведение формы и прочие вещи.

Тут же реализуется передача данных из модели редактора в форму и наоборот.

Сама же форма создаётся на базе View компонентов, которые предоставляются ckeditor5/src/ui

ui/formview.js файл — реализация формы. Также я создал несколько простых компонентов на базе View, которых мне не хватало — это Select, для рендеринга <select> и Tag (служит для вывода произвольного html тега).

bbuttonediting.js файл — тут описывается схема компонента и т.н. конверсии, т.е. преобразования модели (model) в представления (view) и наоборот. Представление в редакторе и в html документе могут отличаться. API предоставляет возможность создать конверторы для каждого из случаев, но можно создать и общий конвертор, как это сделано у меня в плагине изначально.

Возможно, позже я воспользуюсь возможностью, чтобы в редакторе кнопка имела иной html код, чем в исходнике документа.

bbuttoncommand.js файл — это низкий уровень преобразования, когда от вас по имеющейся модели требуется задать структуру компонента (согласно заданной схеме). При этом, я так понимаю, контроля над тем, следуете вы схеме или нет в API не заложено.

Написать комментарий

Мало букафф? Читайте есчо !

CKEditor не включается в при загрузке страницы

Август 30, 2018 г.

Редактор подключен и настроен, но почему то не включается при загрузке страницы. Как быть? Если вы уверены, что все настроено верно, а именно: ...

Читать

Фильтруем нежелательные теги из WORD в CKEditor

Июль 1, 2018 г.

Хоть CKEditor и позволяет редактировать тексты, но редакторов сложно приучить готовить их сразу на сайте. Потому первая ревизия текста обычно появляется ...

Читать

 

Комментарии к «Создание плагина CKEditor 5 в экосистеме Drupal 10»

Понравилась статья? Есть вопросы? - пишите в комментариях.



Комментарий: