API CKEditorVérification d'accès + mise en cache

05/07/2025, by Ivan

L’API CKEditor est nouvelle dans Drupal 8.

Notez que cela concerne uniquement l’API du module CKEditor de Drupal 8, et non l’API de la bibliothèque JavaScript CKEditor – pour cela, voir http://docs.ckeditor.com/.

Pour plus d’informations sur ce que fait ce module, consultez la documentation du module Text Editor.

Fonctionnalités de l’API

Classées par ordre de rareté d’utilisation :

Skins CKEditor

Par défaut, CKEditor Drupal 8 utilise le skin Moono. C’est bien pour la plupart des sites car il est assez neutre. Toutefois, certains sites veulent une intégration parfaite, auquel cas vous pouvez installer un autre skin, voire en créer un vous-même.
Pour cela, implémentez 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';
    }
  }
}

CSS dans l’iframe CKEditor

Le CSS chargé dans l’instance iframe CKEditor, par exemple sur /node/add/article (instance CKEditor non inline), peut nécessiter une personnalisation pour que l’iframe corresponde au style du front-end (pour les utilisateurs qui préfèrent le WYSIWYG) ou pour montrer la structure (pour ceux qui préfèrent un éditeur plus assisté).
- CSS du thème front-end
Presque tous les thèmes front-end ont un CSS pour styliser les paragraphes, citations, légendes d’images, etc. Les thèmes front-end doivent donc indiquer aux instances iframe CKEditor de charger le CSS pour tout contenu (texte/markup) que les créateurs de contenu peuvent produire. Ils le font en indiquant la clé ckeditor_stylesheets dans leur fichier *.info.yml. Ces fichiers CSS sont aussi chargés dans l’iframe. Voir l’exemple dans Bartik. Voir aussi le guide Comment faire en sorte que CKEditor corresponde à votre thème front-end (« WYSIWYG est un mensonge »)!
- CSS des modules
Les modules qui chargent du CSS dans l’interface front-end peuvent utiliser hook_ckeditor_css_alter() pour aussi charger ce CSS dans les instances iframe CKEditor.

Plugins CKEditor

Ajoutez plus de fonctionnalités à CKEditor !

\Drupal\ckeditor\CKEditorPluginInterface : plugins Drupal qui correspondent 1:1 aux plugins CKEditor, permettant à Drupal de connaître les plugins CKEditor disponibles. D’où le nom apparemment déroutant : plugins CKEditor Plugin, mais cela a du sens !

Il existe quatre interfaces additionnelles que vous pouvez implémenter :

              1. \Drupal\ckeditor\CKEditorPluginButtonsInterface permet au plugin CKEditor de définir quelles boutons il fournit, afin que les utilisateurs puissent configurer la barre d’outils CKEditor via une interface par glisser-déposer.
Exemple : \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo fournit un bouton de barre d’outils CKEditor (un menu déroulant même).
              2. \Drupal\ckeditor\CKEditorPluginContextualInterface permet au plugin CKEditor de s’activer automatiquement selon le contexte : si un bouton d’un autre plugin est activé, si un filtre est activé, si un paramètre d’un plugin a une certaine valeur, ou une combinaison de tout cela.
Exemple : \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption s’active automatiquement si le bouton Image est présent et si le filtre d’alignement ou de légende est activé.
              3. \Drupal\ckeditor\CKEditorPluginConfigurableInterface permet au plugin CKEditor de définir un formulaire de configuration pour tout paramètre qu’il peut avoir.
Exemple : le plugin \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo permet de configurer les styles applicables.
              4. \Drupal\ckeditor\CKEditorPluginCssInterface (depuis Drupal 8.1.0) permet au plugin CKEditor de définir un CSS additionnel à charger dans les instances iframe CKEditor.
Exemple : le plugin \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption charge un CSS additionnel.

Les implémentations des plugins doivent être annotées avec @CKEditorPlugin pour être détectées.

Cela inclut l’identifiant du plugin CKEditor ; l’identifiant dans l’annotation doit correspondre au nom du plugin tel que défini dans le JavaScript du plugin à la ligne qui ajoute le plugin :

// L’annotation du plugin PHP doit correspondre à ce qui est défini ici.
CKEDITOR.plugins.add('pluginId', { ... });

Les métadonnées des annotations des plugins détectés peuvent être modifiées via hook_ckeditor_plugin_info_alter().
\Drupal\ckeditor\CKEditorPluginBase fournit une implémentation par défaut, donc les plugins CKEditor n’ont pas besoin d’implémenter toutes les méthodes. Cela optimise le cas le plus courant : utile surtout pour les plugins qui fournissent des boutons.

Enfin, lors de l’implémentation d’un nouveau plugin d’éditeur de texte, vous voudrez probablement aussi assurer une bonne UX pour sa configuration. Pour cela, regardez ckeditor.drupalimage.admin.js et ckeditor.stylescombo.admin.js comme exemples. Notez que cet aspect (et uniquement cet aspect !) peut être modifié via https://www.drupal.org/node/2567801.

Débogage

Drupal 8 inclut une version optimisée et configurable de CKEditor. Voir core/assets/vendor/ckeditor/build-config.js. La documentation dans ce fichier explique aussi comment remplacer la version embarquée optimisée pour la production par une version optimisée pour le développement (non empaquetée).

Types de blocs supplémentaires (EBT) – Nouvelle expérience de Layout Builder❗

❗Types de paragraphes supplémentaires (EPT) – Nouvelle expérience Paragraphes

API CKEditorVérification d'accès + mise en cache

Menu

Fonctionnalités de l’API

Débogage

Voir aussi