Standard TagLibs

Folgende TagLib-Tags stehen zur Verfügung. In nicht selbstschließenden Tags sind alle HTML- Tags und -Formatierungen erlaubt. Die Tags können mit den üblichen HTML-Attributen ausgestattet werden, sofern diese für die Ausgabe oder Funktion relevant sind.

Hinweis: Bitte beachten Sie, dass innerhalb von Tag-Definitionen ausschließlich Leerzeichen eingesetzt werden dürfen. Tabs oder Zeilenumbrüche werden nicht erkannt und es kommt u.U. zu Fehlern beim Auslesen der Tag-Definitionen!

1. Core

1.1. Addtaglib

Der Page-Controller des APF ist nach dem HMVC-Pattern entworfen und verwaltet die einzelnen Elemente und Komponenten Ihrer Software in Dokumenten. Jedes dieser Dokumente - auch Knoten genannt - kann weitere Knoten enthalten. Ein Knoten wird im APF durch die Klasse Document und davon erbenden Klassen repräsentiert. Dabei definiert jede Instanz die möglichen Kind-Typen über die interne Liste $this->tagLibs.

Der APF-Parser ist aus Komplexitäts- und Performance-Gründen so entworfen, dass er nur diejenigen Tags innerhalb eines Dokuments verarbeitet, die auch dort als mögliche Kind-Elemente bekannt sind. Möchten Sie einen Tag nutzen, der im aktuellen Dokument noch nicht bekannt ist, können Sie den <core:addtaglib />-Tag nutzen. Der so bekannt gegebene Tag kann unmittelbar danach genutzt werden.

APF-Template
<core:addtaglib namespace="" class="" prefix="" name="" />
Beschreibung der Attribute:
  • namespace: Der Namespace der Tag-Implementierung. (Zeichen: [A-Za-z0-9_-:])
  • class: Der Klassen-Name der Tag-Implementierung. (Zeichen: [A-Za-z0-9_])
  • prefix: XML-Prefix. (Zeichen: [a-z])
  • name: XML-Tag-Name. (Zeichen: [a-z])

Die innerhalb der Klasse zu implementierenden Methoden können der API-Dokumentation oder dem Tutorial Implementierung von Tags entnommen werden. Die Bennenung der Tag-Implementierung kann ab Release 1.16 frei durch das Attribut class definiert werden. Dabei ist es möglich, eine Implementierung mit unterschiedlichen Präfixen und unterschiedlichen Tag-Namen zu registrieren. Diese Funktionalität wird beispielswiese genutzt um die Implementierung des <html:placeholder />-Tags auch innerhalb eines <html:template /> wiederverwenden zu können.

Die Implementierung von eigenen Tags wird empfohlen, wenn Funktionalitäten in mehreren Projekten wiederverwendet werden sollen oder die Funktionalität mit einem (Document-)Controller nicht mehr abgebildet werden können.

1.2. Importdesign

Möchte der Template-Bauer an einer definierten Stelle ein weiteres Document einfügen, so kann der Tag

APF-Template
<core:importdesign namespace="" template="" [incparam=""] [context=""]/>
Beschreibung der Attribute:
  • namespace: Ein mit "::" getrennter Namespace-Pfad. (Zeichen: [A-Za-z0-9_-:])
  • template: Name eines Templates. (Zeichen: [A-Za-z0-9-_])
  • incparam: URL-Parameter der abgefragt wird, welches Template eingebunden werden soll.
  • context: Setzt den Context ab dem durch den Tag erzeugten APF-DOM-Knoten auf den angegebenen Context.

verwendet werden. Wird bei der Definition des Tags ein sog. pagepart-Template definiert, kann ein Template abhängig vom URL-Parameter eingebunden werden. Standard-Parameter ist "pagepart", dieser kann jedoch mit dem optionalen Attribut "incparam" angepasst werden. Beispiel für die Einbindung mit pagepart-Parameter:

APF-Template
<core:importdesign namespace="sites::testsite::pres::templates" template="[pagepart = test]" /> <core:importdesign namespace="sites::testsite::pres::templates" template="[cmsmodule = test]" incparam="cmsmodule" />

