Spezielle TagLibs

Auf dieser Dokumentationsseite werden Funktionen des Frameworks besprochen die für spezielle Anwendungsfälle oder komplexere Designs verwendet werden können.

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. Iterator

Das Iterator-Tag wurde in Version 1.6 (final) eingeführt um die Ausgabe von Listen von Objekten oder assoziativen Arrays zu erleichtern. Dazu muss in einer Template-Datei ein Iterator definiert und in einem Controller mit den gewünschten Daten bestückt werden. Die Definition des Tags gestaltet sich wie folgt:

APF-Template
<html:iterator name=""> ... [<iterator:addtaglib namespace="" class="" prefix="" name="" />] [<iterator:getstring namespace="" config="" entry="" />] [<iterator:placeholder name="" />] ... <iterator:item [getter=""]> <item:placeholder [name=""][getter=""] /> [<item:getstring namespace="" config="" entry="" />] [<item:addtaglib namespace="" class="" prefix="" name="" />] </iterator:item> ... </html:iterator>

Dabei ist der Tag <html:iterator /> die Definition des Iterators und <iterator:item /> enthält die optische Beschreibung eines Daten-Elementes. Innerhalb eines Daten-Elementes können beliebig viele Platzhalter (<item:placeholder />) und HTML-Tags definiert werden. Der Name des Platzhalters repräsentiert dabei ebenso den Namen des auszugebenden Attributes einer Klasse, bzw. den Namen des Offset eines assoziativen Arrays. Das optionale Attribut getter des <iterator:item />-Tags definiert den Namen derjenigen Methode, mit deren Hilfe das Attribut aus einem Daten-Objekt ausgelesen werden kann. Im Standard-Fall wird die Methode get() als Get-Methode verwendet.

Beschreibung der Attribute:
  • name (1): Name des Iterators. (Zeichen: [A-Za-z0-9])
  • getter: Name der Methode, mit der Attribute eines Objekts abgerufen werden können. (Zeichen: [A-Za-z0-9_])
  • name (2): Name des Platzhalters. (Zeichen: [A-Za-z0-9])
Das Auslesen eines Attributes eines Objektes kann seit dem Release 1.14 auf zwei Arten stattfinden:
  • Auf Ebene des <iterator:item/>-Tag wird eine für alle Platzhalter gültige Methode definiert. Ist das der Fall, kann innerhalb des <item:placeholder/>-Tags über das Attribut name der Name des Attributes angegeben werden, über den die Eigenschaft des Objekts referenziert wird. Beispiel:
    APF-Template
    <html:iterator name="..."> <iterator:item getter="getProperty"> <item:placeholder name="DisplayName" /> </iterator:item> </html:iterator>
    In dieser Konstellation erwartet das Tag, dass das auszugebende Objekt eine Methode
    PHP-Code
    public function getProperty($name)
    implementiert, die den Wert des Attributes (hier DisplayName) zurück liefert. Dies ist das Standard-Verhalten in allen Releases vor 1.14.
  • Ist keine generische Methode für das Abrufen von Objekt-Eigenschaften vorhanden, kann diese auf der Ebene des <item:placeholder/>-Tag granular für jeden Platzhalter definiert werden. Beispiel:
    APF-Template
    <html:iterator name="..."> <iterator:item> <item:placeholder getter="getDisplayName" /> </iterator:item> </html:iterator>
    In dieser Konstellation erwartet das Tag, dass das auszugebende Objekt eine Methode
    PHP-Code
    public function getDisplayName()
    implementiert, die den Wert des Attributes zurück liefert. Diese Möglichkeit wurde in Release 1.14 eingeführt.
Eine Mischung der der beiden Varianten ist ebenso möglich. Sollte sowohl eine generische als auch eine dedizierte Getter-Methode definiert sein, so wird die lokale bevorzugt.

Um den Iterator verwenden zu können muss das Tag zuerst per

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

im aktuellen Document bekannt gemacht werden.

