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.

Der APF-Parser verarbeitet alle Tags der Form

APF-Template

<prefix:name />

beziehungsweise

APF-Template

<prefix:name></prefix:name>

inklusive der definierten Tag-Attribute innerhalb von Template-Dateien. Zur Erzeugung des DOM-Baums greift er auf die Document::$knownTags- (statisch) und Document::$knownInstanceTags-Listen (pro Instanz) zurück um die zu nutzende Implementierung zu erhalten. Möchten Sie in Ihrem Projekt einen eigenen Tag nutzen, der im Auslieferungszustand des APF noch nicht bekannt ist, können Sie den <core:addtaglib />-Tag nutzen. Dieser macht den gewünschten Tag inklusive seiner Implementierung entweder global für alle Templates oder den lokalen DOM-Knoten bekannt. In einem Template auf diese Weise bekannt gegebene Tags können unmittelbar danach genutzt werden.

Die Signatur des Tags gestaltet sich wie folgt:

APF-Template

<core:addtaglib
   class=""
   prefix=""
   name=""
   [scope=""]
/>

Beschreibung der Attribute:

class: Der voll-qualifizierte Klassen-Name der Tag-Implementierung. (Zeichen: [A-Za-z0-9_\])
prefix: XML-Prefix. (Zeichen: [a-z])
name: XML-Tag-Name. (Zeichen: [a-z])
scope: Definiert die Art der Tag-Registrierung. global registriert den Tag projektweit, local nur für den aktuellen DOM-Knoten. Standard: global. (Erlaubte Werte: global|local)

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 frei durch das Attribut class definiert werden. Dabei ist es möglich, eine Implementierung mit unterschiedlichen Präfixen und unterschiedlichen Tag-Namen zu registrieren.

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.

Die Registrierung eines Tags mit Hilfe des <core:addtaglib />-Tags ist gleichbedeutend mit der Registrierung innerhalb der Bootstrap-Datei. Um Ihren Template-Code schlank zu halten empfielt es sich daher die im Projekt verwendeten Tags in der index.php z.B. per

PHP-Code

Document::addTagLib('VENDOR\..\DateDisplayTag', 'date', 'display');

zu registrieren. Details hierzu können Sie den Kapiteln Implementierung von Tags und Umstieg von 2.1 auf 3.0 entnehmen.

1.2. Importdesign

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

APF-Template

<core:importdesign
   namespace=""
   template=""
   [incparam=""]
   [context=""]
/>

genutzt werden.

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.

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="VENDOR\pres\templates"
   template="[pagepart = test]"
/>
<core:importdesign
   namespace="VENDOR\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="" />

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');

Neben der klassischen Definition von Platzhaltern können Sie auch die erweiterte Templating-Syntax einsetzen. Ein Platzhalter mit dem Namen NameDesPlatzhalters lässt sich damit auch per

APF-Template

${NameDesPlatzhalters}

definieren. Details finden Sie unter Templates.

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-_.])

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="VENDOR\modules\guestbook" config="language.ini" entry="title" />

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

Code

/VENDOR/config/modules/guestbook/{CONTEXT}/{ENVIRONMENT}_language.ini

mit dem Inhalt

APF-Konfiguration

[de]
title = "Mein Modul"

[en]
title = "My module"

gefüllt werden.

Sprachabhängige Werte lassen sich 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>
      <html:getstring
             name="intro-text"
             namespace="..."
             config="..."
             entry="intro.text"/>
   </p>
   ...
</html:form>
<html:template name="Message">
   ...
   <p>
      <html: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

use APF\core\pagecontroller\BaseDocumentController;

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 < html:getstring /> im Formular füllen:
      $form = &$this->getForm('Form');
      $form->getLabel('intro-text')->setPlaceHolder('count', 'eine');

      // Platzhalter in einem < html: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.

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="">
   [<html:placeholder name="" />]
   [<core:addtaglib class="" prefix="" name="" />]
   [<html: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-_])

Möchten Sie weitere Tags innerhalb von <html:template /> verwenden, können Sie diese mit <core:addtaglib /> vor der Verwendung hinzufügen.

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
   class=""
@>
<html:placeholder name="Content" />

<html:template name="MyTemplate">
  <html:placeholder name="MyPlaceHolder">
</html:template>

Controller:

PHP-Code

use APF\core\pagecontroller\BaseDocumentController;

class SampleController extends BaseDocumentController {
   public function transformContent(){
      $tmpl = &$this->getTemplate('MyTemplate');
      $tmpl->setPlaceHolder('MyPlaceHolder', 'MyContent');
      $this->setPlaceHolder('Content', $tmpl->transformTemplate());
   }
}

Hier wird in der Template-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. Löschen des Template-Inhalts

