5. WebTML-Scriptlets

WebTML-Scriptlets sind dynamische Bestandteile eines Textes die während seiner Ausgabe über WebTML berechnet werden. Scriptlets können beispielsweise in Items von Inhaltsdokumenten eingebettet werden um dort dynamische Informationen ausgeben zu können.

So kann ein Scriptlet in den Text eines Items eingebettet werden:



Dieses Scriptlet wird bei der Ausgabe des Items über den Tag <tml:item> durch einen dynamisch berechneten Link ersetzt:



Scriptlets werden bei jeder Ausgabe des Textes, der sie enthält, neu und in Bezug auf den aktuell gültigen Kontext berechnet. Ihre Nutzungsweise entspricht weitestgehend der Nutzung normaler WebTML-Tags in WebTML-Modulen, nur dass sie stattdessen in beliebigen Texten eingebettet werden können, so auch in Items die Bestandteil der Webinhalte und damit der Content-Datenbank sind.

Die Grundsyntax von WebTML-Scriptlets ist:

{@funktion@}

Bei Bedarf kann jedem WebTML-Scriptlet ein Kontextausdruck übergeben werden, in dessen Kontext die Scriptlet-Funktion ausgeführt werden soll:

{@(kontextausdruck)funktion@}

Die Syntax für Kontextausdrücke entspricht der Syntax des Attributes context. Der Ausgangskontext ist dabei der Kontext des Tags, über welchen der Text gerade ausgegeben wird.

Die Berechnung von Scriptlets ist normalerweise nicht aktiviert. Es gibt zwei Ordnungen von Scriptlets die sich im Umfang ihrer Funktionalitäten unterscheiden und deren Unterstützung auf unterschiedliche Weise aktiviert wird.

Scriptlets der ersten Ordnung verfügen über vordefinierte Funktionen zur Anreicherung von Texten mit dynamischen Bestandteilen. Sie werden aktiviert wenn:

• An einem Tag <tml:item> der Richtext-Editor verwendet wird (Attribut editor="rtf"). Der Richtext-Editor benutzt für einige seiner Funktionen selbst Scriptlets.
  
• An einem beliebigen WebTML-Tag das Attribut encode auf "rtf" gesetzt wird.

Scriptlets, welche sich in der Ausgabe dieser Tags befinden werden dadurch automatisch ausgeführt.

Folgende Funktionen stehen zur Verfügung:

{@Metaname@}
{@$Metatyp:Metaname@}Ausgabe eines Metadaten-Feldes im aktuellen Kontext. Verfügbare Typen und Namen sind in der Referenz der WebTML-Metadaten dokumentiert. Wird der Metadaten-Typ inklusive Doppelpunkt ausgelassen so werden Metadaten des Typs "content" ausgegeben.

