Spezielle TagLibs

Auf dieser Dokumentationsseite werden Funktionen des Frameworks besprochen die für spezielle Anwendungsfälle oder komplexere Designs verwendet werden können.
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. 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="" prefix="" class="" />] [<iterator:getstring namespace="" config="" entry="" />] ... <iterator:item [getter=""]> <item:placeholder name="" /> [<item:getstring namespace="" config="" entry="" />] [<item:addtaglib namespace="" prefix="" class="" />] </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 "Getter" 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])
Um den Iterator verwenden zu können muss das Tag zuerst per
APF-Template
<core:addtaglib namespace="tools::html::taglib" prefix="html" class="iterator" />
im aktuellen Document bekannt gemacht werden. Weiterhin muss der im Document definierte DocumentController von der Klasse iteratorBaseController, die im Namespace tools::html::taglib::documentcontroller abgelegt ist, erben. Innerhalb des DocumentControllers, kann der Iterator dann wie folgt verwendet werden:
PHP-Code
import('tools::html::taglib::documentcontroller','iteratorBaseController'); class list_controller extends iteratorBaseController { function list_controller(){ } 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.

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.ActionFile = "StreamMediaAction" FC.ActionClass = "StreamMediaAction" FC.InputFile = "StreamMediaInput" FC.InputClass = "StreamMediaInput" FC.InputParams = ""
Eine Beispieldatei findet sich ebenfalls in der adventure-configpack-*-Release-Datei unter tools/media/actions/.

Für den konkreten Einsatz existieren bereits folgende TagLibs:
  • form_taglib_mediastream: Einsatz innerhalb des html:form-Tags
  • html_taglib_mediastream: Einsatz innerhalb einer Template-Datei
  • template_taglib_mediastream: 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" prefix="html" class="form" /> <html:form name="TestFormular"> <form:addtaglib namespace="tools::media::taglib" prefix="form" class="mediastream" /> <img src="<form:mediastream namespace="modules::mymodule::pres::images" filename="phone_icon.png" />" alt="" /&t; <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_.-])

Tipp:
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" prefix="html" class="mediastream" /> <img src="<html:mediastream namespace="config::modules::mymodule::pres::images" filename="phone_icon.png" id="PhoneIcon" />" alt="" />
  2. Manipulieren des Namespaces im DocumentController:
    PHP-Code
    class example_controller extends base_controller { function transformContent(){ $mediaStreamTag = &$this->__getMediaStreamTagByID('PhoneIcon'); $mediaStreamTag->setAttribute($mediaStreamTag->getAttribute().'::'.$this->__Context); } function &__getMediaStreamTagByID($id){ $children = &$this->__Document->getChildren(); foreach($children as $objectId => $DUMMY){ if(get_class($children[$objectId]) == 'html_taglib_mediastream'){ return $children[$objectId]; } } $null = null; return $null; } }

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 Frontcontroller zu registrieren. Dies ist vor Allem dann hilfreich, wenn ein Modul über das Tag eingebunden wird und eine Frontcontroller-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 Frontcontrollers bekannt.

Um das Tag anwenden zu könen, muss dieses zunächst via
APF-Template
<core:addtaglib namespace="tools::html::taglib" prefix="generic" class="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 Frontcontroller-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 FrontcontrollerLinkHandler 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:addtaglib namespace="core::pagecontroller" prefix="core" class="appendnode" /> <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:addtaglib namespace="core::pagecontroller" prefix="core" class="appendnode" /> <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 DocumentController 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
fliegermichl 17.11.2008, 11:06:51
Wo besteht der Unterschied zum core:importdesign Tag?
2
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.