Das eingebundene Template erbt automatisch die Eigenschaften des Vater-Objekts. Insbesondere Context und Sprache werden übertragen.

Das Attribut context sollte dann eingesetzt werden, wenn die Notwendigkeit besteht, ein Modul innerhalb einer Applikation mehrmals und mit unterschiedlichen Konfiguration einzusetzen. Dabei sollten die Module durch die Importdesign-Taglib oder eine abgeleitete Klasse eingebunden und mit dem gewünschten Context versort werden. Alle unterhalb des Knotens angelegten APF-DOM-Knoten werden dann mit dem in den Tag-Attributen gesetzten Context versorgt und können wie gewohnt auf die gewünschten Konfigurationen zugreifen.

2. Html

2.1. Placeholder

Um in einem Document-Controller Inhalte dynamisch füllen zu können gibt es den <html:placeholder/>-Tag.

APF-Template
<html:placeholder name="" /> <html:placeholder name="">...</html:placeholder>
Beschreibung der Attribute:
  • name: Name des Platzhalters. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

Um einen Platzhalter mit Inhalt zu füllen kann man in einem Document-Controller folgendes einbauen:

PHP-Code
$this->setPlaceHolder('NameDesPlatzhalters', 'InhaltDesPlatzHalters');

Ab Release 1.17 können für einen Platzhalter zusätzlich eine beliebige Anzahl an Zeichen-Ersetzungen registriert werden. Damit ist es möglich, dynamische Inhalte innerhalb eines Platzhalters über einen Tag oder einen Document-Controller zu ersetzten.

Hierzu stehen Ihnen in der Klasse BaseDocumentController die Methode setStringPlaceHolder() zur Verfügung. Mit dieser lassen sich in einem Platzhalter (Klasse: PlaceHolderTag) beliebige Zeichen-Ersetzungen registrieren. Soll innerhalb eines Platzhalters der Form

APF-Template
<html:placeholder name="name">Mein Name ist {NAME}.</html:placeholder>

der Schlüssel [NAME] mit dem Wert John Doe ersetzt werden, so können Sie folgenden Code verwenden:

PHP-Code
$this->setStringPlaceHolder('name', 'NAME', 'John Doe');

2.2. Getstring

Der Tag <html:getstring/> dient dazu einen Wert aus einer sprachabhängigen Konfigurations-Datei auszulesen und anzuzeigen. So können Sie auf einfache Weise mehrsprachige Anwendungen bauen.

APF-Template
<html:getstring [name=""] namespace="" config="" entry="" />
Beschreibung der Attribute:
  • name: Name des Platzhalters zur Referenz in der getLabel()-Methode (Zeichen: [A-Za-z0-9_-])
  • namespace: Namespace der Konfigurationsdatei. (Zeichen: [A-Za-z0-9_-:])
  • config: Name der Konfigurationsdatei. (Zeichen: [A-Za-z0-9-_])
  • entry: Name des Konfigurations-Offsets. (Zeichen: [A-Za-z0-9-_.])
Bitte beachten Sie, dass das Attribut name erst ab der Version 1.15 in Verbindung mit der Methode getLabel() genutzt werden kann.

Um den Tag verwenden zu können muss dieser in Versionen < 1.15 via

APF-Template
<core:addtaglib namespace="tools::html::taglib" prefix="html" class="getstring" />

eingebunden werden.

Die sprachabhängige Konfigurationsdatei muss jeweils eine Sektion pro Sprache (zweistelliger ISO-Länder-Code) und die verwendeten Konfigurationsschlüssel in den Sektionen enthalten sein. Soll der Tag

APF-Template
<html:getstring namespace="modules::mymodule" config="language.ini" entry="title" />

zur Anzeige eines sprachabhängigen Titels in einem Template genutzt werden, muss die Konfigurationsdatei

Code
/config/modules/mymodule/{CONTEXT}/{ENVIRONMENT}_language.ini

mit dem Inhalt

