SideBarMenu

Der Wysiwyg-Editor in Stud.IP

Allgemeines

Seit Stud.IP 3.0 gibt es einen Wysiwyg-Editor in Stud.IP, der zur Eingabe von formatierten Inhalten (Text, Bilder, Links, Tabellen usw.) verwendet werden kann. Der Wysiwyg-Editor ersetzt HTML-Textfelder durch eine grafische Oberfläche, die gängigen Textverarbeitungssystemen ähnelt (z.B. LibreOffice). Das Akronym WYSIWYG steht für "What You See Is What You Get", auf Deutsch: "Was Du siehst, ist das, was Du bekommst". Die von uns verwendete Komponente ist der ckeditor und kann als Alternative zur Eingabe von Stud.IP-Formatierung verwendet werden. Die hier beschriebenen Funktionen beziehen sich hauptsächlich auf den Stand in Stud.IP 4.0, die Änderungen zu den Vorversionen sind jeweils im Text aufgeführt.

In Stud.IP 3.x wurde in HTML-Inhalten auch noch zusätzlich die Stud.IP-Formatierung ausgewertet. Da das viele Probleme bereitet hat, gilt ab Stud.IP 4.0 generell: Inhalte im System sind entweder klassische Stud.IP-Formatierung oder HTML-Inhalte aus dem Wysiwyg-Editor. Es gibt keine Vermischung: Stud.IP-Formatierung wird in mit dem Editor erstellten Inhalten nicht ausgewertet (mit Ausnahme spezieller Markup-Plugins) und HTML-Inhalte werden in Stud.IP-Formatierung nicht ausgewertet.

Konfiguration

Der Editor kann systemweit über die Einstellung WYSIWYG in der globalen Konfiguration eingeschaltet werden. Dabei ist zu beachten, daß mit dem Editor erstellte Inhalte als HTML in der Datenbank landen, die beim Ausschalten des Editors zurückbleiben. Wenn der Editor systemweit eingeschaltet ist, wird er standardmäßig für alle Nutzer angeboten - diese können ihn aber für sich individuell wieder deaktivieren. Es gibt also aus Entwicklersicht keine Garantie, daß bei systemweit aktiviertem Editor auch tatsächlich alle neu erstellten Inhalte in HTML vorliegen. Daher ist die PHP-API so konstruiert, daß sie mit den verschiedenen Konstellationen weitgehend transparent umgehen kann.

Verwendung

Wenn ein Eingabefeld den Editor verwenden soll, ist dieses mit der CSS-Klasse "wysiwyg" auszuzeichnen (ggf. zusätzlich zu "add_toolbar" für die klassische Formatierungs-Toolbar). Zu beachten ist dabei: Bis zur Version 3.3. von Stud.IP wird der Wysiwyg-Editor auch für Eingabefelder verwendet, die nur mit der CSS-Klasse "add_toolbar" ausgezeichnet sind. Der Inhalt muß für das textarea-Element mit der Funktion wysiwygReady() aufbereitet werden, die analog zu htmlReady() funktioniert, aber ggf. Stud.IP-Formatierung vor dem Bearbeiten in HTML übersetzt. In Stud.IP-Versionen älter als 4.0 ist an dieser Stelle das normale htmlReady() zu verwenden, da es wysiwygReady() hier noch nicht gibt.

Beispiel (Stud.IP 4.0):

<textarea class="add_toolbar wysiwyg" name="content">
    <?= wysiwygReady($content) ?>
</textarea>

Beispiel (Stud.IP 3.x):

<textarea class="add_toolbar wysiwyg" name="content">
    <?= htmlReady($content) ?>
</textarea>

Der ensprechende Code im Controller, der die Eingabe entgegennimmt und weiterverarbeitet, sollte die Nutzereingabe durch den HTMLPurifier laufen lassen. Dazu gibt es ab Stud.IP 3.4 die Funktion Studip\Markup::purifyHtml(), die eine entsprechende Filterung vornimmt, sofern die Eingabe tatsächlich HTML ist:

Beispiel (ab Stud.IP 3.4):

$content = Studip\Markup::purifyHtml(Request::get('content'));

Beispiel (bis Stud.IP 3.3):

$content = Request::get('content');

