TYPO3 RTE API

TYPO3 enthält eine Schnittstelle für die Kommunikation zwischen RTE und Datenbank. Im englischen wird diese Kommunikation als Transfomation bezeichnet, weil diese API-Schnittstelle für die Umwandlung (transformation) von formatiertem Text (RTE) zu unformatiertem Text (DB) und wieder zurück zuständig ist. Ein einfaches Beispiel könnte sein, dass die b-Tags in der Datenbank zu strong-Tags in der RTE konvertiert werden sollen oder dass Verweise zu Bildern im img-Tag als relative Verweise in der Datenbank gespeichert, aber in der RTE als absoluter Verweis angezeigt werden. Eine Transformation muss also in beide Richtungen funktionieren: RTE zur DB und DB zum RTE.

Anmerkung

Der folgende Text ist eine sehr freie Übersetzung der englischsprachigen Originaldokumentation. Diese Übersetzung ist nicht vollständig, da sie nur eine Einführung in die RTE-API mit ein paar zusätzlichen Beispielen sein soll. Den kompletten Text mit allen Konfigurationseinstellungen entnehmen Sie bitte der oben genannten Dokumentation.

Die Transformation

Eine große Herausforderung für die RTEs ist, dass sie nur für eine handvoll Browser, aber hauptsächlich nur für den Internet Explorer, verfügbar sind. Darüber hinaus muss ein RTE auch rückwärtskompatibel mit dem Inhalt aus einer normalen Textarea OHNE Formatierungen sein. Bei den Transformatoren unter TYPO3 gibt es 2 Modi ts_transform und css_transform, mit denen versucht wird, ein Datenformat so lesbar, aber auch die Bearbeitung, so einfach wie möglich zu gestalten.

Die Datenbank

Hier haben wir ein Beispiel, wie der Inhalt in der Datenbank aussehen könnte, nach der Benutzung eines Tranformation-Modus wie z.B. dem css_transform. Wie Sie sehen können, wird der TYPO3-spezifische Tag link für einen Verweis auf die Seite mit der ID 123 verwendet. Dieser Tag wurde für seine Einfachheit entworfen, damit auch Redakteure diese Links einfügen können. Diese werden natürlich zu einem echten a-Tag konvertiert, wenn die Seite im Frontend gerendert wird. Zeile 2 zeigt fetten Text. In Zeile 3 haben wir die Situation, dass der Paragraph (p) zentriert werden soll - und es scheint keine andere Möglichkeit zu geben, als die Zeile in p-Tags mit dem Attribut align zu umgeben. Das ist zwar nicht so besonders leserfreundlich, aber die Programmierer fanden keine bessere Lösung, wenn ein RTE nicht verfügbar ist. Zeile 4 ist einfach nur unformatierter Text.

Im Allgemeinen wird wird dieser Inhalt natürlich vor der Ausgabe auf einer Webseite noch verarbeitet. In der Regel kann man sagen: "Umschließe jede Zeile mit einem p-Tag, welche noch nicht von einem p-Tag umschlossen ist und konvertiere alle TYPO3-spezifischen link-Tags in echte a-Tags." und damit erhält man als Endergebnis eine gültige HTML-Seite.

Dies ist Zeile 1 mit einem internen <link 123>Link</link>
Dies ist Zeile 2 mit einem <b>fetten Part</b> im Text
<p align="center">Diese Zeile ist zentriert.</p>
Ich bin ein einfacher Text

Der RTE

Dank der verschiedenen Transformation-Modi kann der Inhalt in der Datenbank wie normaler Text bearbeitet werden. Aber wenn der Inhalt von oben in den RTE geschickt wird, wird ein Bearbeiten nicht mehr möglich sein, weil jede Zeile nicht von einem p-Tag umschlossen wurde! Dasselbe gilt auch für den link-Tag; Der Inhalt muss so konvertiert werden, dass ihn auch die RTE versteht:

<p>Dies ist Zeile 1 mit einem internen <link 123>Link</link></p>
<p>Dies ist Zeile 2 mit einem <b>fetten Part</b> im Text</p>
<p align="center">Diese Zeile ist zentriert.</p>
<p>Ich bin ein einfacher Text</p>

Dieser Prozess der Konvertierung vom einen Format in das andere Format ist das, was wir als Transformation bezeichnen.

Prozessdarstellung

Von der Eingabe eines Textes bis zur Ausgabe auf der Webseite, durchläuft der Text 6 Schritte, die hier näher erklärt werden:

1. Das RTE-Programm
   • Dies können die verschiedensten RTE-Programme sein (rte, rtehtmlarea, tinyrte, rteekit,...). Völlig egal, ob sie auf DHTML, Active-X, Java, Flash oder was auch immer basieren.