APF-Konfiguration
[de] title = "Mein Modul" [en] title = "My module"

gefüllt werden.

Seit dem Release 1.15 lassen sich sprachabhängige Werte zusätzlich mit Platzhaltern versehen, die mittels (Document-)Controller zur Ausführungszeit dynamisch gefüllt werden können. Ein Platzhalter definiert sich durch seinen Namen, der durch Klammern eingefasst ist:

Code
{user-name}

Dieser Platzhalter kann später mit dem Schlüssel user-name referenziert werden. Die nachfolgend aufgeführte Sprach-Datei definiert drei Schlüssel, die jeweils einen oder mehrere Platzhalter beinhalten:

APF-Konfiguration
[de] headline = "Dies ist eine {word}" intro.text = "Dies ist ein Text mit {count} Platzhalter." message = "Dies ist eine Nachricht von {user-name}, die am {date} gesendet wurde." ...

Die dort definierten Werte, könnten wie folgt in einem Template genutzt werden:

APF-Template
<h3><html:getstring name="headline" namespace="..." config="..." entry="headline"/></h3> <html:form name="Form"> <p> <form:getstring name="intro-text" namespace="..." config="..." entry="intro.text"/> </p> ... </html:form> <html:template name="Message"> ... <p> <template:getstring name="message" namespace="..." config="..." entry="message"/> </p> </html:template>

Zur Befüllung der Platzhalter stehen nun verschiedene Möglichkeiten zur Verfügung, die im nachfolgend abgebildeten Document-Controller beschrieben sind. Diese nutzen jeweils die Methode getLabel() um die jeweilige Instanz zu beziehen. Diese bietet dann die Methode setPlaceHolder() an, die den Namen und den Wert des Platzhalters entgegen nimmt. Die Methode kann im fluid interface-Stil genutzt werden um mehrere Platzhalter zu setzen:

