Bei den meisten Software steht für jede Vorlage eine bestimmte Menge von Daten respektive Platzhaltern zur Verfügung, die man verwenden kann oder nicht. Braucht man mehr Daten, als Software-seitig vorgesehen sind, geht dies meist nicht oder ist nur schwer zu bewerkstelligen. Umgekehrt werden, wenn weniger Daten benötigt werden, unnötig Daten geladen, was die Software langsamer macht.

Um mehr Flexibilität zu gewährleisten, geht Welcompose einen anderen Weg:

Der Nachteil dieser Methode ist, dass das Nachladen der Daten ein wenig komplizierter als das simple Einsetzen der Platzhalter ist. Mit den Erklärungen in den nächsten Abschnitten sollte dies aber keine unnötig hohe Hürde bedeuten.

Wie bereits gesagt, bringt Welcompose immer ein Minimum an Daten pro Seite mit. Beispielsweise die gesamten Metadaten der aktuellen Seite, da sie ohnehin beim Verarbeiten der Anfrage, wenn Welcompose ermittelt, welche Seite überhaupt angefordert wird, bereits geladen wurden.

Um herauszufinden, wie die Variablen für den Zugriff auf die Metadaten heissen, könnte man entweder den PHP-Code lesen, der die Daten zusammenstellt, oder im Handbuch hier nach einer Liste der Variablen suchen – tun Sie's nicht, selbst wenn mittlerweile so eine existiert. Denn die Daten dort werden entweder nicht aktuell oder aus anderen Gründen unvollständig sein.

Die aktuellen Informationen für die jeweilige Seite bringt nämlich Welcompose direkt selber mit, respektive die Bibliothek zur Verarbeitung der Vorlagen. Diese verfügt nämlich über eine Debug-Konsole, welche die vorhandenen Variablen und die ihnen aktuell zugewiesenen Daten auflistet.

Auf diese Weise kann man dort die benötigten Daten finden und direkt die richtigen Platzhalter in die Vorlage einsetzen.

Die Funktionsweise der Debug-Konsole soll an einem einfachen Beispiel illustriert werden. Dazu muss eine Vorlagengruppe (siehe Abschnitt 7.4, „Vorlagengruppen“)angelegt werden, beispielsweise test und mit einer Seite des Typs WCOM_SIMPLE_PAGE (siehe Abschnitt 5.2, „Seiten“) verbunden werden, die mit ein wenig Inhalt befüllt sein sollte.

Nun muss man eine Vorlage des Typs simple_page_index mit einem beliebigen Namen erstellen, beispielsweise Vorlage für Inhaltsseiten. In den Inhaltsbereich der Vorlage kann man einen Dummy-Text wie Hallo Welt eingeben. Als Vorlagegruppe muss die soeben erstellte Gruppe ausgewählt werden, dem Beispiel gemäss also test.

Hat man dies erledigt, kann man die Seite aufrufen und sollte Hallo Welt zu Gesicht bekommen.

Nun kann man den Dummy-Text aus der Vorlage entfernen und statt dessen den Befehl zur Ausgabe der Debug-Konsole einfügen:

{debug}

Sobald man die Vorlage gespeichert hat und die Ausgabeseite aktualisiert, sollte ein Pop-up mit der Smarty Debug Console erscheinen (gegebenenfalls muss vorab der Pop-up-Blocker deaktiviert werden).

Im Abschnitt Assigned Template Variables listet die Smarty Debug Console die bis zum Aufruf von {debug} der Vorlage zugewiesenen Variablen (links, {$page} usw.) inklusive ihrer aktuellen Inhalte (rechts, grüne Schrift).

Die Variablennamen sind dabei direkt in der Form notiert, wie sie als Platzhalter in die Vorlagen eingesetzt werden müssen. Würde man beispielsweise in die aktuelle Vorlage, wo jetzt {debug} steht, {$SCRIPT_NAME} oder {$action} schreiben und die Seite dann neu laden, würden {$SCRIPT_NAME} und {$action} durch ihre aktuellen Werte /welcompose/trunk/welcompose und Index ersetzt werden.

Wer nun das Gleiche mit {$get} oder {$page} machen würde, erhält als Ergebnis Array. Dies ist korrekt, da es sich bei den beiden Variablen nicht um simple Zeichenketten wie {$SCRIPT_NAME} oder {$action} handelt, sondern um Arrays, also Variablen, in denen mehrere weitere Variablen gespeichert werden.