2. RTE spezifische Transformationen
   • Einige RTEs benötigen neben den Haupt-Tranformationen zusätzlich eigene Transformationen des Inhalts. Ein Beispiel hier ist z.B. der RTE rteekit. Dieser benötigt ein komplettes HTML-Dokument für die Bearbeitung von Inhalt und schickt nach dem Abspeichern ein komplettes HTML-Dokument wieder zurück. In diesem Falle muss der RTE-spezifische Transformator sämtliche HTML, HEAD und BODY-Tag hinzufügen bzw. entfernen.
3. Der Haupt-Transformator
   • Der Haupttransformator kümmert sich um die Umwandlung von Inhalt zwischen dem Browserformat für die RTEs und dem Format für die Speicherung in der Datenbank. Das gilt für alle RTEs. In diesem Schritt werden die Link- und Bilderverweise von absoluten nach relativen Pfaden konvertiert.
4. Die Datenbank
   • Hier werden die tranformierten Texte für den Gebrauch im Backend wie auch für das Frontend abgelegt.
5. Webseite generieren
   • Der Inhalt von der Datenbank wird für das Anzeigen auf der Webseite aufbereitet. Je nach Speicherformat muss auch hier eine Transformation am Inhalt durchgeführt werden. Zum Beispiel muss der interne link-Tag wieder in einen HTML a-Tag umgewandelt werden.
6. Die Webseite
   • Jetzt erst wird die von TYPO3 erstellte Webseite angezeigt

Die verschiedenen Transformation-Modi

Die Transformation von Inhalt erfolgt mit dem Auflisten von den Transformation-Modi, die für die Umwandlung zuständig sein sollen. Die Reihenfolge, wie die Modi in der Liste aufgeführt werden, ist auch gleichzeitig die Reihenfolge, die der Inhalt auf dem Weg zur Datenbank nach dem Speichern durchläuft. Der Inhalt wird in umgekehrter Reihenfolge durchlaufen, wenn er wieder in der RTE angezeigt werden soll.

1. ts_transform
   • Wandelt die Tags der Inhaltselemente Text und Text mit Bild um. Dieser Modus ist für das statische Template content(default) optimiert, welches allerdings immer noch den veralteten font-Tag enthält. Dieser Modus ist ein Umwandlungsmodus, der versucht, nur das Minimum an benötigten HTML-Tag in der Datenbank abzuspeichern, damit der Inhalt auch in Textareas ohne RTE weiterhin bearbeitbar bleibt. Ein Beispiel: Ein Text der mit den p-Tags umschlossen ist, wird in der Datenbank als einfache Zeile (ohne p-Tags) mit einem abschließendem Enter (CHR10) abgespeichert.
2. css_transform
   • Genau wie der ts_transform. Allerdings ohne Unterstützung für den font-Tag; dafür unterstützt dieser Modus aber auch die anderen Inhaltselemente. Er basiert auf das aktuellere statische Template css_styled_content.
3. ts_image
   • Überprüft, ob ein Bild eine externe URL enthält. Wenn dem so ist, wird das Bild heruntergeladen und in den Ordner uploads wieder hochgeladen. Die URL zum Bild wird dann in einen relativen Pfad umgewandelt.
4. ts_links
   • Wandelt die Verweise von a-Tags in die TYPO3-speziellen link-Tags um.
5. ts_reglinks
   • Konvertiert absolute Pfade von a-Links in relative Pfade. Der Original a-Tag wird beibehalten.

Zusammenfassung von Modi

• ts
  • Dieser Modus/Gruppierung umfasst folgende Modi:
    • ts_transform
    • ts_preserve (Wird nicht mehr unterstützt)
    • ts_images
    • ts_links

• ts_css
  • Dieser Modus/Gruppierung umfasst folgende Modi:
    • css_transform
    • ts_images
    • ts_links

ts_css ist der neue und moderne Transformationsmodus, der von den meisten RTEs unterstützt wird.

Welche Transformationen jeder Modus im Einzelnen macht, entnehmen Sie bitte der englischsprachigen Originaldokumentation.

Die Konfiguration

Die Konfiguration findet in der page-TS-Config statt. Am besten wählen Sie dazu die root-Seite aus, damit sich die Konfiguration für alle RTEs auf der gesamten Seite auswirken. Nach Änderungen an der TS-Config bitte unbedingt den Cache leeren!

Ein paar Beispiele: Diese Konfiguration deaktiviert den kompletten RTE:

RTE.default.disabled = 1

In diesem Beispiel wird der RTE zwar komplett deaktiviert, aber für Eingaben in das Feld bodytext freigeschaltet:

RTE.default.disabled = 1
RTE.config.tt_content.bodytext.disabled = 0

Das Proc-Objekt

Mit Hilfe dieses Objektes kann man die Transformationen nochmals "finetunen". Welche Tags sind erlaubt? Welche Tags sollen in welche anderen Tags umgewandelt werden? Wie soll mit br-Tags umgegangen werden? und und und...