PHP-Code
class SampleController extends BaseDocumentController { public function transformContent() { // Platzhalter in einem < html:getstring /> direkt im Template füllen: $this->getLabel('headline')->setPlaceHolder('word', 'Überschrift'); // Platzhalter in einem < form:getstring /> im Formular füllen: $form = &$this->getForm('Form'); $form->getLabel('intro-text')->setPlaceHolder('count', 'eine'); // Platzhalter in einem < template:getstring /> in einem Template füllen: $tmpl = &$this->getTemplate('Message'); $tmpl->getLabel('message') ->setPlaceHolder('user-name', 'Hans') ->setPlaceHolder('date', date('d.m.Y H:i:s')); } }
Die Anzahl der Platzhalter pro Schlüssel ist nicht begrenzt. Nicht gesetzte Platzhalter werden bei der Ausgabe nicht ersetzt und erscheinen im Klartext in der Ausgabe.

Diese Beschreibung gilt ebenso für die Tags <form:getstring /> (Formulare) und <template:getstring /> (Kapitel 2.3.3.).

2.3. Template

2.3.1. Basis-Funktionen
Um weitere Elemente für die Ausgabe-Steuerung definieren zu können gibt es so genannte Templates. Diese können innerhalb eines Document-Controllers manipuliert und verarbeitet werden. In einem Template gibt es wiederum Platzhalter, die dynamisch gesetzt werden können.
APF-Template
<html:template name=""> [<template:placeholder name="" />] [<template:addtaglib namespace="" class="" prefix="" name="" />] [<template:getstring namespace="" config="" entry="" />] </html:template>
Beschreibung der Attribute:
  • name: Name des Templates bzw. des Platzhalters innerhalb des Templates. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
Bitte beachten Sie, dass auf Grund der Restriktionen des APF-Parsers das Hinzufügen von bekannten Tags innerhalb des <html:template />-Tags via <template:addtaglib /> erfolgen muss.

Zugriff auf ein Template gewährt die geschützte Methode getTemplate() eines Document-Controllers. Mit Hilfe dieser Funktion kann eine Referenz auf ein Template-Objekt zurückgeliefert werden. Ein typischer Anwendungsfall sieht so aus:

Template:
APF-Template
<@controller namespace="" class="" @> <html:placeholder name="Content" /> <html:template name="MyTemplate"> <template:placeholder name="MyPlaceHolder"> </html:template>
Controller:
PHP-Code
class SampleController extends BaseDocumentController { public function transformContent(){ $tmpl = &$this->getTemplate('MyTemplate'); $tmpl->setPlaceHolder('MyPlaceHolder','MyContent'); $this->setPlaceHolder('Content',$tmpl->transformTemplate()); } }

Hier wird in der XML-Datei ein Document-Controller, ein HTML-Platzhalter und ein Template mit zugehörigem Platzhalter definiert. Im Controller kann man nun mittels der Methoden getTemplate() eine Referenz auf das Template holen und mit setPlaceHolder() den Platzhalter im Template füllen. Anschließend wird das Template transformiert und die Ausgabe in den HTML-Platzhalter mittels setPlaceHolder() eingesetzt. Es ist möglich mehrere Templates auf einer Seite zu platzieren. Oft wird das für die Ausgabe von unterschiedlichen Meldungen bei unterschiedlichen Events eingesetzt.

2.3.2. Template-Erweiterungen

Um die Funktionalitäten innerhalb eines Templates mit weiteren TagLibs erweitern zu können steht der Tag <template:addtaglib /> zur Verfügung. Ähnlich dem <core:addtaglib />- Tag können hier innerhalb eines Templates weitere TagLibs hinzugefügt werden.

APF-Template
<template:addtaglib namespace="" class="" prefix="" name="" />
Beschreibung der Attribute:
  • namespace: Der Namespace der Tag-Implementierung. (Zeichen: [A-Za-z0-9_-:])
  • class: Der Klassen-Name der Tag-Implementierung. (Zeichen: [A-Za-z0-9_])
  • prefix: XML-Prefix. (Zeichen: [a-z])
  • name: XML-Tag-Name. (Zeichen: [a-z])

Ein Beispiel für die Verwendung des XML-Tags ist der TagLib-Tag <[html|template]:getstring /> zum Auslesen und Darstellen eines Strings aus einer Konfigurations-Datei. Siehe hierzu Kapitel 2.3.3.

2.3.3. Getstring

Der Tag <template:getstring /> dient dazu einen Konfigurations-String aus einer sprachabhängigen Konfigurations-Datei auszulesen und anzuzeigen. So können auf einfache Weise mehrsprachige Anwendungen aufgebaut werden.

APF-Template
<template:getstring namespace="" config="" entry="" />
Beschreibung der Attribute:
  • namespace: Namespace der Konfigurationsdatei. (Zeichen: [A-Za-z0-9_-:])
  • config: Name der Konfigurationsdatei. (Zeichen: [A-Za-z0-9-_])
  • entry: Name des Konfigurations-Offsets. (Zeichen: [A-Za-z0-9-_.])

Um das Tag in Versionen < 1.15 verwenden zu können muss dieses via

APF-Template
<template:addtaglib namespace="tools::html::taglib" prefix="template" class="getstring" />

bekannt gegeben werden.

3. Document

3.1. createobject

Der Tag erzeugt aus einer Inhalts-Datei unter dem Ordner ./frontend/content/ einen weiteren Unter-Objektbaum. Die Inhalts-Dateien werden in der Form
Code
c_{LANGCODE}_{NAME}.html
erwartet, wobei
  • LANGCODE für ein zweizeichen Länderkürzel (de, en, it, es, ...) steht und
  • NAME der URL-Name ist.
APF-Template
<doc:createobject requestparam="" defaultvalue="" />
Beschreibung der Attribute:
  • requestparam: URL-Parameter, der angibt, welche Content-Datei gezogen wird. (Zeichen: [A-Za-z0-9])
  • defaultvalue: Default-Wert für den Parameter requestparam.
Um die TagLib verwenden zu können muss diese mit einem
APF-Template
<core:addtaglib namespace="tools::html::taglib" class="CreateDocumentFromFileTag" prefix="doc" name="createobject" />
in der Template-Datei eingebunden werden.

Wird keine zum zu requestparam passende Datei im Ordner gefunden, erwartet der Tag eine Datei mit dem Namen
Code
c_{LANGCODE}_404.html
um anzeigen zu können, dass die gewünschte Seite nicht verfügbar ist. Ist auch diese Datei nicht verfügbar kommt es zu einem PHP-Fehler.

4. Document-Controller

Um einen Controller zu deklarieren muss folgender Tag am Anfang des Templates platziert werden:

APF-Template
<@controller namespace="" class="" @>
Beschreibung der Attribute:
  • namespace: Namespace-Pfad zum Controller. (Zeichen: [A-Za-z0-9:])
  • class: Klassen-Namen des Controllers. (Zeichen: [A-Za-z0-9_])

Die Implementierung des Document-Controllers muss immer vom BaseDocumentController ableiten. Dieser ist bereits im Page-Controller definiert und stellt grundlegende Methode für das Handling von DOM- Objekten bereit. Beispiel hierfür ist die getForm()-Methode, die eine Referenz auf ein Formular zurück gibt.

5. FrontController

Mit dem Release 1.4-18.11.2007 wurde der Tag "<fcon:importdesign />" eingefügt. Dieser unterstützt bei der Implementierung von FrontController-basierten Applikationen und bindet Views auf Grund von Model-Informationen im Sinne des MVC-Pattern ein. Hierzu muss eine eigene Model-Klasse für die aktuelle Applikation oder das eingebundene Modul erstellt werden, aus dem die Informationen für die Einbindung des Views bezogen werden können. Die Steuerung der View-Einbindung wird typischerweise durch eigene FrontController-Actions geregelt, die im Modus prepagecreate (siehe Front-Controller, Kapitel 1.6) ausgeführt wird. Diese kann in der URL enthaltene Parameter an das Model-Objekt weitergeben.

APF-Template
<fcon:importdesign templatenamespace="" modelnamespace="" modelfile="" modelclass="" modelparam="" [sessionsingleton=""] />
Beschreibung der Attribute:
  • templatenamespace: Namespace zum Template-Ordner. (Zeichen:: [A-Za-z0-9:])
  • modelnamespace: Namespace zur Model Klasse. (Zeichen: [A-Za-z0-9:])
  • modelfile: Name der Datei, in der sich die Model-Klasse befindet. (Zeichen: [A-Za-z0-9_])
  • modelclass: Name der Model-Klasse. (Zeichen: [A-Za-z0-9_])
  • modelparam: Model-Parameter, der für die Einbindung des Templates verwendet werden soll. (Zeichen: [A-Za-z0-9_])
  • sessionsingleton: Definiert, ob das Model-Objekt im SINGLETON oder SESSIONSINGLETON Modus vom ServiceManager bezogen werden soll. Ist das Attribut nicht vorhanden oder enthält es einen anderen Wert als true, so wird der SINGLETON Modus verwendet. (Werte: true|false)

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
« 1   »
Einträge/Seite: | 5 | 10 | 15 | 20 |
1
Christian 01.02.2008, 00:45:42
Hinweise zu untenstehendem Kommentar:

1. Zu den TagLibs *:getstring haben sich einige Tippfehler eingeschlichen, die gerade berichtigt wurden.

2. Es gibt drei Varianten zu den *:getstring-Taglibs: <html:getstring />, <template:getstring /> und <form:getstring />. Die ersten beiden müssen jeweils im entsprechenden Gültigkeitsbereich durch <core:addtaglib /> bzw. <template:addtaglib /> für die <template:getstring />-TagLib bekannt gemacht werden.
2
fliegermichl 29.01.2008, 11:11:12
Im Bereich 2.2.3 getstring steht:
Um das Tag verwenden zu können muss die TagLib "core:setattribute" erst via

<template:addtaglib namespace="tools::html::taglib" prefix="template" class="getstring" />

Wie nun? <core:addtaglib> oder <template:addtaglib>?