CKEditor-API

03/10/2025, by Ivan

CKEditor API is nieuw in Drupal 8.

Let op: dit geldt alleen voor de API van de Drupal 8 CKEditor-module, niet voor de API van de CKEditor JavaScript-bibliotheek – zie daarvoor http://docs.ckeditor.com/.

Voor meer details over wat deze module doet, zie de documentatie van de Text Editor-module.

Kenmerken van de API

Geordend van minst gebruikt naar meest gebruikt:

CKEditor skins

CKEditor in Drupal 8 gebruikt standaard de Moono-skin. Dit is geschikt voor de meeste sites, omdat het een vrij neutrale skin is. Sommige sites willen echter een perfecte integratie, en in dat geval kun je een andere skin installeren – eventueel zelfs een skin die je zelf maakt.
Om dit te doen, implementeer je 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

De CSS die wordt geladen in een CKEditor iframe-exemplaar, bijvoorbeeld op /node/add/article (dus een CKEditor-exemplaar dat niet inline is), moet soms worden aangepast zodat de iframe-editor overeenkomt met de front-endstijl (voor wie WYSIWYG verkiest) of de structuur toont (voor wie een puur ondersteunende teksteditor prefereert).
- Front-end thema CSS
Vrijwel elk front-end thema heeft CSS om paragrafen, citaten, bijschriften bij afbeeldingen enz. te stijlen. Daarom moeten alle front-end thema’s aangeven dat hun CKEditor iframe-instanties dezelfde CSS voor content laden die auteurs kunnen maken. Dit kan door het sleutelwoord ckeditor_stylesheets in hun *.info.yml-bestand te gebruiken. De daar vermelde CSS-bestanden worden dan ook in de iframe geladen. Zie voorbeeld in Bartik. Zie ook de gids Hoe CKEditor af te stemmen op je front-end thema (“WYSIWYG is een leugen”)!
- Module CSS
Modules die CSS in de front-end laden, kunnen hook_ckeditor_css_alter() gebruiken om diezelfde CSS ook in CKEditor iframe-instanties te laden. Zie hook_ckeditor_css_alter().

CKEditor plugins

Voeg extra functionaliteit toe aan CKEditor!

\Drupal\ckeditor\CKEditorPluginInterface: Drupal-plugins die 1-op-1 overeenkomen met CKEditor-plugins, zodat Drupal weet welke CKEditor-plugins beschikbaar zijn. Vandaar de enigszins verwarrende naam: CKEditor Plugin-plugins, maar het klopt wel!

Er zijn vier extra interfaces die je kunt implementeren:

\Drupal\ckeditor\CKEditorPluginButtonsInterface laat een plugin de knoppen definiëren die beschikbaar zijn, zodat gebruikers via de drag-and-drop interface de CKEditor-toolbar kunnen aanpassen.
Voorbeeld: \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo voegt een toolbar-knop (dropdown) toe.
\Drupal\ckeditor\CKEditorPluginContextualInterface laat een plugin zichzelf inschakelen afhankelijk van context: bv. of een andere knop actief is, of een filter aanstaat.
Voorbeeld: \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption activeert zichzelf als de Image-knop en het uitlijnings-/caption-filter aanwezig zijn.
\Drupal\ckeditor\CKEditorPluginConfigurableInterface laat een plugin een configuratieformulier bieden.
Voorbeeld: \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo laat toe in te stellen welke stijlen beschikbaar zijn.
\Drupal\ckeditor\CKEditorPluginCssInterface (sinds 8.1.0) laat een plugin extra CSS toevoegen in iframe-instanties.
Voorbeeld: \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption voegt extra CSS toe.

Implementaties moeten worden geannoteerd met @CKEditorPlugin, zodat ze ontdekt kunnen worden.

De plugin-ID die in de annotatie staat, moet exact overeenkomen met de ID zoals gedefinieerd in de JavaScript van de plugin:

// De annotatie in PHP moet overeenkomen met wat hier gedefinieerd is.
CKEDITOR.plugins.add('pluginId', { ... });

Metadata van gevonden plugins kan worden aangepast met hook_ckeditor_plugin_info_alter().
\Drupal\ckeditor\CKEditorPluginBase biedt een standaardimplementatie, zodat niet elke plugin alle methodes moet implementeren. Dit is vooral handig voor plugins die alleen knoppen toevoegen.

Tot slot: als je een nieuwe plugin voor de teksteditor maakt, wil je waarschijnlijk ook zorgen dat de UX voor de configuratie goed werkt. Bekijk ckeditor.drupalimage.admin.js en ckeditor.stylescombo.admin.js als voorbeelden. Dit aspect kan worden gewijzigd via https://www.drupal.org/node/2567801.

Debugging

Drupal 8 bevat een aangepaste geoptimaliseerde build van CKEditor. Zie core/assets/vendor/ckeditor/build-config.js. De documentatie in dat bestand legt ook uit hoe je de ingebouwde productie-build kunt vervangen door een ontwikkel-build (niet-gecomprimeerd).

Extra Block Types (EBT) - Nieuwe Layout Builder ervaring❗

❗Extra Paragraph Types (EPT) - Nieuwe Paragraphs ervaring

Menu

Kenmerken van de API

Debugging

Zie ook