8.3. Seitenvorlagen

8.3.1. Einführung

Die Vorlagen dienen in Welcompose zur Gestaltung respektive Aufbereitung der einzelnen Seiten. Sie werden in Form von normalen HTML-Dateien hinterlegt, bei denen die Inhalte, die mit Welcompose verwaltet werden sollen, durch Platzhalter ersetzt werden. Diese werden wiederum von Welcompose beim Seitenaufruf durch die jeweiligen Inhalten ersetzt. Selbstverständlich ist man nicht nur auf HTML begrenzt und kann jede Markup-Sprache verwenden, die man benötigt – oder sogar nur nackten Text.

[Anmerkung] Anmerkung

Zur Speicherung von CSS- oder JavaScript-Dateien kommen nicht die normalen Vorlagen, sondern die globalen Vorlagen (siehe Abschnitt 8.6, „Globale Vorlagen“) zum Einsatz. Um Bilder und andere binäre Objekte kümmern sich die globalen Dateien (siehe Abschnitt 8.7, „Globale Dateien“).

8.3.2. Vorlagen verwalten

Die Verwaltung der Vorlagen erfolgt im Bereich Vorlagen im Unterpunkt Seitenvorlagen. Die Übersicht listet die vorhandenen Vorlagen zusammen mit dem Namen, dem jeweiligen Typ und einer allenfalls vorhandenen Beschreibung. Eine Filterung der angezeigten Vorlagen ist anhand des Vorlagentypen- und Gruppen möglich. Dazu werden eine Reihe von Funktionen zur Bearbeitung von Vorlagen geboten:

Abbildung 8.1. Übersicht über vorhandene Vorlagen

Übersicht über vorhandene Vorlagen

Upload

Ermöglicht das Hochladen einer Vorlage, wobei mit dem Dateiinhalt der hochgeladenen Datei die auf dem Server hinterlegte Vorlage ersetzt wird.

Download

Erlaubt den Download der Vorlage als Datei.

Duplizieren

Mit dieser Funktion ist es möglich, die jeweilige Vorlage zu duplizieren und unter einem anderen Namen, Typ oder auch Inhalt zu speichern. So kann man Zeit beim Erstellen der Vorlagen sparen, wenn sich zwei Vorlagen nur wenig unterscheiden.

Löschen

Löscht die Vorlage.

Um die jeweiligen Inhalte einer Seitenvorlage zu bearbeiten, klicken Sie bitte auf den Namen der Seitenvorlage.

Sobald man auf den Link Neu anlegen klickt, kommt man zum Formular zum Hinzufügen einer neuen Vorlage.

Abbildung 8.2. Vorlage hinzufügen

Vorlage hinzufügen

Typ

Der Vorlagen-Typ, den die neue Vorlage erhalten soll. Bestimmt, für welche Arten von Seiten die Vorlage eingesetzt werden soll. Achten Sie dabei darauf, dass innerhalb einer Vorlagengruppe für jeden Vorlagen-Typ nur eine Vorlage existieren kann.

Name

Der Name der Vorlage. Kann frei gewählt werden.

Beschreibung

Beschreibung der Vorlage. Kann frei gewählt werden und soll beim Wiederfinden der Vorlage helfen.

Inhalt

Der eigentliche Inhalt der Vorlage. Hier kann der (X)HTML-Code eingefügt werden. Links zu anderen Seiten, Globalen Vorlagen und einigen anderen Strukturelementen können über die Hilfsfunktionen oberhalb des Inhaltsbereichs eingefügt werden.

Vorlagengruppen

Vorlagengruppen, denen die Vorlage zugeordnet werden soll. Es kann entweder keine, eine oder mehrere Vorlagengruppen ausgewählt werden. Die Vorlage ist aber nur aktiv, wenn sie mindestens einer Vorlagengruppe zugewiesen wird.

[Anmerkung] Anmerkung

Über der Textarea stehen Links zur Verfügung, die über ein Pop-up unterschiedliche Dateien des Systems referenzieren und Ihnen die Gestaltung der Seitenvorlagen erleichtern. Details über Funktion und Anwendung der einzelnen Links finden sie in den jeweiligen inhaltlichen Kapiteln.

Die Smarty-Funktion zur Einbindung der Globalen Dateien muss man nicht selber schreiben, sondern kann man sich von einer Hilfsfunktion einsetzen lassen, die jeweils über den Eingabefeldern für die Vorlagen-Inhalte sitzt. Über ein Pop-up lässt sich die gewünschte Globale Datei auswählen. Die Smarty-Funktion zur Einbindung der Globalen Datei generiert die adäquate Syntax und setzt diese an der Stelle des zuvor gesetzten Cursors ein.

Abbildung 8.3. Interne Links mit Hilfsfunktion referenzieren

Interne Links mit Hilfsfunktion referenzieren

8.3.3. Anwendung

8.3.3.1. Einführung

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:

  • Es wird standardmässig nur ein Minimum an Daten geladen.

  • Werden weitere Daten benötigt, können diese nach Bedarf nachgeladen werden.

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.

8.3.3.2. Vorhandene Daten auslesen

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.

8.3.3.3. Die Smarty Debug Konsole

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.

[Tipp] Tipp

Die Smarty Debug Konsole ist DAS zentrale Mittel, um die tatsächlich der Vorlage zur Verfügung stehenden Variablen und die ihnen aktuell zugewiesenen Werte anzeigen zu lassen.

Die Funktionsweise der Debug-Konsole soll an einem einfachen Beispiel illustriert werden. Dazu muss eine Vorlagengruppe (siehe Abschnitt 8.4, „Vorlagengruppen“)angelegt werden, beispielsweise test und mit einer Seite des Typs WCOM_SIMPLE_PAGE (siehe Abschnitt 6.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.

Abbildung 8.4. "Hallo-Welt"-Vorlage

"Hallo-Welt"-Vorlage

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

Abbildung 8.5. Smarty Debug Konsole

Smarty Debug Konsole

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 und Werte (rechts).

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
...
[Tipp] Tipp

Auf diese Weise lässt sich leicht herausfinden, auf welche Daten in eine Vorlage zugegriffen werden kann oder welche Informationen nachgeladene Daten mitbringen, ohne dass man die Dokumentation wälzen muss.

8.3.3.4. Daten nachladen

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 17.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"}
[Warnung] Warnung

Wenn die Smarty Debug Console mittels {debug} vor der Benutzung von {select_named} respektive {select_simple} aufgerufen wird, tauchen die angeforderten Daten, im obigen Fall {$page_types}, in der Smarty Debug Console nicht auf. Wer die angeforderten Daten einbeziehen möchte, muss {debug} nach dem Aufruf von {select_simple} respektive {select_named} anwenden.

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"}


[9] Schreibende Methoden sind aus Sicherheitsgründen mittels einer Whitelist für den Zugriff aus den Vorlagen gesperrt.

[10] Namespacing ist eigentlich der falsche Begriff, da PHP keine Namespaces unterstützt und es somit nur eine grosse Lüge ist. Aber uns ist kein besserer Name eingefallen...