CKEditor API

Die CKEditor-API ist neu in Drupal 8.

Beachten Sie, dass sich dies nur auf die API des Drupal 8 CKEditor-Moduls bezieht und nicht auf die API der JavaScript-Bibliothek CKEditor – für diese siehe http://docs.ckeditor.com/.

Für ausführlichere Informationen darüber, was dieses Modul macht, siehe die Dokumentation des Text Editor Moduls.

API-Funktionen

Geordnet nach den am seltensten verwendeten APIs:

CKEditor Skins

Der CKEditor in Drupal 8 verwendet standardmäßig das Skin Moono. Das ist für die meisten Websites gut, da es ein recht neutrales Skin ist. Einige Websites möchten jedoch eine perfekte Integration haben, und in diesem Fall können Sie ein anderes Skin installieren – möglicherweise sogar ein eigenes, das Sie selbst erstellen.
Dazu implementieren wir hook_editor_js_settings_alter():

function hook_editor_js_settings_alter(array &$settings) {
  foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
    if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
      $settings['editor']['formats'][$text_format_id]['editorSettings']['skin'] = 'SKIN_NAME,ABSOLUTE_URL_TO_SKIN';
    }
  }
}

CKEditor iframe CSS

Das CSS, das in die CKEditor-iframe-Instanz geladen wird, zum Beispiel bei /node/add/article (also die CKEditor-Instanz, die nicht für die Inline-Bearbeitung genutzt wird), muss möglicherweise so angepasst werden, dass die CKEditor-iframe-Instanzen dem Frontend-Stil entsprechen (für Nutzer, die WYSIWYG bevorzugen) oder die Struktur anzeigen (für Nutzer, die reine Hilfstext-Editoren bevorzugen).
                – Frontend-Theme CSS
Fast jedes Frontend-Theme hat CSS zur Gestaltung von Absätzen, Zitaten, Bildunterschriften usw. Deshalb sollten alle Frontend-Themes den CKEditor-iframe-Instanzen das Laden von CSS für alle Inhalte (Text/Markup) ermöglichen, die Content-Ersteller erzeugen können. Dies können sie erreichen, indem sie den Schlüssel ckeditor_stylesheets in ihrer *.info.yml-Datei angeben. Die dort aufgelisteten CSS-Ressourcen werden ebenfalls im iframe geladen. Siehe Beispiel im Bartik-Theme. Außerdem siehe die Anleitung Wie man CKEditor mit Ihrem Frontend-Theme in Einklang bringt („WYSIWYG ist eine Lüge“)!
                – CSS-Module
Module, die CSS im Frontend laden, können hook_ckeditor_css_alter() nutzen, um auch dieses CSS in CKEditor-iframe-Instanzen zu laden.

CKEditor Plugins

Fügen Sie dem CKEditor mehr Funktionalität hinzu!

\Drupal\ckeditor\CKEditorPluginInterface: Drupal-Plugins, die 1:1 CKEditor-Plugins entsprechen, sodass Drupal über verfügbare CKEditor-Plugins Bescheid weiß. Daraus ergibt sich der – auf den ersten Blick verwirrende – Name „CKEditor Plugin Plugins“, aber es macht tatsächlich Sinn!

• Es gibt vier zusätzliche Interfaces, die Sie implementieren können

              1. \Drupal\ckeditor\CKEditorPluginButtonsInterface ermöglicht es einem CKEditor-Plugin, die Buttons zu definieren, die es bereitstellt, sodass Benutzer die CKEditor-Toolbar-Instanz über eine Drag-and-Drop-Oberfläche konfigurieren können.
Beispiel: \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo stellt einen Toolbar-Button (sogar eine Dropdown-Liste) bereit.
              2. \Drupal\ckeditor\CKEditorPluginContextualInterface ermöglicht es einem CKEditor-Plugin, sich automatisch kontextabhängig zu aktivieren: wenn ein Button eines anderen CKEditor-Plugins aktiviert ist, ein bestimmter Filter aktiviert ist, eine Einstellung eines CKEditor-Plugins einen bestimmten Wert hat oder eine Kombination davon.
Beispiel: \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption aktiviert sich selbst, wenn der Bild-Button vorhanden und der Ausrichtungs- oder Caption-Filter aktiviert ist.
              3. \Drupal\ckeditor\CKEditorPluginConfigurableInterface ermöglicht es einem CKEditor-Plugin, ein Einstellungsformular für beliebige Konfigurationsparameter dieses Plugins bereitzustellen.
Beispiel: Das Plugin \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo ermöglicht es, konfigurierbare Stile festzulegen.
              4. \Drupal\ckeditor\CKEditorPluginCssInterface seit 8.1.0 ermöglicht es einem CKEditor-Plugin, zusätzliches CSS in CKEditor-iframe-Instanzen zu laden.
Beispiel: Das Plugin \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption lädt zusätzliches CSS.

• Plugin-Implementierungen müssen mit der Annotation @CKEditorPlugin versehen sein, damit sie erkannt werden können.

Dazu gehört die Plugin-ID von CKEditor; die in der Annotation definierte ID muss mit dem Namen des Plugins übereinstimmen, wie er in der JavaScript-Datei des Plugins in der Zeile definiert ist, die das Plugin hinzufügt.

// Die Annotation im PHP-Plugin muss mit dem hier definierten Wert übereinstimmen.
CKEDITOR.plugins.add('pluginId', { ... });

• Die Metadaten der Annotation erkannter Plugins können mit hook_ckeditor_plugin_info_alter() geändert werden.
• \Drupal\ckeditor\CKEditorPluginBase stellt eine Standardimplementierung bereit, sodass CKEditor-Plugins nicht jede Methode selbst implementieren müssen. Das bedeutet, dass es für den häufigsten Fall optimiert ist: Es ist nur für Plugins nützlich, die Buttons bereitstellen.

Zuletzt, aber nicht weniger wichtig: Wenn Sie ein neues Texteditor-Plugin implementieren, möchten Sie vermutlich auch sicherstellen, dass die Benutzererfahrung (UX) für dessen Konfiguration gut funktioniert. Dafür sehen Sie sich die Dateien ckeditor.drupalimage.admin.js und ckeditor.stylescombo.admin.js als Beispiele an. Beachten Sie, dass dieser Aspekt (und nur dieser!) unter https://www.drupal.org/node/2567801 geändert werden kann.

Debugging

Drupal 8 enthält einen anpassbaren, optimierten CKEditor-Build. Siehe core/assets/vendor/ckeditor/build-config.js. Die Dokumentation in dieser Datei erklärt auch, wie Sie den eingebauten CKEditor-Build in Drupal 8 (optimiert für Produktion) durch einen Build ersetzen können, der für die Entwicklung optimiert ist (d.h. unkomprimiert).

Siehe auch

• CKEditor Modul: tief integrierter Texteditor
• Texteditor Modul: Verknüpfung von Hilfseditoren mit Textformaten
• Filter Modul: Textformate, die Benutzereingaben filtern
• Texteditor API
• Drupal 8: Besseres strukturiertes Inhaltserstellungserlebnis?
• CKEditor in Drupal 8: Site Builder und Entwickler Fragen & Antworten
• Tutorial: Erweiterte Funktionalität für den Basis-CKEditor in Drupal 8 erstellen
• Tutorial: Wie man CKEditor mit Ihrem Frontend-Theme in Einklang bringt („WYSIWYG ist eine Lüge“)
• Zur Entwicklung von CKEditor Widget Plugins: Einführung in Widgets
• Liste der CKEditor-bezogenen Module für Drupal 8