Hinweis: Da ts_css moderner ist, gehen wir hier nur auf die Optionen ein, die für diesen Modi zur Verfügung stehen. Die Werte hinter den Optionen sind keine Standardwerte, sondern persönliche Empfehlungen. Alle Einstellungen, die im Bereich Proc gemacht werden, werden erst beim Abspeichern bzw. beim Laden in den RTE aktiv und haben nichts mit dem Erscheinungsbild des RTE zu tun.

1. overruleMode = ts_css
   • Kommagetrennte Liste von Transformation-Modi (siehe oben). Meist jedoch ts_css
2. dontConvBRtoParagraph = 1
   • Standartmäßig wird jeder br-Tag zu p-Tags konvertiert. Ein return in die nächste Zeile gibt es also nicht. Deshalb sollte dieser Wert auf 1 gesetzt werden.
3. internalizeFontTags = 0
   • Keine Ahnung. Hat was mit font-Tags zu tun, ob die jetzt außerhalb oder innerhalb von p- und div-Tags stehen sollen. Ich setze es auf 0, da ich eh keine font-Tags verwende.
4. allowTagsOutside = img,hr
   • Tragen Sie die HTML-Tags ein, die auch außerhalb von p- und div-Tags stehen dürfen.
5. allowTags =
   • Es macht keinen Sinn hier sowas wie b,i,u einzutragen in der Hoffnung alle anderen Tags werden verboten. Es gibt eine interne Liste an Tags, die per default hier eingetragen werden: b,i,u,a,img,br,div,center,pre,font,hr,sub,sup,p,strong,em,li,ul,ol,blockquote,strike,span. Evtl. können in dieser Liste weitere/zusätzliche Tags eingetragen werden, die erlaubt werden sollen.
6. denyTags = hr,sub,sup,li,ul,ol,blockquote,strike,center,pre
   • Um aus der oberen Liste bestimmte Tags herauszunehmen, trägt man diese hier ein. Werden diese Tags über HTML eingetragen, werden sie von den Transformatoren direkt wieder gelöscht. Der Inhalt zwischen den Tags bleibt aber weiterhin erhalten.
7. dontRemoveUnknownTags_db = 0
   • Gerade beim Kopieren von Inhalten aus Word könnten unbekannte HTML-Tag mitkopiert werden. Damit diese unbekannten Tags auf dem Weg zur Datenbank gelöscht werden, lässt man den default-Wert auf 0.
8. allowedFontColors =
   • Grundsätzlich sind alle Farben erlaubt. Wird hier etwas eingetragen (z.B. #FF0000, #00FF00, #0000FF), dann werden alle anderen Farben, die per RTE definiert wurden auf dem Weg zur DB gelöscht und nur die angegebenen "überleben".
9. allowedClasses= roteSchrift,blaueSchrift
   • Grundsätzlich sind alle Klassen (die in der CSS-Datei definiert wurden) erlaubt. Da bei Copy&Paste-Aktionen aus Word heraus schon mal span- und p-Tags mit Klassennamen mitkopiert werden könnten, sollte man sich die Mühe machen, hier alle erlaubten Klassen einzutragen.
10. skipAlign = 0 und skipClass = 0
    • Werden diese Optionen auf eins gesetzt, werden die Attribute align und/oder class aus den p- und div-Tags entfernt. Normalerweise werden p- und div-Tags die ein solches Attribut enthalten unangetstet in die Datenbank geschrieben. Sind die p- und div-Tags leer, werden sie auf dem Web zur Datenbank gelöscht.
11. keepPDIVattribs = style
    • Grundsätzlich werden nur die Attribute align und class erlaubt, alle anderen werden gelöscht. Hier können weitere Attribute wie z.B. style dieser Liste hinzugefügt werden.
12. useDIVasParagraphTagForRTE =
    • Standardmäßig wird der Inhalt von p-Tags umschlossen. Mit dieser Option kann man den Wert auf DIV abändern. Dieser Wert ist nicht boolean, sondern erwartet wie im Beispiel einen String.
13. dontFetchExtPictures = 0
    • Normalerweise werden externe Bilder auf den lokalen Server herunter geladen und in den Ordner uploads kopiert. Dieses Verhalten kann man mit dem Wert 1 abschalten.

HTMLparser

In dem Objekt Proc kann man mit Hilfe des sogenannten HTMLparsers noch mehr "FineTuning" betreiben. So wäre es z.B. möglich dem img-Tag bestimmte Attribute wie width und height zu entfernen. Auf der anderen Seite kann man natürlich auch einem bestimmten Tag zusätzliche Attribute mit einem gewünschten Wert hinzuzufügen oder festlegen, dass alle i-Tag nach em und alle b-Tags zu strong-Tags umgewandelt werden.

Solange ich die deutsche Übersetzung noch nicht angefangen habe, sind die englischen Dokumentationen hier zu finden:

- eng. HTMLparser

- eng. HTMLparser_tags