{@#Itemname@} Ausgabe eines Items im aktuellen Kontext

Führt ein so genanntes Scriptlet-Makro aus. Dies ist eine Spezial-Funktion, die entweder vordefiniert oder benutzerdefiniert ist (siehe weiter unten "Benutzerdefinierte Scriptlets"). Manche Scriptlets unterstützen Parameter die nach einem Doppelpunkt angefügt werden. Wird kein Parameter verwendet so muss auch der Doppelpunkt ausgelassen werden.

Folgende Scriptlet-Makros sind vordefiniert:

{@!div:CSS-Klasse@}
Gibt einen HTML-DIV-Tag der angegebenen CSS-Klasse aus.

{@!_div@} 
Beendet einen HTML-DIV-Bereich über den entsprechenden End-Tag.

{@!filelink:datei@}
{@!filelink:container, datei@}
{@!filelink:container, datei, titel@}
Generiert einen HTML-Link zu einem Dateianhang. Als Parameter werden der Container des Dateianhangs angegeben (Name eines Datei-Containers oder Schlüssel eines Inhaltsdokumentes), Name des Anhangs sowie ein Titel welchen der HTML-Link erhält. Bei Auslassung des Titels wird der Name der Datei als Titel verwendet. Wird zusätzlich der Container-Name ausgelassen so wird die Datei aus dem aktuell im Kontext befindlichen  Inhaltsdokument entnommen.

{@!label:Schlüssel@}
{@!label:Datei, Schlüssel@}
{@!label:Container, Datei, Schlüssel@}
Gibt ein WebTML-Label aus, siehe Tag <tml:label>. Die Parameter Container, Datei und Schlüssel entsprechen den Attributen container, file und key. Die Parameter "Container" und "Datei" können ausgelassen werden um die im WebTML-Tag üblichen Standardwerte zu verwenden.

{@!link@}
{@!link:CSS-Klasse@}
Generiert eine HTML-Link zum aktuell im Kontext befindlichen Inhaltsdokument. Der Titel des Dokumentes wird als Titel des Links ausgegeben. Optional kann als Parameter eine CSS-Klasse für den Link angegeben werden.

{@!span:CSS-klasse@}
Gibt einen HTML-DIV-Tag der angegebenen CSS-Klasse aus.

{@!/span@}
{@!_span@}
Beendet einen HTML-DIV-Bereich über den entsprechenden End-Tag.
/doc-wga40/html/default/dr.webtml.scriptlets.kind1.de.html
Generiert eine URL zum aktuell im Kontext befindlichen Inhaltsdokument.

Scriptlets der zweiten Ordnung beinhalten alle Funktionen der ersten Ordnung, ermöglichen aber darüber hinaus die Ausführung beliebigen TMLScript-Codes im aktuellen Kontext.

Scriptlets der zweiten Ordnung können für Ausgaben des Tags <tml:item> aktiviert werden indem das Attribut scriptlets auf "true" gesetzt wird.

Folgende Syntaxen stehen zur Verfügung

{@= TMLScript-Ausdruck @}
Ausführung eines beliebigen TMLScript-Ausdrucks dessen Ergebnis ausgegeben wird.

{@ TMLScript-Code @}
Ausführung beliebigen TMLScript-Codes, inklusive Steueranweisungen. Wird per "return"-Anweisung ein Ergebnis zurückgegeben so wird dieses ausgegeben.

Seit WGA 4.0.4 besteht die Möglichkeit den "Scriptlet-Sprachschatz" durch benutzerdefinierte Scriptlets zu erweitern. Ein benutzerdefiniertes Scriptlet wird als TMLScript-Modul im Datenbank-Design angelegt. Das Modul muss folgende Voraussetzungen erfüllen:

• Sein Name muss mit "scriptlets:" beginnen (bzw. in einem WGA-Designverzeichnis muss die Moduldatei in einem Ordner "scriptlets" unterhalb des Ordners "scripts/tmlscript" abgelegt werden).
• Der Name hinter ":scriptlets" darf nicht dem Namen eines vordefinierten Scriptlet-Makros entsprechen, wie z.B. "scriptlets:div"
  

Definieren sie im Code des TMLScript-Moduls den TMLScript-Code der berechnet werden soll wenn das Scriptlet ausgeführt wird. Per "return"-Anweisung geben sie das Ergebnis des Scriptlets aus. Legen sie beispielsweise ein TMLScript-Modul "scriptlets:home" an welches einen Link auf das Home-Dokument ihrer Website berechnet:

return '<a href="' + context("name:home").contenturl(null, null) + '">Home</a>';

Das Scriptlet ist sofort bei Speicherung des Moduls verfügbar. Um es zu benutzen verwenden sie die Scriptlet-Makro-Syntax, geben jedoch den Namen ihres TMLScript-Moduls ohne "scriptlets:"-Präfix an, z.B.

Hier geht es zum Home-Dokument: {@!home@}

Ihr Scriptlet kann auch Parameter in der für Scriptlet-Makros üblichen Form empfangen. Diese sind im Scriptlet als WebTML-Variablen "tmlparam1" bis "tmlparam5" verfügbar.