Vor Release 1.17 musste der für das aktuelle Document zuständige Document-Controller von der Klasse iteratorBaseController, die im Namespace tools::html::taglib::documentcontroller abgelegt ist, erben. Ab Release 1.17 ist die Methode getIterator() bereits im BaseDocumentController enthalten.

Innerhalb des Document-Controllers, kann der Iterator dann wie folgt verwendet werden:

PHP-Code
class ListController extends BaseDocumentController { public function transformContent(){ ... // Referenz auf den Iterator holen $Iterator = &$this->getIterator('...'); // Datencontainer mit einer Liste von Objekten oder assoziativen Arrays fuellen $Iterator->fillDataContainer(...); // Am Ort der Definition ausgeben ... $Iterator->transformOnPlace(); // ... oder den Inhalt in einen Platzhalter einsetzen $this->setPlaceHolder('...',$Iterator->transformIterator()); ... } }
Für die Ausgabe von sprachabhängigen Werten können die Tags <iterator:getstring /> sowie <item:getstring /> verwendet werden. Diese funktionieren analog zum Tag <html:getstring />. Reicht die Funktionalität nicht aus, können per <iterator:addtaglib /> und <item:addtaglib /> eigene Taglibs analog zu <core:addtaglib /> eingebunden werden.

Sollen die Einträge einer Liste/Tabelle durchnummeriert werden, kann innerhalb eines <iterator:item />-Tags ein <item:placeholder />-Tag definiert werden, das den Namen IterationNumber trägt. Beispiel:

APF-Template
<html:iterator name=""> <iterator:item [getter=""]> <item:placeholder name="IterationNumber"> </iterator:item> </html:iterator>

Nutzt man das Iterator-Tag in Verbindung mit dem Pager, sollte die Nummerierung auf einer anderen Seite nicht wieder bei 1 beginnen, sondern fortgesetzt werden. Um dies zu erreichen, muss für den <html:iterator />-Tag das Attribut pager definiert werden. Als Wert muss das page-Attribut den Namen einer Sektion der Pager-Konfigurationsdatei erhalten.

Im folgenden Beispiel würde die Iterator-TagLib die Konfiguration /apps/config/modules/pager/{ENVIRONMENT}_pager.ini aufrufen und die Konfigurations-Werte der Sektion PagerExample verwenden.

APF-Template
<html:iterator name="" pager="PagerExample"> <iterator:item [getter=""]> <item:placeholder name="IterationNumber"> </iterator:item> </html:iterator>

2. Mediastream-Tags

Die Mediastream-Tags ermöglichen es dem Entwickler, Ressourcen zur Gestaltung der GUI direkt im Namespace des Moduls abzulegen und daraus auszuliefern. Hierzu stellt das Framework einerseits eine abstrakte TagLib-Implementierung und einige konkrete TagLibs zur Verfügung, die eine Medien-URL generieren, andererseite eine allgemeingültig verwendbare FrontController-Action, die die adressierten Medien ausliefert.

Um die Tags einsetzen zu können, muss sichergestellt sein, dass für die Action, die mit der Auslieferung betraut ist eine validie Konfiguration für den aktuellen Applikations-Kontext existiert. Die Konfiguration wird dabei unter

Code
/config/tools/media/actions/{CONTEXT}/{ENVIRONMENT}_actionconfig.ini

erwartet. Der Inhalt der Datei kann der nachfolgenden Code-Box entnommen werden:

APF-Konfiguration
[streamMedia] FC.ActionNamespace = "tools::media::actions" FC.ActionClass = "StreamMediaAction" FC.InputClass = "StreamMediaInput" FC.InputParams = ""

Eine Beispieldatei findet sich ebenfalls in der apf-configpack-*-Release-Datei unter tools/media/actions/.

Für den konkreten Einsatz existieren bereits folgende TagLibs:

  • FormMediaInclusionTag: Einsatz innerhalb des html:form-Tags
  • MediaInclusionTag: Einsatz innerhalb einer Template-Datei
  • MediaInclusionTag: Einsatz innerhalb des html:template-Tags

Um das Tag einzusetzen, muss dieses im gewünschten Gültigkeitsbreich mit dem <*:importdesign />-Tag bekannt gemacht werden. Die folgende Code-Box zeigt die Anwendung innerhalb eines Formulars:

APF-Template
<core:addtaglib namespace="tools::form::taglib" class="HtmlFormTag" prefix="html" name="form" /> <html:form name="TestFormular"> <form:addtaglib namespace="tools::media::taglib" class="FormMediaInclusionTag" prefix="form" name="mediastream" /> <img src="<form:mediastream namespace="modules::mymodule::pres::images" filename="phone_icon.png" />" alt="" /> <form:text name="phonenumber" /> <br /> <form:button name="send" value="Absenden" /> </html:form>

Wie dem Beispiel zu entnehmen ist, erwarten die <*:mediastream />-Tags folgende Attribute:

  • namespace: Namespace zur gewünschten Medien-Datei. (Zeichen:: [A-Za-z0-9:])
  • filename: Name der Medien-Datei. (Zeichen: [A-Za-z0-9_.-])
Möchten Sie den Namespace der auszuliefernden Datei zusätzlich beeinflussen um z.B. diese beispielsweise abhängig vom aktuellen Kontext im config-Namespace ablegen zu können, so kann folgende Vorgehenweise gewählt werden:
  1. Ausstatten des Tags mit einer eindeutigen ID:
    APF-Template
    <core:addtaglib namespace="tools::media::taglib" class="MediaInclusionTag" prefix="html" name="mediastream" /> <img src="<html:mediastream namespace="config::modules::mymodule::pres::images" filename="phone_icon.png" id="PhoneIcon" />" alt="" />
  2. Manipulieren des Namespaces im Document-Controller:
    PHP-Code
    class ExampleController extends BaseDocumentController { public function transformContent(){ $mediaStreamTag = &$this->getMediaStreamTagByID('PhoneIcon'); $mediaStreamTag->setAttribute($mediaStreamTag->getAttribute('namespace').'::'.$this->getContext()); } private function &getMediaStreamTagByID($id){ $children = &$this->getDocument()->getChildren(); foreach($children as $objectId => $DUMMY){ if(get_class($children[$objectId]) == 'MediaInclusionTag'){ return $children[$objectId]; } } throw new InvalidArgumentException('No media stream tag contained within the current document!'); } }
  3. Manipulation des Datei-Namens innerhalb eines Templates:
    PHP-Code
    class ExampleController extends BaseDocumentController { public function transformContent() { $FileTemplate = &$this->getTemplate('file'); $mediaStreamTag = &$this->getMediaStreamTagByID('FileIconID', $FileTemplate); $mediaStreamTag->setAttribute('extension', 'png'); $mediaStreamTag->setAttribute('filebody', 'dateinameOhneEndung'); } private function &getMediaStreamTagByID($id, TemplateTag &$template) { $children = &$template->getChildren(); foreach ($children as $objectId => $DUMMY) { if (get_class($children[$objectId]) == 'MediaInclusionTag' && $children[$objectId]->getAttribute('id') == $id ) { return $children[$objectId]; } } throw new InvalidArgumentException('No media stream tag contained within the current template "' . $template->getAttribute('name') . '"!'); } }

Die zur Auslieferung der Bilder eingesetzte Front-Controller-Action StreamMediaAction bietet ab Version 1.14 die Möglichkeit, erlaubte Datei-Typen und deren MIME-Typen explizit zu konfigurieren. Damit ist es möglich die Standard-Werte zu überschreiben um weniger oder mehr Typen zuzulassen. Im Standard-Setup sind folgende Endungen erlaubt:

