rte_ckeditor
Der CKEditor ist ein sehr umfangreicher und vor allem sehr anpassungsfähiger WYSIWYG Editor (What you see is what you get). Als einer der beliebtesten Editoren, auch in anderen CMS, freuen wir uns diesen Editor seit TYPO3 8.5.0 mit on Board zuhaben. Damit hat die bereits existierende Systemextension EXT:rtehtmlarea
ausgedient.
rte_ckeditor und seine Presets
Seit Einführung in TYPO3 8.5.0 kann der CKEditor mittels pageTSconfig konfiguriert werden. Ab TYPO3 8.6.0 kam die Konfiguration mittels YAML hinzu, die man über sogenannte Presets definiert.
Die Presets
Mittels der Presets könnt ihr eine YAML Datei referenzieren, die die CKEditor Konfiguration beinhaltet. In dieser Konfiguration wird nicht nur der CKEditor konfiguriert, sondern auch die Verarbeitung des Inhalts beim Speichern in die Datenbank und Auslesen von der Datenbank.
Nach Aktivierung der Systemextension rte_ckeditor
stehen euch 3 Presets von TYPO3 zur Verfügung: default
, minimal
und full
. Als TYPO3 Entwickler könnt ihr weitere Presets im TYPO3 System registrieren. Schaut euch dazu mal die ext_localconf.php
vom rte_ckeditor
an:
if (empty($GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'])) {
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['default'] = 'EXT:rte_ckeditor/Configuration/RTE/Default.yaml';
}
if (empty($GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['minimal'])) {
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['minimal'] = 'EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml';
}
if (empty($GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['full'])) {
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['full'] = 'EXT:rte_ckeditor/Configuration/RTE/Full.yaml';
}
Eine Registrierung für ein eigenes Preset könnte z.B. so aussehen:
if (empty($GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['presetNurBodytext'])) {
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['presetNurBodytext']
= 'EXT:my_site_package/Configuration/RTE/PresetNurBodytext.yaml';
}
Falls ihr eigene Presets baut verwendet bitte eigene Preset Namen und überschreibt nicht die von TYPO3.
Dank dieser Presets bedarf es nur einer einzigen Zeile pageTSconfig oder einer Zeile TCA, um bis auf Spaltenebene eine individuelle CKEditor Konfiguration anzuwenden.
Beispiel pageTSconfig
Setzen aller CKEditoren auf das Preset presetGanzeWebseite
RTE.default.preset = presetGanzeWebseite
Speziell für die Spalte bodytext
der Tabelle tt_content
wird statt presetGanzeWebseite
das Preset presetNurSpalteBodytext
verwendet.
RTE.config.tt_content.bodytext.preset = presetNurSpalteBodytext
Beispiel TCA
Folgendes Beispiel klappt nur, wenn für die angegebene Spalte im TCA auch enableRichtext aktiviert wurde.
$GLOBALS['TCA']['tx_news_domain_model_news']['columns']['bodytext']['config']['richtextConfiguration']
= 'presetNurBodytextDerNews';
Priorisierung der Presets
Auf der Suche nach dem zu verwendenden Preset wird folgende Reihenfolge berücksichtigt: von höchster Priorität nach niedrigste Priorität:
- Auslesen des Presets von RTE.config.[Tabellenname].[Spaltenname].types.[Typ].preset
- Auslesen des Presets von RTE.config.[Tabellenname].[Spaltenname].preset
- Auslesen des Presets von TCA richtextConfiguration
- Auslesen des Presets von RTE.default.preset
Wenn kein Preset gefunden, dann verwende Preset: default
Konfiguration mittels pageTSconfig
Die Konfiguration des CKEditors lässt sich wie schon zu rtehtmlarea
Zeiten auch mittels pageTSconfig konfigurieren. Im Preset default
stehen euch üblicherweise die Format-Tags p, h1, h2, h3, h4, h5 und pre zur Verfügung. Mit diesem Einzeiler könnt ihr ein paar Format-Tags entfernen:
RTE.default.editor.config.format_tags = p;h2;h3;h4
Um das Verhalten der Inhalte beim Speichern und Laden des Editors zu beeinflussen stellt euch TYPO3 die proc Eigenschaft zur Verfügung. Hier ein Beispiel, um die Überschrift H4 beim Speichern zu entfernen:
RTE.default.proc {
exitHTMLparser_db = 1
exitHTMLparser_db {
allowTags = p,h2,h3
}
}
Achtet bitte darauf, dass ihr euch im Bereich RTE.default.editor
in der Konfiguration vom CKEditors befindet und ihr die Werte bitte so eintragt, wie ihr Sie in der Dokumentation des CKEditors vorfindet. In meinem Beispiel werden die Format Tags mit Semikolon getrennt. Das ist Vorgabe vom CKEditor. Innerhalb der proc
Eigenschaft befinden wir uns jedoch in einer TYPO3 Konfiguration, in der mehrere Werte üblicherweise mit Komma getrennt werden.
Konfiguration mittels YAML Dateien
Seit TYPO3 8.6.0 lässt sich der CKEditor auch mittels YAML Dateien konfigurieren, die mithilfe der Presets vorkonfiguriert werden müssen. Siehe Erklärung weiter oben. Warum man sich hier allerdings für YAML entschieden hat, erklärt sich mir leider nicht. Ja, es ist übersichtlicher, aber sämtliche in YAML angegebenen Tags werden bei der Verarbeitung durch den YAML-Parser in ein Array umgewandelt. Schön, dass wir dann ein Array haben, aber solange der TYPO3 Core intern die RTE Konfiguration größtenteils noch immer als Sting verarbeitet und Komma separierten Listen benötigt helfen uns die Arrays ziemlich wenig. Hinzu kommt, dass sämtliche Beispiele aus der Dokumentation des CKEditors im JavaScript und JSON Stil sind und man jede Konfiguration erstmal in YAML konvertieren darf. Copy&Paste ist hier nicht.
Erstellen eines eigenen Presets
Diesen Eintrag habe ich in die ext_localconf.php
meines SitePackages gepackt. Alternativ könnt ihr diese Zeile auch in die AdditionalConfiguration.php
packen.
$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['sfGlobalPreset']
= 'EXT:my_site_package/Configuration/RTE/SfGlobalPreset.yaml';
Standard-Preset setzen
Tragt diese pageTSconfig in den Seiteneigenschaften der Rootseite Eurer Webseite ein:
RTE.default.preset = sfGlobalPreset
YAML-Konfiguration erstellen
Hierbei handelt es sich um eine absolut minimalistische Konfiguration. Da hier kaum etwas konfiguriert ist, greift CKEditor und TYPO3 auf diverse Standardeinstellungen zurück. Somit werden mit dieser Konfiguration z.B. Buttons angezeigt, die zwar funktionieren, aber sich das Ergebnis nicht abspeichern lässt, weil ich mittels allowTags
ja nur die 3 Tags erlaube.
Hinweis: Ohne den styleSet-Eintrag wird der CKEditor überhaupt nicht geladen.
processing:
mode: default
exitHTMLparser_db:
allowTags: "p, h2, h3"
editor:
config:
format_tags: "p;h2;h3;h4"
stylesSet: []
YAML Dateien importieren
Falls eure YAML Datei arg groß werden sollte oder ihr mehrere Presets konfiguriert habt, kann es Sinn machen bestimmte Teilbereiche der Konfiguration auszulagern. Nutzt dazu die imports
Eigenschaft innerhalb eurer YAML Datei.
imports:
- { resource: "EXT:my_site_package/Configuration/RTE/Processing.yaml" }
- { resource: "EXT:my_site_package/Configuration/RTE/Plugins.yaml" }
processing:
mode: default
editor:
config:
stylesSet: []
Konfiguration Mischmasch
Ihr kennt jetzt die Presets, die Konfiguration mittels pageTSconfig und YAML. All das lässt sich auch noch kombinieren. Zuallererst wird die Reihenfolge der Preset Prioritäten durchlaufen (siehe oben). Wenn ein Preset gefunden wurde und die dazugehörende YAML-Datei existiert, dann wird diese als Basis geladen. Ab jetzt könnt Ihr mit pageTSconfig diese geladene Konfiguration individuell überschreiben. TYPO3 kombiniert dazu in der Richtext.php
zunächst die Konfiguration aus RTE.default
, überschreibt diese mit der Konfiguration aus RTE.config.[Tabellenname].[Spaltenname]
und überschreibt diese Konfiguration dann nochmals, sofern vorhanden, mit der Konfiguration aus RTE.config.[Tabellenname].[Spaltenname].types.[type]
.
Im Backend habt ihr über das Info-Modul nur Zugriff auf die RTE Konfiguration, die ihr über pageTSconfig erzeugt habt. Eine vollständig kombinierte Fassung aller Einstellungen inkl. der aus den YAML-Dateien ist leider nicht möglich.
CKEditor Konfiguration nach YAML migrieren
Ich habe auf der CKEditor Webseite einen Konfigurator gefunden, mit dem ihr euch den CKEditor zusammen klicken könnt. Sie kann zwar nicht 1zu1 in YAML übertragen werden, aber trotzdem nimmt euch das Teil einen Großteil an Arbeit und Sucherei ab.
Beispiel aus dem Konfigurator
CKEDITOR.editorConfig = function( config ) {
config.toolbar = [
{ name: 'document', items: [ 'Source' ] },
{ name: 'basicstyles', items: [ 'Bold', 'Italic', 'Underline' ] },
{ name: 'paragraph', items: [ 'NumberedList', 'BulletedList', '-', 'JustifyLeft', 'JustifyRight' ] },
'/',
{ name: 'styles', items: [ 'Styles', 'Format' ] },
{ name: 'about', items: [ 'About' ] }
];
};
Migrierte Fassung für YAML
Grob muss somit die erste und letzte Zeile weg und dann interessiert uns nur noch der Wert hinter dem config.
. Dann noch alle Anführungszeichen weg und schon haben wir eine YAML Fassung der CKEditor Konfiguration:
editor:
config:
toolbar:
- { name: document, items: [ Source ] }
- { name: basicstyles, items: [ Bold, Italic, Underline ] }
- { name: paragraph, items: [ NumberedList, BulletedList, -, JustifyLeft, JustifyRight ] }
- '/'
- { name: styles, items: [ Styles, Format ] }
- { name: about, items: [ About ] }
Beispiele für CKEditor Konfiguration
Die wichtigsten Einstellungen, um den CKEditor zu konfigurieren, findet ihr in der CKEditor Dokumentation (englisch). Theoretisch sollten sich alle dort aufgeführten Einstellungen in die YAML Konfiguration umbauen lassen.
contentsCss
Anstatt mithilfe von stylesSet
für jeden einzelnen Eintrag, ob Überschrift, Fließtext oder Vorformattiert (pre), könnt ihr auch eine CSS Datei definieren. Wenn ihr in dieser CSS Datei nur eine CSS Klasse definiert, dann kann diese Klasse jedem HTML-Tag zugewiesen werden. Definiert ihr eine CSS Klasse jedoch so, dass sie nur einem bestimmten HTML-Tag zugewiesen ist, dann kann auch im CKEditor diese Klasse nur dem entsprechenden HTML-Tag zugewiesen werden.
editor:
config:
contentsCss: "EXT:my_site_package/Resources/Public/Css/CkEditor.css"
justifyClasses
Angabe von exakt 4 CSS Klassennamen in folgender Reihenfolge: Links, Zentriert, Rechts, Blocksatz
editor:
config:
justifyClasses:
- text-left
- text-center
- text-right
- text-justify
removeButtons
Hiermit könnt ihr einzelne Buttons entfernen. Bei Entfernung mehrerer Buttons macht es evtl. mehr Sinn das CKEditor Plugin zu deaktivieren als diese Eigenschaft völlig auszureizen
editor:
config:
removeButtons:
- Subscript
- Superscript
stylesSet
Mit stylesSet könnt ihr das Aussehen der Schrift in den Selectboxen und auch im Text selbst gestalten und die Vorgaben aus contentsCss individuell überschreiben.
editor:
config:
stylesSet:
- { name: "Ich bin fett", element: "strong" }
- { name: "Ich bin schräg", element: "em", styles: { color: "blue" } }
- { name: "Ich bin zerstochen", element: "strike", attributes: { class: "strike" } }