>> Inhaltsverzeichnis >> Anleitung für Entwickler >> Templates und Skins erstellen

Anleitung für Entwickler

Templates und Skins erstellen

Referenzhandbuch für Templates

Dieses Framework verwendet die "Smarty Template-Engine". Diese Engine besitzt Ihre eigene Dokumentation, welche kostenlos unter der Adresse http://smarty.php.net/docs.php zum Download bereit steht.

Es ist Ihnen gestattet, die Engine durch selbt geschriebene Funktionen zu erweitern. Auf diese Weise können Sie die Syntax der verwendeten Templates quasi beliebig erweitern. Sie finden die Engine im Verzeichnis "include/template_classes". Eine Anleitung dazu finden Sie im Referenzhandbuch der Engine. Änderungen an der Engine sind jedoch nur Experten zu empfehlen.

Hinweis zu Lizenzen: Bevor Sie Änderungen vornehmen, beachten Sie bitte die Lizenzhinweise.

Abweichungen der Syntax

Die Syntax der verwendeten Version der "Smarty Template-Engine" weicht in einigen Punkten vom Referenzhandbuch ab. Der folgende Abschnitt beschreibt diese geänderte Syntax.

Kennzeichnung von Token

Anders als in der Originalversion von Smarty verwendet diese Version nicht die Zeichen '{' und '}' als öffnende und schliessende Tags für die Auszeichnung von Smarty-Codes, sondern die unverfänglicheren Strings: '[%' und '%]'. Als beispielsweise NICHT "{$variable}", sondern "[%$variable%]". Der Grund ist, dass die ursprünglichen Zeichen in den meisten HTML-Dokumenten zu häufig im Fließtext bzw. in Skripten oder Stylesheets auftauchen, was zu Problemen bei der Abarbeitung der Templates führen kann. Daher wurden die Tags vorsorglich auf diese unverfänglichere Variante geändert. (Dieses Vorgehen wird zudem auch im Handbuch der Engine für solche Fälle empfohlen.)

Anders als in der Originalversion erlaubt diese Version auch den Einsatz einer verkürzten Syntax für das Einsetzen einfacher Variablen. Statt der etwas umständlicheren Schreibweise "[%$VARIABLE%]" ist in dieser Version auch folgende Schreibweise gestattet: "%VARIABLE%". Dies betrifft allerdings ausschliesslich Variablen. Auf alle anderen Smarty-Codes ist dies NICHT anwendbar.

Namenskonventionen

Weil Smarty zwischen Groß- und Kleinschreibung unterscheidet wurde zur Vereinfachung festgelegt, dass Variablennamen prinzipiell in Großbuchstaben benannt sein sollten. Während die Namen von Funktionen und anderen Codes ausschliesslich Kleinbuchstaben enthalten sollten. Aus Gründen der Übersichtlichkeit ist dringend zu empfehlen, sich an diese Konvention zu halten.

Pfadangaben

In dieser Version können Verweise auf Dateien (Links, Grafiken, CSS, Skripte, etc.) als relative Pfadangaben gespeichert werden. Dateipfade werden beim Laden der Seite automatisch korrigiert. Es ist also nicht mehr erforderlich, ausschliesslich absolute Dateipfade zu verwenden.

Konfiguration

Smarty läuft in dieser Version im sicheren Modus (security=true). Das Einbetten von PHP-Codes in Templates ist nicht gestattet. Außerdem sind folgende Funktionen deaktiviert: include, include_php, config_load, php.

neue Funktionen

Diese Version führt einige neue Funktionen ein, welche die Originalversion nicht hatte.

import

[%import [preparser] file="<string>"%]

Attribut Typ erforderlich Defaultwert Beschreibung
file string ja n/a Pfad der einzufügenden Datei
preparser n/a nein null bestimmt wann die Datei importiert werden soll