  • png bzw. image/png
  • jpeg bzw. image/jpg
  • jpg bzw. image/jpg
  • gif bzw. image/gif
  • css bzw. text/css
  • js bzw. text/javascript

Um die vorhandenen Werte neu zu definieren muss die Konfigurations-Datei {ENVIRONMENT}_allowed_extensions.ini unter dem Pfad tools::media::{CONTEXT} angelegt werden. Die erlaubten Endungen können dann in der Form

APF-Konfiguration
[Default] jpg = "image/jpg" xml = "text/xml" psd = "application/psd"

definiert werden.

3. Generischer importdesign-Tag

In komplexeren Applikationen ist es oft notwendig, die durch <*:importdesign />-Tags definierten Views dynamisch füllen zu können. Vielfach möchte der Entwickler in aufwändigeren Strukturen die Informationen des Applikationsmodels verwenden. Um dies uneingeschränkt zu ermöglichen und eine Applikationssteuerung aus der Business-Schicht zu ermöglichen, wurde das Framework mit einem generischen importdesign-Tag ausgestattet, der es erlaubt sowohl den Namen des Templates aus auch den Namespace desselben dynamisch aus einem Model-Objekt zu beziehen.

Die Signatur des generischen Tags gestaltet sich dabei wie folgt:
APF-Template
<generic:importdesign modelnamespace="" modelfile="" modelclass="" modelmode="NORMAL|SINGLETON|SESSIONSINGLETON" namespaceparam="" templateparam="" [getmethod=""] [dependentactionnamespace="" dependentactionname="" [dependentactionparams=""]] />
Den Attributen kommt dabei folgende Bedeutung zu:
  • modelnamespace: Namespace der Model-Klasse. (Zeichen:: [A-Za-z0-9:])
  • modelfile: Name der Model-Datei. (Zeichen: [A-Za-z0-9_])
  • modelclass: Name der Model-Klasse. (Zeichen: [A-Za-z0-9_])
  • modelmode: Instanzierungsmodus des Models. (Erlaubte Werte: NORMAL|SINGLETON|SESSIONSINGLETON)
  • namespaceparam: Name des Model-Parameters für den Template-Namespace. (Zeichen: [A-Za-z0-9_.-])
  • templateparam: Name des Model-Parameters für den Template-Namen. (Zeichen: [A-Za-z0-9_.-])
  • getmethod: Name der Mode-Methode mit dem die Parameter abgefragt werden können. Dieser wird der Wert des namespaceparam bzw. templateparam als Parameter übergeben und erwartet den zugehörigen Rückgabewert. Standardmäßig wird die Funktion getAttribute() verwendet. (Zeichen: [A-Za-z0-9_])
  • dependentactionnamespace / dependentactionname / dependentactionparams: Die drei Optionen dienen dazu, eine abhängige Action automatisch beim Front-Controller zu registrieren. Dies ist vor Allem dann hilfreich, wenn ein Modul über das Tag eingebunden wird und eine Front-Controller-Action zur Steuerung der Navigation verwendet wird.

