CKEditor API

29 Июля 2020 17:23 (Редактировано: 29 Июля 2020 21:46)

CKEditor обладает мощным API для формирования своих плагинов. Используя его можно работать с выделяемым текстом, добавлять кнопки на панель, создавать диалоговые окна и т.д.

Самому доводилось работать с CKEditor API не очень много, но что-то я успел понять. Все это будет отражено здесь!

Документация по API - ссылка.

Работа с диалоговыми окнами

Раздел в документации - ссылка.

Как правило, диалоговые окна, по входящим в основной пакет плагинам, размещаются в исполняемом файле ckeditor.js. Но в некоторых случаях, сценарий для диалоговых окон может выноситься и в отдельные файлы, как например, инструмент для работы с таблицами (table) или со ссылками (link). Часть функционала диалоговых окон для таблиц, например, реализован в основном файле ckeditor.js, а часть в plugins/table/table.js.

Возьмем в пример плагин link. Весь процесс работы с диалоговым окном помещен в ананоимную функцию:

(function() {
  CKEDITOR.dialog.add("link", function(c) {
    function t(a, b) {
      var c = a.createRange();
      c.setStartBefore(b);
      c.setEndAfter(b);
      return c;
    }
    ...
})();

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

В самом начале прописываются функции и свойства для работы. В будущем эти функции будут прпоисываться в элементах диалогового окна на различные события типа setup (при открытии диалогового окна) или commit (событие на нажатие кнопки "Ок") и т.д.

Далее, рассматриваются элементы диалогового окна т.е. поля для информации, которые как то будут влиять на контент

После перечисления функций и свойств, идет такая конструкция:

return {
  title: b.title,
  minWidth: "moono-lisa" == (CKEDITOR.skinName || c.config.skin) ? 450 : 350,
  minHeight: 240,
  contents: [{
    id: "info",
    label: b.info,
    title: b.info,
    elements: [{
      type: "text",
      id: "linkDisplayText",
      label: b.displayText,
      setup: function() {
        this.enable();
        this.setValue(c.getSelection().getSelectedText());
        q = this.getValue()
      },
      commit: function(a) {
        a.linkText = this.isEnabled() ? this.getValue() : ""
      }
    }, {

Разобраться не сложно. Возвращаем объект с набором параметров таких как заголовок, ширина, высота.... Далее идет свойство contents, в котором перечисляются вкладки, которые будут в диалоговом окне: 

  1. id - идентификатор вкладки в виде названия;
  2. label и title - название вкладки;
  3. elements - массив из элементов данной вкладки.

Сразу после перечисления всех элементов данной вкладки, будет следовать следующая вкладка с названием и элементами.

...
    }],
    setup: function() {
      this.getDialog().getContentElement("info", "linkType") || this.getElement().hide()
    }
  }]
}, {
  id: "target",
  requiredContent: "a[target]",
  label: b.target,
  title: b.target,
  elements: [{
    type: "hbox",
    widths: ["50%", "50%"],
    children: [{
      type: "select",
...

 Этот кусок кода - это завершение вкладки "Информация о ссылке" и начало новой вкладки "Цель" (скриншот выше).

Примечание. такие конструкции как b.info или b.title - это ссылки на языковой объект, который хранится в отдельном файле lang/ru.js или lang/en.js. Расшифровку искать нужно в нем. Также можно дополнять файл новыми значениями.

Элементы диалогового окна

Рассмотрим пример конкретного элемента (но плагина не link, а table).

{
  type: "checkbox",
  id: "tableType",
  requiredContent: "table[tableType]",
  label: a.lang.table.tabletype,
  setup: function(a) {
    a.hasClass('content-table') ? this.setValue(1) : this.setValue(0);
  },
  commit: function(a, d) {
    this.getValue() ? d.addClass("content-table") : d.removeClass("content-table");
  }
}

Этот элемент - это добавленный чекбокс для взаимодействия с созданной таблицой в CKEditor. Смысл его был в том, чтобы по нажатию на этот чекбокс и подтверждению диалогового окна, таблице присваивался класс content-table. Что здесь происходит:

  1. type - тип добавляемого поля;
  2. id - идентификатор;
  3. requiredContent - включаем работу с контентом для этого поля;
  4. label - подпись для поля.

Это стандартные настройки для поля, дальше интереснее. События:

  1. setup - событие на открытие диалогового окна. Т.е. при открытии окна будут выполнены эти действия для поля. Например, тут сделано, чтобы проводилась првоерка на наличие у таблицы класса content-table и если есть то присваиваем чекбоксу 1, т.е. делаем его активным, иначе - 0. В этом коллбэке доступен объект a (CKEDITOR.dom.element) - это объект таблицы. Тут могут быть использованы все свойства и методы, перечисленные в документации.

     

    Доступные объекты:

     

  2. commit - событие, которое срабатывает при нажатии кнопки "ОК" диалогового окна. Т.е. фактически - это результат работы элемента. Принажатии ОК, CKEDITOR собирает все коммиты всех элементов и выполняет их! В данном примере, делаем првоерку - если чекбокс выставлен, добавляем класс объекту таблицы, если нет - убираем.

     

    Доступные объекты:

    • this - объект элемента;
    • a - объект с настройками элемента;
    • d - объект таблицы CKEDITOR.dom.element.