Zur Bearbeitung der meisten Inhalte mit individueller Formatierung wird der TinyMCE-Editor eingesetzt. Der Editor ist für Contao bereits vorkonfiguriert, aber eine individuelle Konfiguration ist optional möglich.
Deine individuelle Konfiguration erfolgt über das Template be_tinyMCE.html5. Hier findest du die von Contao gesetzte
Konfiguration vor und kannst die Angaben updatesicher anpassen.
Erstelle über den Navigationsbereich
»Layout« unter »Templates« ein neues Template.
Wähle über Original-Template das Template be_tinyMCE.html5 aus und gebe als Zielverzeichnis das Hauptverzeichnis an.
Das Template muss im Hauptverzeichnis (templates/be_tinyMCE.html5) abgelegt werden, da das Backend von Contao das
Template nur dort findet. Alle Zeilen innerhalb von <script>...</script> bis auf die letzte Zeile müssen mit einem
Komma abgeschlossen werden. Nach dem Speichern des Templates werden deine Änderungen sofort übernommen.
Seit Contao 4.10 kann Template Vererbung benutzt werden, um nur Teile
des Standard be_tinyMCE Templates nach den eigenen Bedürfnissen anzupassen.
Wenn du den Template Namen be_tinyMCE.html5 beibehältst führt dies dazu, dass deine Änderungen sich auf alle Bereiche
auswirken die den Editor benutzen. Dies gilt zumindest für die Contao eigenen Komponenten.
Du möchtest gezielt eine Editor-Konfiguration z. B. nur für das Inhaltselement vom Typ »Text« erstellen? Dazu kannst
du das Template beliebig umbenennen: z. B. nach be_myTinyMCE.html5.
Als nächstes müssen wir Contao dazu bringen dieses Template zu nutzen. Dazu muss folgendes in die contao/dca/tl_content.php
eingefügt werden:
// contao/dca/tl_content.php
// Custom RTE-Configuration for Content Text
$GLOBALS['TL_DCA']['tl_content']['fields']['text']['eval']['rte'] = 'myTinyMCE';
Der letzte Eintrag entspricht der Template Bezeichnung (ohne be_ Präfix). In unserem Fall myTinyMCE. Im Anschluß musst du über
den Contao-Manager (»Systemwartung« > »Prod.-Cache erneuern«) oder über die Konsole einmalig den Anwendungs-Cache leeren.
Analog wäre die Vorgehensweise z. B. für deine Nachrichten Texte mit einem Template be_myTinyMCENews und
einer tl_news.php:
// contao/dca/tl_news.php
// Custom RTE-Configuration for News Text
$GLOBALS['TL_DCA']['tl_news']['fields']['text']['eval']['rte'] = 'myTinyMCENews';
Eine Einführung zum Contao Data Container Array findest du unter Adjusting the DCA
und die detaillierte Referenz unter Data Container Array in der Entwickler-Dokumentation.
Welche Version des Editors herangezogen wird kannst du der aktuellen Contao composer.json entnehmen. Abhängig von der jeweiligen TinyMCE-Version findest du die Infos zur weiteren Konfiguration in der TinyMCE-Dokumentation.
Falls etwas nach deinen Änderungen nicht funktionieren sollte entferne diese zunächst wieder. Du kannst auch das Template löschen. Es wird dann wieder die Contao-Standardkonfiguration des Editors benutzt.
Im Bereich »Einstellungen > Sicherheitseinstellungen« kannst du Erlaubte HTML-Tags definieren. Es kann vorkommen, dass diese Angaben allein nicht ausreichen.
Falls du beispielsweise mit verfügbaren »Font-Awesome« das Contao-Logo in einem Inhaltselement vom Typ »Aufzählung« wie folgt einsetzt, werden deine Angaben nach dem »Speichern« nicht übernommen.
<i class="fa fa-contao" aria-hidden="true">Contao Logo</i>
Auch wenn das HTML-Element <i> bereits im Bereich Erlaubte HTML-Tags
berücksichtigt wird, musst du dies zusätzlich für den TinyMCE freigeben. Ergänze hierzu im Template die Zeile
beginnend mit »extended_valid_elements«:
// be_tinyMCE.html5
extended_valid_elements: 'q[cite|class|title],article,section,hgroup,figure,figcaption,i[class]/em',
Anschließend musst du über den Contao-Manager (»Systemwartung« > »Prod.-Cache erneuern«) oder über die Konsole den Anwendungs-Cache leeren, deine HTML-Angabe im Inhaltselement erneut eintragen und »Speichern«.
Im Editor kannst du über das Menü Bearbeiten oder über eine Tastenkombination Text aus der Zwischenablage einfügen.
Hierbei kann es passieren, dass nicht nur der Text sondern auch weitere Formatierungen (z. B. aus einer Word Datei) übernommen
werden. Damit nur Text eingefügt wird kannst du über das Menü die Option Bearbeiten > Als Text einfügen manuell auswählen.
Über die Konfiguration werden wir die Option standardmäßig aktivieren. Diese Funktion des Editors erfolgt über das Paste
-Plugin und die möglichen Einstellungen findest du in der
Dokumentation. Wir müssen demnach die
Angabe paste_as_text im Template hinzufügen:
// be_tinyMCE.html5
...
toolbar: 'link unlink | image | formatselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | code',
// activate paste_as_text option
paste_as_text: true
Im Beispiel haben wir dies über eine neue Zeile unterhalb der bestehenden Zeile (toolbar: …) eingetragen. Da unsere neue Zeile die letzte Zeile ist, brauchen wir hier kein Komma setzen.
Allerdings musst du darauf achten, dass die bestehende Zeile (toolbar: …) nun zusätzlich mit einem Komma abgeschlossen
werden muss. Im Editor ist die Option Bearbeiten > Als Text einfügen jetzt immer aktiviert.
Die Toolbar des Editors bietet u. a. die Möglichkeit der Absatz Ausrichtung. Wenn du dies für deine Redakteure
unterbinden möchtest entferne die Einträge alignleft aligncenter alignright alignjustify in der toolbar Definition:
// be_tinyMCE.html5
...
// custom toolbar settings
toolbar: 'link unlink | image | formatselect | bold italic | bullist numlist outdent indent | code',
// activate paste_as_text option
paste_as_text: true
ab 5.0 Ab Contao 5 verwendet Contao den TinyMCE-Editor in der Version 6. Hier ändern sich einige Begriffe für die Anzeige von Elementen in der Toolbar. Verwende z. B. blocks statt formatselect und styles statt styleselect. Eine vollständige Liste der geänderten Begriffe findest Du in den Migrationshinweisen der TinyMCE Dokumentation.
Analog zur Toolbar kannst du auch das Menü konfigurieren. Wenn du den Menüpunkt Tabelle vollständig entfernen
möchtest lösche den Eintrag table in der Zeile der Menübar Definition (menubar:...).
Zur gezielten Kontrolle einzelner Menüpunkte steht die menu Definition zur Verfügung. Die detaillierten Infos hierzu
findest du in der TinyMCE-Dokumentation.
Wir haben in der Toolbar die Absatz Ausrichtung entfernt. Allerdings ist diese noch im Menü unter Format > Ausrichtung
erreichbar. Wir möchten gezielt diesen Menüpunkt entfernen und die übrigen Menü-Einträge beibehalten. Hierzu kannst
du den Eintrag removed_menuitems benutzen.
Eine vollständige Liste der Toolbar-Items und Menü-Items findest du in der TinyMCE-Dokumentation.
ab 5.0 Ab Contao 5 verwendet Contao den TinyMCE-Editor in der Version 6. Hier ändern sich einige Begriffe für die Anzeige von Elementen im Menü. Verwende z. B. blocks statt blockformats und fontsize statt fontsizes. Eine vollständige Liste der geänderten Begriffe findest Du in den Migrationshinweisen der TinyMCE Dokumentation.
// be_tinyMCE.html5
...
// removed table menu
menubar: 'file edit insert view format',
// remove align settings from format menu
removed_menuitems: "align",
// custom toolbar settings
toolbar: 'link unlink | image | formatselect | bold italic | bullist numlist outdent indent | code',
// activate paste_as_text option
paste_as_text: true
Du möchtest eigene Format-Definitionen zur Auswahl anbieten? Der TinyMCE-Editor bietet hierzu die Option
style_formats an. Du kannst hierüber z. B. deine Definition auf bestimmte HTML-Selektoren begrenzen,
mit Inline-Style Angaben versehen oder bestimmte CSS-Klassen übergeben.
Du erweiterst die Toolbar mit dem Eintrag styleselect. Über die Toolbar können dann deine eigenen Angaben aus den
style_formats Definitionen ausgewählt werden:
// be_tinyMCE.html5
...
// removed table menu
menubar: 'file edit insert view format',
// remove align settings from format menu
removed_menuitems: "align",
// custom toolbar settings
toolbar: 'link unlink | image | formatselect | styleselect | bold italic | bullist numlist outdent indent | code',
// custom styles
style_formats: [
{title: 'Red Text - Inline Style', inline: 'span', styles: {color: '#ff0000'}},
{title: 'Blue Text - Inline Class', inline: 'span', classes: 'myCssClassA'},
{title: 'Div - Block Class', block: 'div', classes: 'myCssClassB', exact: true, wrapper: true},
{title: 'Table row - Restrict Selector', selector: 'tr', classes: 'myCssClassC'}
],
// activate paste_as_text option
paste_as_text: true
Alle Details über die style_formats Möglichkeiten findest du in der
TinyMCE-Dokumentation.
Lesenswert sind auch die Informationen
über die Format-Parameter wie z. B. exact oder wrapper.
In unserem obigen style_formats Beispiel haben wir im ersten Eintrag den Farbwert über eine inline CSS-Angabe definiert.
Das sollte du möglichst vermeiden und lieber mit CSS-Klassen arbeiten. Möchtest du später den Style z. B. den Farbwert
ändern, kannst du das global über deine CSS-Klasse realisieren.
Der Nachteil ist hierbei, dass du oder deine Redakteure die Styles im Editor nicht sehen können. Hierzu kannst du dem
Editor deine eigene CSS-Datei über die content_css Angabe zur Verfügung stellen.
Wir erstellen uns unterhalb des files-Ordner in einem öffentlichen Verzeichnis die Datei myCustomTiny.css:
// files/myfolder/myCustomTiny.css
.myCssClassA {
color: #0000ff;
}
.myCssClassB {
color: #ffffff;
background-color: #ff0000;
}
Die hier angegebenen CSS-Klassen entsprechen den style_formats Definitionen. Die Angabe content_css existiert
bereits im Template. Du kannst den bestehenden Eintrag mit deiner eigenen CSS-Datei vollständig ersetzen oder du
fügst deine CSS-Datei hinzu:
// be_tinyMCE.html5
...
//content_css: 'system/themes/<?= Backend::getTheme() ?>/tinymce.min.css',
// add new custom css file
content_css: [
'system/themes/<?= Backend::getTheme() ?>/tinymce.min.css',
'files/myfolder/myCustomTiny.css'
],
Wählst du im Editor deine Format-Definition aus wird diese auch so angezeigt. Allerdings werden nun in der Toolbar unsere CSS-Klassen aus der CSS-Datei zusätzlich aufgeführt. Dies ist nicht erwünscht. Mit einem kleinen Trick können wir das verhindern.
Die Option importcss_selector_filter ist eigentlich dazu gedacht die Anzeige auf bestimmte Bezeichnungen zu begrenzen. Die
Informationen findest du in der TinyMCE-Dokumentation.
Wir verwenden dies in unserem Sinne und geben einen Filter an der gar nicht existiert:
// be_tinyMCE.html5
...
//content_css: 'system/themes/<?= Backend::getTheme() ?>/tinymce.min.css',
// add new custom css file
content_css: [
'system/themes/<?= Backend::getTheme() ?>/tinymce.min.css',
'files/myfolder/myCustomTiny.css'
],
// do not import all css-classes from custom .css, only classes starts with prefix
importcss_selector_filter: ".myDummyPrefix-",
In der Toolbar werden jetzt wieder nur unsere eigenen Format-Definitionen entsprechend den style_formats Angaben angezeigt.
Wenn du also eigene Format-Definitionen im Editor zu Verfügung stellst, solltest du möglichst auch eine eigene CSS-Datei einbinden. Die CSS-Datei kann darüber hinaus auch weitere Styles beinhalten die du für das eigentliche Layout deiner Webseite benutzt.
Allerdings kann das sehr schnell aufwendig werden. Bei dieser Vorgehensweise musst du abwägen was du in welchem Umfang zur Verfügung stellen möchtest.
Die offizielle Dokumentation ist auf www.tiny.cloud zu finden - bitte die passende Version aus der linken Navigation auswählen. In Contao 4 ist bis 4.9 die Version 4 des TinyMCE als Standard eingebunden und ab 4.10 die Version 5.
Nicky Hoff hat zur Contao-Konferenz 2018 einen Vortrag zu dem Thema gehalten - dazu gibt es Folien und ein Video.
In der Contao-Erweiterungsliste gibt es einige Pakete, mit denen sich leicht weitere Funktionen einbauen lassen extensions.contao.org