Die Funktion "import" ersetzt die verschiedenen ursprünglichen Funktionen zum Einfügen von Dateien durch eine einheitliche Funktion. Sie unterscheidet sich außerdem in der Art, wie die Dateien behandelt werden. Die Funktion "import" behandelt die zu importierende Datei wie ein eigenständiges Template. Dieses hat mehrere Vorteile: das eingefügte Template unterliegt bspw. den selben Sicherheitseinschränkungen wie das Basistemplate. Außerdem (und noch viel wichtiger:) sorgt dieses Vorgehen dafür, dass die Korrektur enthaltener Pfadangaben korrekt arbeiten kann.

Das Flag "preparser" bestimmt, wann eine Datei importiert werden soll: BEVOR oder WÄHREND der Parser das Templat abarbeitet. Wird es gesetzt, wird die Datei VOR dem eigentlichen Parsen eingefügt. Das Flag "preparser" sollte beispielsweise immer dann verwendet werden, wenn das importierte Template auf Variablen zugreifen muss, welche durch das Basistemplate gesetzt werden. Klassisches Beispiel sind Templates welche innerhalbs des Körpers von Schleifen importiert werden. ("foreach", "section") Diese benötigen das Flag "preparser", falls sie auf die Schleifenvariablen zugreifen können müssen.

Beispiel:

Datei "hello_world.html"
Hello World!

Datei "template.html"
<p>[%import file="hello_world.html"%]</p>

Ausgabe:

<p>Hello World!</p>

create

[%create template="<string>" file="<string>" table="<string>" [ where="<string>" ] [ desc="<boolean>" ] [ sort="<string>" ] [ page="<integer>" ] [ entries="<integer>" ] [ titles="<boolean>" ] %]

Attribut Typ erforderlich Defaultwert Beschreibung
template string ja n/a Name des Templates, welches zum Generieren der GUI verwendet werden soll.
Erlaubte Werte sind: view_seperated, view, new, edit, search, small_search
file string ja n/a Pfad der Strukturdatei welche verwendet werden soll.
table string ja n/a Name der Tabelle, welche verwendet werden soll
where string nein <empty> wird verwendet um die WHERE-Klausel für die SQL-Anfrage zu generieren.
Syntax: <FELDNAME1>=<WERT1>[,<FELDNAME2>=<WERT2>[,...]]
desc boolean nein false Gibt an, ob die Einträge aufsteigend (false) oder absteigend (true) sortiert werden sollen.
sort string nein <primary key> Name der Spalte, nach welcher die Einträge sortiert werden sollen
page integer nein 0 Nummer des ersten Eintrags der angezeigt werden soll
entries integer nein 5 Anzahl der insgesamt anzuzeigenden Einträge
titles boolean nein true Legt fest, ob Attributnamen angezeigt werden sollen oder nicht.

Die Funktion "create" generiert automatisch eine GUI für eine gewählte Datenbank. Voraussetzung ist das Vorhandensein einer gültigen Strukturdatei, welche die Datenbank beschreibt.

Beispiel:

[%create template="edit" file="database.config" table="bookstore"%]

smilies

[%smilies target="<string>" [ width="<integer>" ] %]

Attribut Typ erforderlich Defaultwert Beschreibung
width integer nein 1 Anzahl der Spalten der Tabelle
target string ja n/a ID eines Input- oder Textarea-Tags

Die Funktion "smilies" generiert automatisch eine Tabelle aller verfügbaren Emoticons / Smilies, mit einem Link zum Einfügen in das angegebene Eingabefeld.

Beispiel:

<textarea id="text"></textarea>
[%smilies target="text" width="5"%]

Modifier

date

[%$foo|date%]

Erzeugt aus einer Variable, welche einen UTC enthält, eine JavaScript-Anweisung, welche die passende Zeitangabe entsprechend der Zeitzone des Client-Browsers als Text ausgibt.

Smilies

[%$foo|smilies%]

Ersetzt in einer Variable vom Typ String enthaltene Codes durch die dazu passenden Icons.

Beispiel:

$foo = „Text :example: Text“

wird umgesetzt zu:

