Inhaltsverzeichnis
Anleitung für Entwickler
Templates und Skins
erstellen
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.
Die Syntax der verwendeten Version der "Smarty Template-Engine" weicht in einigen Punkten vom Referenzhandbuch ab. Der folgende Abschnitt beschreibt diese geänderte Syntax.
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.
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.
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.
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.
Diese Version führt einige neue Funktionen ein, welche die Originalversion nicht hatte.
[%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.
Datei "hello_world.html"
Hello World!
Datei "template.html"
<p>[%import file="hello_world.html"%]</p>
<p>Hello World!</p>
[%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.
[%create template="edit" file="database.config" table="bookstore"%]
[%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.
<textarea id="text"></textarea>
[%smilies target="text" width="5"%]
[%$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.
[%$foo|smilies%]
Ersetzt in einer Variable vom Typ String enthaltene Codes durch die
dazu passenden Icons.
$foo = „Text :example: Text“
wird umgesetzt zu:
Text
<img border="0" hspace="2"
src="common_files/smilies/example.gif">
Text
[%$foo|embeddedTags%]
Ersetzt in einer Variable vom Typ String Tags gemäß
der für YANA vorgegebenen Syntax.
$foo = „Text [b]Text[/b] Text“
wird umgesetzt zu:
Text <span style=“font-weight: bold;“>Text</span> Text
[%$foo|css%]
Erstellt für eine Verknüpfung mit dem angegebenen
Pfad einer CSS-Datei.
[%“default.css“|css%]
wird umgesetzt zu:
<link rel=“stylesheet“ type=“text/css“ href=“default.css“>
[%$foo|url%]
Generiert aus einer angegebenen Liste von Parametern einen Link auf das
Framework selbst.
<a href=“[%“target=1“|url%]“>Link</a>
wird umgesetzt zu:
<a href=“index.php?id=beispiel&target=1“>Link</a>
* "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. |
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. |
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.
Tutorials zum Erstellen eigener Templates finden Sie auf der Smarty-Homepage unter: http://smarty.php.net
© 2001, 2002, 2003, 2004, 2005, 2006Thomas Meyer, www.all-community.de