Parser Secrets

1. Einleitung

Auf dieser Seite erhalten Sie Tipps und Tricks rund um den APF-Parser und die Erweiterung von Funktionalitäten des APF für spezielle Projekt-Lösungen.

Sollten Sie weitergehende Fragen haben, nutzen Sie unser Forum oder erstellen einen Feature-Request im Issue Management Tool.

2. Adressieren von DOM-Elementen

Wie im Kapitel Page-Controller beschrieben baut das APF aus Template-Dateien und deren Inhalt zur Laufzeit einen DOM-Baum auf, der der internen Struktur einer HTML-Seite im Browsers ähnlich ist. Aus diesem Grund können Sie innerhalb eines Tags (siehe Implementierung von Tags) oder Controllers (siehe (Document-)Controller) auf jedes Element dieses Baumes zugreifen.

Hierzu stehen eine Reihe von Methoden zur Verfügung, die für unterschiedliche Einsatzzwecke genutzt werden können. Die folgenden Kapitel gehen auf die einzelnen Optionen und deren Einsatzgebiet ein.

2.1. Zugriff über Convenience-Methoden

Die Klasse BaseDocumentController stellt eine Reihe von Methoden zur Verfügung, die beim Zugriff auf Template-Elemente helfen. getTemplate() sucht beispielsweise die Instanz eines <html:template />-Tags im aktuellen Dokument, setPlaceHolder() erlaubt das setzen eines Platzhalter-Wertes.

Eine Übersicht über die verfügbaren Methoden erhalten Sie auf der Seite (Document-)Controller oder in der API-Dokumentation.

2.2. Zugriff per getChildNode()

Die Methoden Document::getChildNode() und Document::getChildNodes() ermöglichen die Abfrage eines beliebigen DOM-Knotens innerhalb des aktuellen Dokuments an Hand des gewünschten Typs und eines Tag-Attributs.

Möchten Sie in einem Controller einen selbst erstellten Tag an Hand des Attributs ident abfragen, gestaltet sich der entsprechende Code wie folgt:

PHP-Code
use APF\core\pagecontroller\BaseDocumentController; class NewsController extends BaseDocumentController { public function transformContent() { try { $newsItem = &$this->getDocument()->getChildNode('ident', 'foo', 'VENDOR\..\tags\NewsTag'); ... } catch (InvalidArgumentException $e) { ... } } }

Möchten Sie mehrere Tag-Instanzen abfragen - z.B. alle Radio-Buttons mit gleichem Namen innerhalb eines Formulars - so können Sie dazu die Methode Document::getChildNodes() nutzen:

PHP-Code
use APF\core\pagecontroller\BaseDocumentController; class FormController extends BaseDocumentController { public function transformContent() { try { $radioButtons = &$this->getForm('...')->getChildNodes('name', 'foo', 'APF\tools\form\taglib\RadioButtonTag'); ... } catch (InvalidArgumentException $e) { ... } } }

2.3. Zugriff per getNodeById()

Die in Kapitel 2.1 und Kapitel 2.2 beschriebenen Vorgehensweisen beschränken sich auf die Abfrage von Knoten innerhalb eines definierten anderen Knotens. Im Fall von Kapitel 2.1 ist dies das aktuelle Dokument, für dessen Transformation der Controller zuständig ist, in Kapitel 2.2 wurden die Radio-Buttons eines Formulars ausgelesen.

Möchten Sie von einem beliebigen Punkt - etwa einem Controller oder innerhalb eines Tags - auf Knoten des gesamten DOM-Baums zugreifen können Sie entweder eine rekursive Suche implementieren oder das oder die gewünschte(n) DOM-Knoten mit dem Attribut dom-id klassifizieren.

Tags, die das Attribut dom-id besitzten, werden automatisch indiziert und können über die Methode Document::getNodeById() unter der definierten ID referenziert werden.

Möchten Sie in einem Controller auf ein Template (<html:template />-Tag) zugreifen, von dem Sie auf Grund der Applikations-Struktur nicht genau wissen, in welcher Struktur es definiert ist, so fügen Sie zunächst das Attribut dom-id mit einem für das Projekt eindeutigen Wert hinzu:

APF-Template
<html:template dom-id="gl-tmpl-foo" [name="foo"]> ... </html:template>

Anschließend können Sie diese an jeder beliebigen Stelle im Controller per

PHP-Code
use APF\core\pagecontroller\BaseDocumentController; class ListController extends BaseDocumentController { public function transformContent() { $listTemplate = $this->getDocument()->getNodeById('gl-tmpl-foo'); ... } }

darauf zugreifen.

Bitte beachten Sie, dass der Index für den Zugriff auf DOM-Knoten während der Analyse-Phase aufgebaut wird. Details hierzu können Sie dem Timing-Modell des Page-Controller entnehmen. Für den Zugriff via getNodeById() bedeutet dies, dass der Index erst während der Transformation eines Tags (innerhalb von Document::transform())) oder bei der Abarbeitung eines Controllers (innerhalb von DocumentController::transformContent()) vollständig aufgebaut ist.

Innerhalb von Tags können Sie auf Grund der Implementierung des APF-Parsers auf Kindstrukturenbereits bereits nach der Ausführung von Document::onParseTime() - sprich innerhalb von Document::onAfterAppend() - auf den Index zugreifen. Dieser ist zu diesem Zeitpunkt bereits vollständig aufgebaut. Bitte beachten Sie, dass dies nicht für Parallel- oder Vater-Strukturen gilt!

3. Überschreiben von Standard-Tags

Sind die mit dem APF ausgelieferten Standard-Tags für Ihr Projekt nicht ausreichend, so können Sie diese mit einer Projekt-spezifischen Löung überschreiben ohne dabei die Unterstützung von existierenden Convenience-Methoden zu verlieren.

Um die in Kapitel (Document-)Controller beschriebenen Methoden weiterhin nutzen zu können müssen die Projekt-spezifischen Tags entsprechende Interfaces implementieren. Die folgende Tabelle fasst dies zusammen:

Methode(n) Beschreibung
BaseDocumentController::setPlaceHolder() und BaseDocumentController::setPlaceHolders() Um eine eigene Implementierung eines Platzhalter-Tags einzusetzen, implementieren Sie bitte das APF\core\pagecontroller\PlaceHolder-Interface und überschreiben den mitgelieferten APF-Tag mit Ihrer Projekt-Lösung.
BaseDocumentController::getTemplate() Für eine Projekt-spezifische Lösung eines Template-Tags implementieren Sie bitte das Interface APF\core\pagecontroller\Template und überschreiben den mitgelieferten APF-Tag.
BaseDocumentController::getForm() Beabsichtigen Sie eine eigene Formular-Implementierung für Ihr Projekt einzusetzen, so nutzen Sie hierfür bitte das Interface APF\tools\form\HtmlForm. Überschreiben Sie die mit dem APF mitgelieferte Implementierung, können Sie getForm() weiterhin nutzen.
BaseDocumentController::getLabel() Möchten Sie eine andere Implementierung für den LanguageLabelTag einsetzen, so implementieren Sie bitte das APF\core\pagecontroller\LanguageLabel-Interface und überschreiben den mitgelieferten APF-Tag mit Ihrer Projekt-Lösung.

Registrieren Sie bitte anschließend den/die Projekt-spezifische(n) Tag(s) mit Hilfe von Document::addTagLib() in der Bootstrap-Datei nach dem Einbinden von APF/core/bootstrap.php mit den selben Argumenten für prefix und name wie der Standard-Tag jedoch mit einer unterschiedlicher Implementierung (Attribut class).

4. Erweiterte Templating-Syntax

Innerhalb von Templates lassen sich mit Hilfe der erweiterten Template-Syntax verschiedene Ausdrücke registrieren und ausführen. Diese können dazu genutzt werden um Templates übersichtlicher zu gestalten und im Projekt wiederkehrende Funktionen in Templates zu verpacken.

Details hierzu finden Sie im Kapitel Erweiterte Template-Funktionen. Ein weiter interessanter Artikel zum Thema Templating steht Ihnen in Kapitel Working with view models (Englisch) zur Verfügung.

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.
Für diesen Artikel liegen aktuell keine Kommentare vor.