Text
<img border="0" hspace="2" src="common_files/smilies/example.gif">
Text

embeddedTags

[%$foo|embeddedTags%]

Ersetzt in einer Variable vom Typ String Tags gemäß der für YANA vorgegebenen Syntax.

Beispiel:

$foo = „Text [b]Text[/b] Text“

wird umgesetzt zu:

Text <span style=“font-weight: bold;“>Text</span> Text

css

[%$foo|css%]

Erstellt für eine Verknüpfung mit dem angegebenen Pfad einer CSS-Datei.

Beispiel:

[%“default.css“|css%]

wird umgesetzt zu:

<link rel=“stylesheet“ type=“text/css“ href=“default.css“>

url

[%$foo|url%]

Generiert aus einer angegebenen Liste von Parametern einen Link auf das Framework selbst.

Beispiel:

<a href=“[%“target=1“|url%]“>Link</a>

wird umgesetzt zu:

<a href=“index.php?id=beispiel&amp;target=1“>Link</a>

Liste der wichtigsten erlaubten Platzhalter

* "erforderlich" meint in diesem Fall "ungleich NULL"

Platzhalter Typ erforderlich * Defaultwert Herkunft Beschreibung
PHP_SELF String ja n/a PHP Name der ausgeführten Skriptdatei.
REMOTE_ADDR String ja n/a PHP Die IP-Adresse des Clients.
ID String ja default GET/POST ID-Code des gerade aktiven Profils.
ACTION String nein <empty> GET/POST Name der Aktion welche gerade ausgeführt wird bzw. welche ausgeführt werden soll.
TARGET String nein <empty> GET/POST Ziel der Aktion welche gerade ausgeführt wird bzw. welche ausgeführt werden soll. (bspw. die ID eines Datensatzes)
SESSION_NAME, SESSION_ID String nein <empty> GET/POST Name und ID-Code der gerade laufenden Session (sollten bei allen internen Links angegeben werden)
PAGE integer nein 0 GET/POST Die Nummer des Datensatzes, ab welchem mit der Anzeige begonnen werden soll. (falls erforderlich)
ATIME string ja n/a Dateiattribut Fügt Datum und Zeit des letzten Zugriffs auf das HTML-Template an dieser Stelle ein.
MTIME string ja n/a Dateiattribut Fügt an dieser Stelle das Datum ein, an welchem das HTML-Template zuletzt geändert worden ist.
CTIME string ja n/a Dateiattribut Fügt an dieser Stelle das Datum ein, an welchem das HTML-Template erstellt worden ist.
BESCHREIBUNG String nein n/a skriptabhängig Beschreibungstext der gerade ausgewählten Aktion.
LANGUAGE Array ja n/a Sprachdatei(en) Array, welches alle Textstrings der gerade ausgewählten Übersetzung enthält.
PROFILE Array ja n/a Profildatei Array, welches alle Einstellungen des gerade aktiven Profils enthält.
Im Folgenden einige Beispiele. Beachten Sie, dass alle hier genannten Felder auch einen NULL-Wert enthalten dürfen.
PROFILE.BGCOLOR,
PROFILE.BGIMAGE
String nein n/a Profildatei Hintergrundfarbe und Hintergrundbild der Webseite
PROFILE.PFONT,
PROFILE.PSIZE,
PROFILE.PCOLOR
String nein n/a Profildatei Schriftart, Schriftgröße, Schriftfarbe für Standardabsätze (P-Tags)
PROFILE.HFONT,
PROFILE.HSIZE,
PROFILE.HCOLOR
String nein n/a Profildatei Schriftart, Schriftgröße, Schriftfarbe für Überschriften (H1-,H2-,H3-Tags)
PROFILE.HFONT,
PROFILE.HSIZE,
PROFILE.HCOLOR
String nein n/a Profildatei Schriftart, Schriftgröße, Schriftfarbe für Überschriften (H1-,H2-,H3-Tags)
INSERT_CONTENT_HERE String nein n/a skriptabhängig Dies ist eine Einfügemarke. Sie markiert die Stelle, an der Daten des Standard-Ausgabestroms eingefügt werden. Diese Variable hat lokalen Kontext, dass heißt sie muss auf der Basisseite des Skins (normalerweise ist das "index.html") enthalten sein und darf nicht entfernt werden. Wenn diese Marke fehlt, werden Meldungen oder Menüs eventuell nicht angezeigt. Sie darf zwar auch in anderen Dateien auftauchen, hat dort aber keine besondere Bedeutung.