Dies erkennt man daran, dass die Smarty Debug Console bei {$get} rechts in der ersten Zeile mit Array (8) signalisiert, dass es sich eben um einen Array mit 8 sogenannten Elementen, also in ihm gespeicherte Variablen handelt. Die Elemente bestehen einerseits aus ihrem Namen (auch Schlüssel genannt), der links vom Pfeil => steht, und einem Wert rechts vom Pfeil (der wiederum ein Array sein kann).

Um auf ein Array-Element zuzugreifen, muss man den Variablennamen um den Elementnamen erweitern, die beide durch einen Punkt (.) separiert werden. Um beispielsweise auf das Element id von {$page} zuzugreifen, müsste man {$page.id} schreiben, worauf dann 16 erschienen würde.

Man kann auch jeweils alle Elemente eines Arrays ausgeben:

{foreach from=$page key=_element item=_value}
	Element: {$_element}
	Wert: {$_value}
{/foreach}

Dieses Konstruktur iteriert durch den gesamten Array $page und gibt jedes einzelne Element samt Name ({$_element}) und Wert ({$_value}) aus (gekürzt):

Element: id
Wert: 16
Element: project
Wert: 1
Element: navigation
Wert: 3
Element: root_node
Wert: 15
Element: parent
Wert: 15
Element: lft
Wert: 2
Element: rgt
Wert: 3
...

Die Daten, die standardmässig in den Vorlagen zur Benutzung bereitstehen, entsprechen nur einem kleinen Teil der Daten, die Welcompose bereithält. Man denke nur an Navigationen oder Boxen. Diese Daten müssen jeweils von Hand nachgeladen werden.

Zu diesem Zweck verfügt Welcompose über zwei Funktionen, mit denen direkt aus den Vorlagen heraus auf die internen APIs von Welcompose zugegriffen werden kann – genauer gesagt auf alle lesenden Methoden^[9]. So bietet Welcompose innerhalb der Vorlagen sozusagen dieselbe Funktionalität und Flexibilität, wie die Modifikation des Original-Quellcode bei anderen Systemen.

Die beiden Funktionen respektive Smarty Plug-ins, welche den Zugriff auf die internen APIs bereitstellen, heissen select_simple und select_named. Sie tun beide dasselbe: Sie rufen die gewünschte Funktion mit den angegebenen Parametern auf und stellen die retournierten Daten innerhalb der Vorlage bereit. So kann auf sie zugegriffen werden, als seien die Daten bereits von Anfang an geladen gewesen.

select_simple und select_named funktionieren fast gleich. Es gibt nur einen kleinen Unterschied in der Art, wie sie die Funktionen aufrufen. Aber dazu erst später mehr. Für den Moment tun wir so, als wären sie identisch.

Ein Aufruf von select_simple respektive select_named besteht nebst dem Namen der Funktion (select_simple respektive select_named) immer aus mindestens vier Parametern: Dies sind ns, class, method und var.

{select_named ns="Content" class="BlogPosting"
	method="selectBlogPostings" var="blog_postings"}

Die Bedeutung von var ist schnell erklärt: var bezeichnet den Variablennamen, dem die von der Funktion zurückgegebenen Daten innerhalb der Vorlage zugeordnet werden sollen. Auf die Daten von obigem Aufruf liesse sich also über die Variable $blog_postings zugreifen. Der Variablenname ist frei wählbar, so könne man statt $blog_postings auch $blps schreiben.

Die anderen drei Parameter ns, class und method gehören zusammen und dienen dazu, select_simple respektive select_named zu sagen, welche Welcompose-Funktion sie ausführen sollen.

Damit man weiss, was man überhaupt für Werte den Parametern übergeben muss, muss entweder einen Blick in die API-Dokumentation (siehe Abschnitt 15.1, „API-Dokumentation erzeugen“) oder direkt in den Code werfen.

Welcompose verfügt über eine Menge von Klassen, die mit Begriffen wie Application, Community, Content oder Media beginnen. Auf sie folgt ein Unterstrich, bevor ein weiterer Begriff wie BlogPosting, GeneratorForm oder PageType folgt.

Die Begriffe vor dem Unterstrich (_) dienen zur Gruppierung der Klassen. Alle Klassen, die Content anfangen, haben irgendwas mit den Inhalten zu tun, die Welcompose verwaltet. Die Klassen mit Media kümmern sich dagegen um Multimediaobjekte wie Bilder oder Filme. Diese Organisation nach Bereichen nennen wir bei Welcompose Namespacing^[10], oder kurz ns. Dies bedeutet, wer auf eine Klasse aus Application, Community, Content oder Media zugreifen will, muss bei ns entweder Application, Community, Content oder Media eintragen.