    Das Attribut dependentactionnamespace definiert den Namespace der Action (z.B. sites::mysite::biz) und dependentactionname den Namen/Alias der Action (z.B. Navigate). dependentactionparams beinhaltet die Parameter der Action in der Form param1:value1|param2:value2, wie aus dem URL-Layout des Front-Controllers bekannt.

Um das Tag anwenden zu könen, muss dieses zunächst via
APF-Template
<core:addtaglib namespace="tools::html::taglib" class="GenericImportTemplateTag" prefix="generic" name="importdesign" />
im aktuellen Gültigkeitsbereich bekannt gemacht werden.

Hinweise:
  • Als Anwendungsbeispiel kann der Artikel Behind the site (englisch) herangezogen werden. Dieser beschreibt, wie die vorliegende Dokuentationswebseite aufgebaut ist und welche Mittel des Frameworks sie nutzt.
  • Soll eine Front-Controller-Action zu Navigationszwecken verwendet werden, so muss bei der Klassendefinition die Variable $keepInURL mit true initialisiert werden. Dies bewirkt, dass die Action bei der Link-Generierung mit dem LinkGenerator erfasst wird.
  • Die Registrierung der Action wird nur dann durchgeführt, wenn die Attribute dependentactionnamespace und dependentactionname gefüllt sind und die Action noch nicht gegistriert ist. Die Angabe von Parametern ist optional.

4. core:appendnode-Tag

Aus einer Diskussion über wiederverwendbare Template-Fragmente (z.B. Formulare) entstand die Idee, eine TagLib zu entwerfen, die Inhalte aus einem beliebigen Template in den aktuellen Gültigkeitsbereich zu importieren. Durch die generische DOM-Struktur der GUI-Elemente des Frameworks ist dies auf sehr einfache Weise möglich.

Um die Funktion allgemeingültig zur Verfügung zu stellen, wurde im 1.8er-Zweig der <core:appendnode />-Tag hinzugefügt, der beliebige Templates "importieren" kann. Der Tag erwartet - ähnlich dem importdesign-Tag - die statischen Attribute namespace und template.

Ab Version 1.12 ist zusätzlich das Attribut includestatic verfügbar. Ist dieses vorhanden und auf den Wert true eingestellt, so wird sämtlicher Inhalt des inkludierten Templates übernommen. Enthält es einen anderen Wert oder ist nicht vorhanden, werden nur die aktuell im eingebundenen Template enthaltenen DOM-Knoten (Instanzen von Taglibs) übernommen.

4.1. Einbindung von Templates

Um ein wiederverwendbares Template einbinden zu können, muss das Tag im gewünschten Template wir folgt platziert werden:

APF-Template
<core:appendnode namespace="..." template="..." [includestatic="true" ]/>

Soll beispielweise ein Template zur Ausgabe eines Domänen-Objekts in mehreren View-Templates eingesetzt werden, so schickt es sich, dieses in einem eigenen Template (Namespace: sites::testsite::pres::templates::generic; Template: generic_templates) zu definieren. Die Definition kann dabei folgende Gestalt haben:

APF-Template
<html:template name="ReusableTemplate"> ... <template:placeholder name="DisplayName"> ... </html:template>

Um das Template in einem anderen verwenden zu können, muss die Template-Datei wie folgt in die bestehende eingebunden werden:

APF-Template
<core:appendnode namespace="sites::testsite::pres::templates::generic" template="generic_templates" />

4.2. Verwendung der Elemente

Die Verwendung der durch das <core:appendnode />-Tag eingebundenen Elements gestaltet sich identisch zur bisherigen Vorgehensweise, da die Elemente in den Gültigkeitsbereich des gewünschten Templates importiert werden. Damit können weiterhin die im Document-Controller zur Verfügung stehenden Methoden (z.B. getTemplate()) verwendet werden.

Das im Kapitel 4.1 aufgezeigte Template könn wie auch bisher mit

PHP-Code
$tmpl = &$this->getTemplate('ReusableTemplate');

adressiert werden.

4.3. Wichtige Hinweise

Das Parsen des eingebundenen Templates erfolgt identisch zu den per importdesign-Tag eingebundenen Template-Dateien. Das bedeutet, dass der Entwickler dafür Sorge tragen muss, dass die gewünschten Tags im eingebundenen Template auch erkannt werden.

Die <core:appendnode />-TagLib legt im Ursprungstemplate Marker-Tags an, damit die transformOnPlace()-Methoden genutzt werden können. Bitte beachten Sie, dass die eingebundenen Kinder in der Reihenfolge der Definition im zusätzlichen Template eingebunden werden!

Sofern auch statischer Inhalt des eingebundenen Templates wie z.B.

APF-Template
<div class="formattingContainer"> <html:template name="ReusableTemplate"> ... </html:template> </div>

übernommen werden soll, muss das Attribut includestatic auf den Wert true gestellt werden.

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 06.12.2008, 22:47:46
Der Unterschied ist, dass der core:importdesign-Tag einen neues Kind im aktuellen DOM-Knoten erzeugt und seine Kinder verarbeitet, der core:appendnode-Tag bindet seine Kinder in den Vater-Knoten dein. Das bedeutet, dass die "eingepflanzten" Kinder im ursprünglichen Knoten wie "eigene" Kinder verwendet werden können.
So ist es möglich, Template-Fragmente ohne Kopieren wieder zu verwenden.
2
fliegermichl 17.11.2008, 11:06:51
Wo besteht der Unterschied zum core:importdesign Tag?