Verwenden Sie ein Template um sich wiederholende Inhalte auszugeben, so gilt zu beachten, dass die Instanz des Template-Tags (TemplateTag) bei der Verwendung in Schleifen immer die selbe Instanz ist. Füllen Sie während eines Durchlaufs nur einen Teil der Platzhalter, so werden in vorherigen Durchläufen gefüllte Elemente nicht wieder entfernt. Um dies zu vermeiden können Sie nach jedem Durchlauf die Methode clear() auf der Instanz des Templates aufrufen:

PHP-Code

use APF\core\pagecontroller\BaseDocumentController;

class SampleController extends BaseDocumentController {

   public function transformContent() {

      $template = &$this->getTemplate('table-line');

      $elements = ...;

      foreach($elements as $element) {
         $template->setPlaceHolder('foo', $element->getFoo());

         $bar = $element->getBar();
         if(!empty($bar)) {
            $template->setPlaceHolder('bar', $bar);
         }

         $buffer .= $template->transformTemplate();

         $template->clear();
      }

      $this->setPlaceHolder('content', $buffer);
   }
}

Der Aufruf von clear() sorgt dafür, dass alle Platzhalter-Tags (Instanzen von PlaceHolderTag) zurückgesetzt - sprich der Inhalt geleert - wird.

Definieren Sie eigene Platzhalter-Tags oder haben Sie weitere Elemente, die nach einem Schleifen-Durchlauf geleert werden sollen, können Sie der Methode clear() eine eigene Implementierung des Interfaces TemplateTagClearApproach mitgeben. Die folgende Code-Box zeigt die Standard-Implementierung des APF, die die vorhandenen Platzhalter zurücksetzt und gleichzeitig im Template vorhandenen <*:getstring />-Tags zurücksetzt:

PHP-Code

use APF\core\pagecontroller\TemplateTagClearApproach;

class DefaultTemplateTagClearApproach implements TemplateTagClearApproach {

   public function clear(TemplateTag &$node) {
      $children = & $node->getChildren();
      foreach ($children as $objectId => $DUMMY) {
         if ($children[$objectId] instanceof PlaceHolderTag) {
            $children[$objectId]->setContent('');
         }
         if ($children[$objectId] instanceof LanguageLabelTag) {
            $children[$objectId]->clearPlaceHolders();
         }
      }
   }

}

Möchten Sie der Methode eine eigene Implementierung des Lösch-Vorgehens mitgeben, so gestaltet sich der Controller-Code wie folgt:

PHP-Code

use APF\core\pagecontroller\BaseDocumentController;
use APF\core\pagecontroller\DefaultTemplateTagClearApproach;

class SampleController extends BaseDocumentController {

   public function transformContent() {

      $template = &$this->getTemplate('table-line');

      $elements = ...;

      $clearApproach = new DefaultTemplateTagClearApproach();
      foreach($elements as $element) {
         $template->setPlaceHolder('foo', $element->getFoo());

         $bar = $element->getBar();
         if(!empty($bar)) {
            $template->setPlaceHolder('bar', $bar);
         }

         $buffer .= $template->transformTemplate();

         $template->clear($clearApproach);
      }

      $this->setPlaceHolder('content', $buffer);
   }
}

3. Document-Controller

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

APF-Template

<@controller
   class=""
@>

Beschreibung der Attribute:

class: Voll-qualifizierter Klassen-Name des Controllers. (Zeichen: [A-Za-z0-9_\])

Details finden Sie unter (Document-)Controller.

4. FrontController

Der Tag <fcon:importdesign />-Tag 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 TYPE_PRE_PAGE_CREATE (siehe Front-Controller) ausgeführt wird. Diese kann in der URL enthaltene Parameter an das Model-Objekt weitergeben.

APF-Template

<fcon:importdesign
   template-namespace=""
   template-param=""
   model=""
   [sessionsingleton=""]
/>

Beschreibung der Attribute:

template-namespace: Namespace zum Template-Ordner. (Zeichen:: [A-Za-z0-9\])
template-param: Model-Parameter, der für die Einbindung des Templates verwendet werden soll. (Zeichen: [A-Za-z0-9_])
model: Voll-qualifizierter Klassen-Name der Model-Klasse. (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)

Um den Tag verwenden zu können muss diese mit einem

APF-Template

<core:addtaglib
   class="APF\tools\html\taglib\FrontControllerImportTemplateTag"
   prefix="fcon"
   name="importdesign"
   />

eingebunden werden.

Bitte beachten Sie, dass das Model das Interface FrontControllerImportTemplateModel implementieren muss. Der Tag nutzt die Methoden getTemplateNamespace() und getTemplateName() um das zu ladende Template zu evaluieren.

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.

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.

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>?

Standard TagLibs

Kommentare

QUICKNAVI