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>" ] [ on_new="<string>" ] [ on_edit="<string>" ] [ on_delete="<string>" ] [ on_search="<string>" ] %]
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 |
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. |
on_new | string | nein | n/a | Name der Aktion welche ausgelöst werden soll wenn ein neuer Eintrag gespeichert werden soll |
on_edit | string | nein | n/a | Name der Aktion welche ausgelöst werden soll wenn geänderte Einträge gespeichert werden sollen |
on_delete | string | nein | n/a | Name der Aktion welche ausgelöst werden soll wenn ausgewählte Einträge gelöscht werden sollen |
on_search | string | nein | n/a | Name der Aktion welche ausgelöst werden soll um eine Suchanfrage zu bearbeiten und die Trefferliste zu erzeugen |
advanced_search | boolean | nein | false | gibt an, ob die einfache, oder die erweiterte Suchmaske mit zusätlichen Optionen angezeigt werden soll (nur für template="search") |
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|href%]
Generiert einen Link auf die Datei index.php inklusive aller
erforderlichen Parameter. Der String $foo wird an das Ende des
Search-Strings der URL angehängt. Um die URL werden
automatisch doppelte Anführungszeichen (") erzeugt.
<a href=[%"action=meinplugin_new_entry“|href%]>Neuer Eintrag</a>
wird umgesetzt zu:
<a href=“index.php?sessid=foo&id=beispiel&action=meinplugin_new_entry“>Neuer Eintrag</a>
[%$foo|url%]
Generiert ebenso wie der Modifier "href" einen Link, allerdings ohne
Anführungszeichen zu erzeugen.
<meta http-equiv="Refresh" content="2; URL=[%"action=meinplugin_new_entry"|url%]">
wird umgesetzt zu:
<meta http-equiv="Refresh" content="2;
URL=index.php?sessid=foo&id=beispiel&action=meinplugin_new_entry">
Achtung! Folgendes funktioniert NICHT: <a href="[%"action=meinplugin_new_entry“|url%]">link</a>
Ergebnis: <a
href="skins/default/index.php?sessid=foo&id=beispiel&action=meinplugin_new_entry">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_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. |
Um aufklappbare Menüs mit YANA zu erzeugen benötigen Sie keine Programmierkenntnisse. Gehen Sie wie folgt vor:
<ul class="menu root">
<li class="entry"><a href="ziel.html">Link</a></li>
<li class="menu">
<div onclick="yanaMenu(this)">Menü 1</div>
<ul class="menu">
<li class="entry"><a href="1.html">Eintrag 1</a></li>
</ul>
</li>
<li class="menu">
<div onclick="yanaMenu(this)">Menü 2</div>
<ul class="menu">
<li class="entry"><a href="2.html">Eintrag 2</a></li>
<div onclick="yanaMenu(this)">Submenü 2.1</div>
<ul class="menu">
<li class="entry"><a href="2_1.html">Eintrag 2.1</a></li>
</ul>
</ul>
</li>
<li class="menu">
<div onclick="yanaMenu(this)">Ein geschlossenes Menü</div>
<ul class="menu" style="display: none;">
<li class="entry"><a href="2.html">Eintrag 3 (nicht sichtbar)</a></li>
</ul>
</li>
</ul>
Achten Sie bei obigem Beispiel auf die hier kursiv gestellten Attribute. Das Attribut "onclick" enthält hier den Aufruf zum Öffnen und Schließen des Menüs. "Style"-Attribute legen abweichende Eigenschaften fest, wobei "display: none" das Menü ausblendet. Menüs sind von einem Element der CSS-Klasse "menu" umschlossen. Menüeinträge sind umschlossen von einem Element der CSS-Klasse "entry". Die Überschrift eines Menüs wird mit "div"-Tags umschlossen, welche auch das Attribut "onclick" erhalten. Durch Anklicken der Überschrift kann das Menü geschlossen oder geöffnet werden.
Es gilt folgende Voreinstellung: alle Menüs sind zunächst geöffnet, wenn Sie nicht explizit als geschlossen gekennzeichnet sind. Es können mehrere Menüs gleichzeitig geöffnet sein.
Falls Sie wünschen, dass stets nur 1 Menü gleichzeitig geöffnet sein soll, fügen Sie folgenden Quellcode hinzu:
<script type="text/javascript">
yana_menu_auto_close = true;
</script>
Falls Sie wünschen, dass zu Anfang alle Menüs geschlossen sind, verwenden Sie folgenden Quellcode:
<script type="text/javascript">
yanaCloseAll();
</script>
Beide Varianten können kombiniert werden.
Die Darstellung des Menüs entspricht den gängigen Empfehlungen und ist suchmaschinenfreundlich.
Das Layout wird in der Datei "skins/default/styles/menu.css" festgelegt und kann über folgende CSS-Klassen gesteuert werden:
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
Wenn Sie nicht nur ein bereits existierendes Template editieren, sondern ein neues - oder vielleicht sogar einen neuen Skin - erstellen wollen, dann genügt es nicht, die Template-Dateien zu editieren. Sondern Sie müssen auch die Konfiguration der Templates und Skins verstehen und anwenden.
Dies ist jedoch sehr einfach und erschöpft sich in zwei Konfigurationsdateien. Eine davon für Ihre neuen Templates und die andere für Ihren neuen Skin.
Im Folgenden ein einfaches Beispiel.
<SKIN_INFO> <NAME>mein Skin</NAME> <BESCHREIBUNG>das ist eine Beschreibung meines Skins</BESCHREIBUNG> <AUTOR>mein Name</AUTOR> <KONTAKT>meine Webseite</KONTAKT> <GRAFIK>%SKINDIR%mein_skin/data/preview.gif</GRAFIK> <DIRECTORY>mein_skin/</DIRECTORY> </SKIN_INFO>
Die Syntax ist weitgehend selbsterklärend. Die Felder "Name", "Beschreibung", "Autor" und "Kontakt" sind Freitext. Für das Feld "Name" können Sie sich einen beliebigen Namen ausdenken, der Ihren Skin beschreibt. Ebenso beliebig ist das Feld "Beschreibung". Achten Sie darauf, dass als Whitespace nur Leerzeichen erlaubt sind. Sie können einen Zeilenumbruch bei Bedarf einfügen, indem Sie den Text "[br]" verwenden. Das Feld "Autor" sollte Ihren Namen enthalten und das Feld "Kontakt" sinnvollerweise eine Mail- oder Internetadresse, über welche man Sie erreichen und/oder Updates downloaden kann.
Das Feld "Grafik" gibt eine Vorschaugrafik an. Der Platzhalter %SKINDIR% bezieht sich auf das Verzeichnis, in welchem die Skins gespeichert sind und sollte stets angegeben werden. Die Grafik sollte vorzugsweise im GIF-, PNG- oder JPEG-Format gespeichert sein und etwa 300x300 Pixel groß sein.
Das Feld "Directory" muss stets angegeben werden. Es gibt an in welchem Verzeichnis der Skin gespeichert ist.
Im Folgenden ein einfaches Beispiel.
<MY_TEMPLATE> <FILE>template.html</FILE> <STYLE> <0>style/default.css</0> <1>foo1/foo2.css</1> <MEIN_CSS>foo3/foo4.css</MEIN_CSS> </STYLE> <SCRIPT> <0>foo5/foo6.js</0> <MEIN_SCRIPT>foo7/foo8.js</MEIN_SCRIPT> </SCRIPT> <LANGUAGE> <0>guestbook</0> <1>admin</1> </LANGUAGE> </MY_TEMPLATE>
Beachten Sie, dass "MY_TEMPLATE" als Identifier fungiert, welcher das Template identifiziert. Sie können diese Id in den Konfigurationsdateien Ihrer Plugins verwenden, um auf das Template zu verweisen. Der Text kann beliebig gewählt werden. Achten Sie jedoch darauf, dass die Id keine Sonderzeichen oder Leerzeichen enthält, mit einem Buchstaben beginnt und über die gesamte Anwendung hinweg eindeutig ist. Groß- und Kleinschreibung spielt keine Rolle.
Es gibt 4 Felder: "File", "Style", "Script" und "Language". Das Feld "File" gibt den Dateinamen an. Die restlichen Felder sind optional und dienen der Automatisierung.
Das Feld "Language" enthält Verweise auf eine oder mehrere Dateien, welche die Sprachinformationen für dieses Template enthalten. Beispielsweise bezieht sich der Wert "guestbook" auf die Datei "languages/XX/guestbook.config", wobei der Text "XX" automatisch vom System durch die vom Nutzer gewählte Sprache ersetzt wird. Zum Beispiel "de" für Deutsch beziehungsweise "en" für Englisch.
Das Feld "Style" kann mehrere Verweise auf Stylesheets enthalten. Ebenso enthält das Feld "Script" einen oder mehrere Verweise auf JavaScript-Dateien. Die angegebenen Dateien werden jeweils automatisch eingebunden, wenn das Template aufgerufen wird.
Hinweis: Ist in einem Skin ein erforderliches Template nicht definiert oder sind Eigenschaften dieses Templates ("Styles", "Script", "Languages") nicht erneut erklärt, so fällt das Programm automatisch auf den "Default"-Skin zurück.
Dies geschieht wie folgt.
Dieses Verhalten mag zunächst unlogisch erscheinen, hat jedoch einen durchaus einen tieferen Sinn. Es erlaubt einzelne Stylesheets oder Scripts in einem neu erstellten Skin ganz gezielt auszutauschen. Gleichzeitig gestattet es aber auch einzelne Stylesheets oder Scripts von diesem Mechanismus auszuschließen. Beide Variante kommen vor und haben ihre Einsatzgebiete.
© 2001, 2002, 2003, 2004, 2005, 2006Thomas Meyer, www.all-community.de/pub