Wie füge ich CKEditor5 Plugins in TYPO3 12 ein?

TYPO3 12 revolutioniert das Content Management mit der Einführung von CKEditor5 als Nachfolger des bewährten CKEditor4. Diese bahnbrechende Veränderung verspricht nicht nur eine modernere Benutzeroberfläche, sondern auch erweiterte Funktionen, die die Content-Erstellung und Bearbeitung auf ein neues Niveau heben.

Die mitgelieferte CKEditor-Version in TYPO3 12 ist maßgeschneidert, jedoch fehlen möglicherweise einige Plugins. Keine Sorge, wir zeigen, wie du fehlende CKEditor-Plugins problemlos nachinstallierst.

Hier kommt die Schritt-für-Schritt-Anleitung für die nahtlose Integration zusätzlicher Funktionen in deinen TYPO3-Editor. Let's enhance your TYPO3 experience!

Hinweis

TYPO3 liefert bereits eine umfangreiche Anzahl an CKEditor 5 Plugins mit. Darunter auch das CodeBlock Plugin. Hierzu müsst ihr kein Build Tool einrichten. Es reicht wenn ihr die Plugins per Yaml Datei einbindet. Wie das funktioniert zeige ich euch hier.

Öffnet eure CKEditor.yaml und ergänzt folgendes. Mehr Infos zur Yaml Datei findet ihr weiter unten.

editor:
  config:
    importModules:
      - { 'module': '@ckeditor/ckeditor5-code-block', 'exports': [ 'CodeBlock' ] }

    extraPlugins:
      - Code
      - CodeBlock

    toolbar:
      items:
        - code
        - codeBlock
    
    codeBlock:
      languages:
        - { language: 'plaintext', label: 'Plain text' }
        - { language: 'php', label: 'PHP' }
        - { language: 'sql', label: 'SQL' }
        - { language: 'yaml', label: 'YAML' }
        - { language: 'json', label: 'JSON' }
        - { language: 'css', label: 'CSS' }
        - { language: 'scss', label: 'SCSS' }
        - { language: 'javascript', label: 'JavaScript' }
        - { language: 'typescript', label: 'TypeScript' }
        - { language: 'shell', label: 'Shell' }
        - { language: 'xml', label: 'XML' }
        - { language: 'nginx', label: 'Nginx' }
        - { language: 'bash', label: 'Bash' }

Wir beschreiben, dass das exportierte Modul CodeBlock aus der Datei @ckeditor/ckeditor5-code-block.js geladen werden soll.

Mehr Infos zu Import Modules findet ihr hier https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

Vorraussetzung

Um den CKEditor 5 in TYPO3 12 zu erweitern brauchen wir eine eigene Extension. In meinem Beispiel heißt diese ext:site_package. Damit unsere Anpassungen auch greifen müssen wir das mitgelieferte "Preset" anpassen. Das geht über die ext_localconf.php. Wir setzen folgendes ein

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:site_package/Configuration/CKEditor/CKEditor.yaml';

Die Datei enthält den kopierten Inhalt von ext:rte_ckeditor/Configuration/RTE/Default.yaml.

Installation der fehlenden Plugins

In diesem Beispiel gehen wir davon aus, dass das CKEditor 5 Plugin font hinzugefügt werden soll um die Plugins FontColor und FontSize nutzen zu können. Außerdem befinden wir uns im Projekt "root" Verzeichnis, außerhalb von der Extension site_package. Falls Ihr den Befehl innerhalb von der Extension durchführt achtet bitte darauf den Ordner node_modules aus eurer Versionskontrolle zu entfernen.

npm install @ckeditor/ckeditor5-font@41.0.0

Hinweis Achtet darauf, dass die Version des Plugins zu der CKEditor Version vom TYPO3 Core passt. Das könnt ihr hier prüfen: github.com/TYPO3/typo3/blob/v12.4.11/Build/package.json

Um das Plugin als ES6 Modul einzusetzen müssen wir es noch zusammen bauen. Dafür nehmen wir rollup.

npm i -D rollup rollup-plugin-import-css rollup-plugin-svg

Wir erstellen uns eine passende rollup.config.js

import { defineConfig } from 'rollup';
import svg from 'rollup-plugin-svg';
import css from "rollup-plugin-import-css";

export default defineConfig({
  input: "node_modules/@ckeditor/ckeditor5-font/src/font.js",
  output: {
    file: "extensions/site_package/Resources/Public/@ckeditor/font.js",
    format: 'esm',
    paths: (id) => {
      if (id.startsWith('ckeditor5')) {      
          return id.replace(/ckeditor5\/src\/([a-z-]+)\.js/, '@ckeditor/ckeditor5-$1')
      }
      return id;
    },
  },
  external: ['@ckeditor'],
  plugins: [svg(), css()]
});

Mit diesem Befehl lässt sich der Build Prozess aufrufen

node node_modules/.bin/rollup -c --bundleConfigAsCjs

Kurz zusammengefasst sagen wir rollup, dass der "input" im "format": esm in die Datei "output" geschrieben werden soll. Außerdem schließen wir durch die Angaben in "external" und "paths" Code und Pfade aus dem Ergebnis aus, die bereits durch den TYPO3 Core geliefert werden. In "plugins" fügen wir noch API's hinzu die im Code die Formate *.svg und *.css verarbeiten können.

Die Extension liegt hier relativ zum Projekt "root" im Verzeichnis "extension" und wird per composer als lokales Paket installiert. 

Einrichten in TYPO3

Um das Plugin nun in TYPO3 nutzen zu können müssen wir noch 2 Anpassungen machen.

Erstelle eine JavaScriptModules.php Datei im Ordner EXT:site_package/Configuration/ mit folgendem Inhalt

<?php

return [
    'dependencies' => ['backend'],
    'tags' => [
        'backend.form',
    ],
    'imports' => [
        '@werkraum/site_package/font.js' => 'EXT:site_package/Resources/Public/@ckeditor/font.js',
    ],
];

Nun muss noch der CKEditor wissen, dass er ein weiteres Plugin laden soll. Dazu bearbeiten wir die Datei EXT:site_package/Configuration/CKEditor/CKEditor.yaml

editor:
  config:
    importModules:
      - '@werkraum/site_package/font.js'

Für die beiden Plugins FontSize und FontColor habe ich zusätzlich diese Einstellungen vorgenommen

editor:
  config:
    importModules:
      - '@werkraum/site_package/font.js'
    toolbar:
      items:
        ...
        - fontSize
        - fontColor
        ...

    fontSize:
      options:
        - default
        - big
        - small

    fontColor:
      colors:
        - {color: '#00908d', label: 'green'}
        - {color: '#a6276f', label: 'lila'}
        - {color: '#f86200', label: 'orange'}
        - {color: '#f62459', label: 'red'}

    extraPlugins:
      - FontSize
      - FontColor

Hinweis: der Prefix "@werkraum" kann frei gewählt werden und ist ähnlich wie beim composer Namespace nicht Teil des Pfads.

Ein besonderer Dank geht an den inspirierenden Artikel von derhansen.de How to create a custom CKEditor 5 plugin for TYPO3 12.4.