Die Verwendung des Editors für einzeilige Eingabefelder (d.h. <input>) wird derzeit allerdings nicht unterstützt.

Weitere Funktionen der Klasse Studip\Markup

In den allermeisten Fällen sollte die oben beschriebene API ausreichend sein. Für spezielle Einsatzfälle gibt es aber noch weitere Funktionen in der Markup-Klasse, die hier kurz beschrieben sind:

  • Studip\Markup::editorEnabled() [ab Stud.IP 4.0]
    Diese Funktion liefert true zurück, wenn der Editor systemweit und auf Nutzerebene aktiviert ist.
  • Studip\Markup::isHtml($text)
    Diese Funktion liefert true zurück, wenn der übergebene Inhalt von Stud.IP als HTML interpretiert wird.
  • Studip\Markup::markAsHtml($text)
    Markiert einen Inhalt als HTML. Ist der Inhalt bereits entsprechend markiert, wird er nicht verändert.
  • Studip\Markup::purifyHtml($html) [ab Stud.IP 3.4]
    Falls der Inhalt als HTML markiert ist, wird er mit dem HTMLPurifier gefiltert. Andere Inhalte werden nicht verändert.
  • Studip\Markup::markupToHtml($text, $trim = true, $mark = true) [ab Stud.IP 4.0]
    Konvertiert Inhalte aus Stud.IP-Formatierung in HTML, damit diese z.B. im Editor bearbeitet werden können. War der Inhalt bereits HTML, wird er nur durch den HTMLPurifier gefiltert. Normalerweise wird das Resultat auch gleich als HTML markiert, dieses Verhalten kann aber abgeschaltet werden.
  • Studip\Markup::removeHtml($html)
    Entfernt alle HTML-Elemente aus dem Inhalt, z.B. um diesen anschließend wieder ohne Wysiwyg-Editor bearbeiten zu können. Ist der Inhalt kein HTML, wird er nicht verändert.

Beispiel 1: Vordefinierte Inhalte als über den Editor bearbeitbares HTML generieren, z.B. als Vorbelegung für ein Eingabefeld mit Wysiwyg-Editor:

$html = Studip\Markup::markAsHtml('<h1>' . htmlReady($title) . '</h1>');

Beispiel 2: Zusammenfügen von formatierten Inhalten, so daß das Resultat je nach Nutzereinstellung des Editors Text oder HTML ist (ein Beispiel dafür ist das Zusammenfügen einer in Editor erstellen Nachricht mit der Signatur des Nutzers):

if (Studip\Markup::editorEnabled()) {
    $result = Studip\Markup::markupToHtml($part1) . Studip\Markup::markupToHtml($part2);
} else {
    $result = Studip\Markup::removeHtml($part1) . Studip\Markup::removeHtml($part2);
}

Javascript-API

Neben der regulären Javascript-API des ckeditor, die auch in Stud.IP verwendet werden kann (natürlich nur, sofern der Editor aktiviert ist), gibt es noch eine kleine Anzahl von Einstellungen und Hilfsfunktionen in Stud.IP:

  • STUDIP.wysiwyg_enabled [ab Stud.IP 4.0]
    Diese Property ist true, wenn der Editor systemweit aktiviert ist.
  • STUDIP.editor_enabled [ab Stud.IP 4.0]
    Diese Property ist true, wenn der Editor im aktuellen Kontext aktiv ist - d.h. er ist systemweit aktiviert, der Nutzer hat ihn nicht ausgeschaltet und der Editor funktioniert auf dem Client (oder glaubt zumindest, daß er es tut).
  • STUDIP.wysiwyg.isHtml(text)
    Diese Funktion liefert true zurück, wenn der übergebene Inhalt von Stud.IP als HTML interpretiert wird.
  • STUDIP.wysiwyg.markAsHtml(text)
    Markiert einen Inhalt als HTML. Ist der Inhalt bereits entsprechend markiert, wird er nicht verändert.

Beispiel:

posting = jQuery('textarea[name=content]').val();
if (STUDIP.editor_enabled) {
    posting = STUDIP.wysiwyg.markAsHtml(posting);
}

Letzte Änderung am 25.05.2017 20:00 Uhr von eludwig.