Liste der wichtigsten Datenfelder der Gästebuchanwendung

Um die volle Liste zu sehen oder neue Felder einzufügen bzw. alte Felder zu löschen, öffnen Sie die passende Strukturdatei "guestbook.config".

Feldname Typ Pflichtfeld Defaultwert Beschreibung
GUESTBOOK_ID integer ja <auto increment> Primärschlüssel
PROFILE_ID string nein default Schlüssel des passenden Profils.
Nur für Datenbankversion. Wird bei Dateiversion über Dateinamen gelöst.
GUESTBOOK_IP string nein default IP des Autors eines Beitrages.
GUESTBOOK_IP string nein default IP des Autors eines Beitrages.
GUESTBOOK_MESSAGE string ja n/a Text des Beitrages
GUESTBOOK_MAIL string nein null Mailadresse des Autors eines Beitrages.
GUESTBOOK_DATE integer ja <CURRENT_TIMESTAMP> Erstellungsdatum eines Beitrages.
GUESTBOOK_COMMENT string nein null Kommentar des Webmasters.

HTML-Vorlagen editieren

Dieses Programm verwendet Musterseiten, sogenannte "Templates". Was auch immer Sie auf diesen Seiten ändern, ändert auch das Aussehen und Verhalten der Anwendung. Diese Dateien befinden sich im Skinverzeichnis. Sie können diese Dateien so wie normale HTML-Seiten in Ihrem Webeditor laden und ändern. Zum Ändern der Dateien sind keine HTML-Kenntnisse notwendig, bei größeren Änderungen sind diese allerdings vorteilhaft.

In jedem Fall sollten Sie sich Kopien der Originaldateien anlegen, bevor Sie Änderungen vornehmen.

Schritt-für-Schritt Anleitung:

  1. Im Basisverzeichnis Ihrer Anwendung finden Sie ein Verzeichnis mit dem Namen "skins/" in diesem Verzeichnis finden Sie alle derzeit installierten Skins.
  2. Um einen neuen Skin anzulegen kopieren Sie zunächst den Inhalt des Verzeichnisses "default/" inklusive seiner Unterverzeichnisse in ein neues Verzeichnis mit dem Namen Ihres Skins. Zum Beispiel "skins/meinSkin/".
  3. Öffnen Sie die Datei "index.html" in einem Webeditor Ihrer Wahl. Sie können dazu auch Notepad bzw. unter Unix/Linux Emacs verwenden.
  4. Passen Sie Datei Ihren Wünschen an und speichern Sie Ihre Änderungen ab.
  5. Abschließend müssen Sie eine Konfigurationsdatei für Ihren Skin erstellen. Diese Datei enthält den Namen Ihres Skins, eine Beschreibung zum Autor. Sie können dazu die Datei "skins/default.config" als Vorlage verwenden. Kopieren Sie diese Datei unter einem neuen Namen. Zum Beispiel "meinSkin.config".
  6. Diese Skindatei können Sie mit einem beliebigen Texteditor editieren. Öffnen Sie die Datei, ändern Sie die Angaben so, wie gewünscht. Achten Sie darauf, dass die Dateipfade korrekt sind. Speichern Sie anschließend Ihre Änderungen.

Tutorials zum Erstellen eigener Templates finden Sie auf der Smarty-Homepage unter: http://smarty.php.net

© 2001, 2002, 2003, 2004, 2005, 2006Homepage: Thomas Meyer, www.all-community.de