Nachdem der Teil links des Unterstrichs bereits vergeben ist, bleibt rechts neben dem Unterstrich noch ein Teil des Klassennamens übrig. Dieser wird jeweils für den Parameter class verwendet. Wer also etwas aus der Klasse Content_PageType will, wird als ns Content verwendenden und als class PageType.

Mit Hilfe von ns und class weiss Welcompose nun, mit welcher Klasse es arbeiten soll. Nun geht es aber noch darum, Welcompose zu sagen, welche Funktion respektive Methode es daraus verwenden soll, indem man für method kurzerhand den Methoden-Namen eingibt. Möchte man beispielsweise alle Page Types auslesen, gibt man selectPageTypes ein. Der ganze Aufruf sieht dann etwa so aus:

{select_named ns="Content" class="PageType" method="selectPageTypes"
	var="page_types"}

Nun wird man in den seltensten Fällen alle Page Types, Blog Postings oder alle Bilder auslesen wollen. In der Regel möchte man beispielsweise nur die neusten Blog Postings. Dies kann man Welcompose sagen, indem man select_simple und select_named weitere Parameter übergibt. Und davon gibt es je nach Funktion eine ganze Menge. Wer beispielsweise in der API-Dokumentation den Eintrag zu selectBlogPostings() nachliest, findet eine Liste unterstützter Parameter wie page oder draft, mit denen sich beispielsweise festlegen lässt, von welcher Seite Blog Postings geladen werden sollen (page) oder wie der Entwurfsstatus der Blog Postings (draft) sein muss. Diese Parameter kann man select_simple respektive select_named einfach mitgeben:

{select_named ns="Content" class="BlogPosting" method="selectBlogPostings"
	var="blog_postings" page="12" draft="0"}

Kommen wir nun zum Unterschied zwischen select_simple und select_named.

Als Faustregel für alle, für die die bisherigen Erläuterungen bereits an Fachchinesisch grenzen, kann man sich merken, dass für alle Funktionen respektive Methoden, die mehrere Datensätze auslesen und darum selectBlogPostings() oder selectPageTypes() heissen (man beachte das Plural-S!), select_named verwendet werden muss. Alle Funktionen, die dagegen nur einen Datensatz auslesen und darum selectNavigation() oder selectGlobalBox() heissen, benötigen select_simple.

Doch warum? Zu diesem Zweck ziehen wir wieder die API-Dokumentation zur Funktion respektive Methode selectBlogPostings() und ihrem Geschwister selectBlogPosting() zu Rate. In beiden Einträgen ist eine Zeile nach der Form array selectBlogPostings ([array $params = array()]) respektive array selectBlogPosting (int $id) enthalten. Dabei handelt es sich um die jeweiligen Funktionssignaturen.

Überall, wo ([array $params = array()]) nach dem Funktionsnamen wie selectBlogPostings steht, muss select_named stehen. Denn select_named nimmt alle Parameter, die abgesehen von ns, class, method und var angegeben werden, und formt diese in den Array $params um, den die Funktionen erwarten. Dies ist nötig, damit man von der Vielzahl der Parameter, die diese Funktionen zur Filterung der Datensätze anbieten, jeweils nur die benutzt werden, die man verwenden möchte.

Überall, wo (int $id) steht, muss dagegen select_simple verwendet werden. Denn die Funktionen erwarten einen oder mehrere Parameter in einer festen Reihenfolge, die von select_simple eingesetzt werden – in diesem Fall id. Wenn eine Funktionssignatur wie (int $page, int $id) vorliegt, müssen die Parameter page und id in den select_simple-Aufruf eingesetzt werden und zwar in genau dieser Reihenfolge, damit die Daten korrekt angefordert werden:

{select_simple ns="Beispiel" class="TestKlasse" method="selectTestKlasse"
	page="2" id="15"}

Wer trotz Verwaltung der Vorlagen nicht auf seinen angestammten Editor verzichten will (beispielsweise um von Syntax-Highlighting oder anderen Funktionen zu profitieren), muss das nicht. Der Webbrowser Firefox (und auch der grössere Bruder Mozilla/Seamonkey), der für verschiedene Betriebssysteme erhältlich ist, ermöglicht die Integration des gewünschten Editors zur Bearbeitung von Inhalten innerhalb eines HTML-Formulars.

Firefox bringt diese Funktionalität zwar nicht von Haus aus mit, allerdings existieren verschiedene Erweiterungen zu diesem Zweck:

Sollten Sie weitere Tipps kennen, um das Editieren von Vorlagen einfacher zu machen, nehmen wir diese gerne in das Handbuch auf.