Skinvorlagen

für die Liste aller Seiten

Diese Seite beschreibt die Skinvorlagendateien (.tmpl), die benutzt werden, um PmWikis Skins (Oberflächen) zu erstellen und wie PmWiki sie benutzt. Wie in der Skins-Seite beschrieben, ist ein Skin eine Sammlung von Dateien, die das Layout von PmWiki-Seiten beschreiben. Jedes Skin muss eine Vorlagendatei enthalten, die das Skelett für die Anzeige einer PmWiki-Seite liefert. (→ Layout anpassen)

Vorlagen finden und behandeln

Wenn man den Wert von $Skin in einer Konfigurationsdatei wie local/config.php wie hier setzt,

## Benutze das 'Foo'-Skin.
$Skin = 'foo';

dann weist man PmWiki an, nach einem Skin mit diesem Namen zu suchen und es zu benutzen. Das Ergebnis der Suche mündet gewöhnlich darin, dass PmWiki eine Vorlagendatei aus dem zugehörigen Skin-Verzeichnis dieses Namens lädt. In diesem Beispiel würde es wahrscheinlich die Datei pub/skins/foo/foo.tmpl sein.

Der wirkliche Weg, den PmWiki beschreitet, wenn es eine Vorlage sucht, ist wichtig für jene, die ein komplexes Skin entwickeln, deshalb beschreiben wir hier, welche Schritte das sind:

1. Wenn $PageTemplateFmt leer ist (was es sein sollte), sammelt PmWiki die Namen aller Kandidaten für den Skin. Es startet mit den aktions-spezifischen Skins, die in $ActionSkin[$action] festgelegt sind. Dadurch wird PmWiki nach einem Skin namens 'Bar' sehen, wenn die aktuelle Aktion 'login' ist und $ActionSkin['login'] = 'Bar' ist.
2. Wenn bis dahin noch kein Skin gefunden wurde, sucht es nach dem/den Skin(s), die in der $Skins-Variablen genannt sind ($Skins darf ein Array sein). Wenn das Ende der Liste erreicht ist, ohne dass ein Skin gefunden wird, meldet es einen Fehler.
3. Beim Versuch, ein Skin zu finden, konsultiert PmWiki zuerst die $SkinLibDirs-Variable, wo es suchen muss. Skins bestehen aus server-seitigen Dateien (wie .php- und .tmpl-Dateien), die von PmWiki geladen werden und client-seitigen Dateien (wie .css-Dateien und Bildern), die vom Browser der Benutzer angefragt werden, wenn die die angehübschten PmWiki-Seiten ansehen.
   $SkinLibDirs ist ein Array aus Schlüssel/Wert-Paaren. Der Schlüssel ist ein Verzeichnis, in dem nach server-seitigen Dateien gesehen wird, der zugehörige Wert ist ein URL, der auf die öffentlichen, client-seitigen Recourcen weist, die vom Skin benutzt werden. Der Standardwert von $SkinLibDirs ist:

   $SkinLibDirs = array(
      "./pub/skins/\$Skin"      => "$PubDirUrl/skins/\$Skin",
      "$FarmD/pub/skins/\$Skin" => "$FarmPubDirUrl/skins/\$Skin");
   

   PmWiki würde mit der obigen Definition also das Skin 'foo' zu finden versuchen, indem es nach einem Verzeichnis mit dem Namen ./pub/skins/foo und dann nach $FarmD/pub/skins/foo sieht (wobei der Server $FarmD durch das Root-Server-Verzeichnis für die Farm-Dateien ersetzt). Von dem ersten dieser Verzeichnisse, das gefunden wird, wird angenommen, dass es das gesuchte Skin enthält. Dann wird $SkinDir auf den Namen des Verzeichnisses gesetzt und $SkinDirUrl auf den zugehörigen URL.
4. Wenn erst einmal ein gültiges Skin-Verzeichnis gefunden wurde, beginnt PmWiki die Dateien in diesem Verzeichnis abzuarbeiten, indem es nach einer .php-Skin-Datei sucht, die es ausführen kann. Zuerst sucht es nach einer mit dem gleichen Namen wie das Skin. Bei dem Skin 'foo' sucht es also nach foo.php. Wenn es eine solche Datei nicht findet, prüft es die Datei skin.php. Ist eine dieser beiden Dateien gefunden, lädt PmWiki sie und führt sie aus. Das erlaubt einem Skin, eigene Markups oder eigene Konfigurationsparameter zu definieren. Es erlaubt dem Skin auch, zwischen verschiedenen .tmpl-Dateien eine zum Laden auszusuchen.
   Um festzulegen, welche .tmpl-Datei geladen werden soll, ruft man schlicht LoadPageTemplate() innerhalb der skin.php-Datei mit dem Namen der .tmpl-Datei auf, die man laden will.
   LoadPageTemplate($pagename, "$SkinDir/xyz.tmpl");
   Ein Skin möchte zum Beispiel eine spezielle Vorlage benutzt sehen, wenn die Aktion 'print' ausgeführt wird:

   if ($GLOBALS['action'] == 'print')
     LoadPageTemplate($pagename, "$SkinDir/print.tmpl");
   

   Wenn es irgend eine der anderen Aktionen ist, fällt PmWiki auf das Laden der Standard-.tmpl-Datei zurück.
5. Wenn keine passende .php-Datei gefunden wurde, oder wenn diese Datei keine Vorlage lädt, dann fällt PmWiki zurück auf die Suche nach einer Vorlage mit dem selben Namen wie das Skin oder, wenn das scheitert, irgend eine .tmpl-Datei, so lange es die einzige in dem Verzeichnis ist. Wenn es eine findet, wird diese geladen und ausgeführt. Wenn nicht, wird ein Fehler gemeldet.

Vorlagendateiformat

Eine Vorlagendatei ist im Grunde genommen eine HTML-Datei, die auch Variablenersetzungen enthält (erkennbar am '$') und spezielle Direktiven, eingebettet in HTML-Kommentare. Die folgenden Direktiven sind notwendig in der Vorlagendatei:

1. Die Direktive <!--PageText--> gehört zum <body>-Abschnitt des HTML-Dokuments und weist PmWiki an, wohin der Hauptinhalt der Wikiseiten gehört.
2. Die Direktive <!--HTMLHeader-->, die in den <head>-Abschnitt des HTML-Dokuments gehört.
3. Die Direktive <!--HTMLFooter-->, die typischerweise kurz vor dem schließenden </body-Tag steht und von einigen Rezepten benutzt wird, um Dinge am Ende des HTML-Dokuments einzufügen. Vor PmWiki 2.2.0 war die <!--HTMLFooter-->-Direktive optional.

Wenn PmWiki eine Seite anzeigt, ersetzt es die Direktiven und Variablenersetzungen mit den zu dieser aktuellen Seite gehörenden Werten. Zum Beispiel wird die <"--PageText-->-Direktive durch den Seiteninhalt ersetzt, während alle Vorkommen von $PageUrl durch den URL (die Adresse) der aktuellen Seite ersetzt werden.

Anmerkung: Ihre Skinvorlage sollte kein <meta />-Tag enthalten, das den Zeichensatz (encoding) festlegt, da PmWiki dieses Tag hinzufügt, wenn es nötig ist.

Es gibt eine lange Liste von Variablen, die für die Ersetzungen in Seiten zur Verfügung stehen, zu den gebräuchlichsten gehören:

$PageUrl         der URL der aktuellen Seite
$ScriptUrl       der Basis-Url zum PHP-Skript
$Title           den Seitentitel (z. B. "SkinTemplates")
$Titlespaced     den Seitentitel mit Leerzeichen (e.g., "Skin Templates")
$Group           den Namen der aktuellen Gruppe (e.g., "PmWiki")
$FullName        der volle Name der Seite (e.g., "PmWiki.SkinTemplates")
$LastModified    die letzte Änderungszeit der Seite
$PageLogoUrl     der URL vom Logo er Site
$WikiTitle       der Titel der Site
$SkinDirUrl      der URL des Skin-Verzeichnisses

Diese letzte Variable, $SkinDirUrl, ist in Vorlagen besonders nützlich, da sie den Skindesignern erlaubt, auf andere Dateien (wie Bilder oder Stylesheets) im Skinverzeichnis zu verweisen, ohne den genauen URL zu kennen.

Die Vorlage ist nicht auf die Variablen beschränkt, die hier aufgelistet sind, nahezu jede globale PHP-Variable, die mit einem Großbuchstaben beginnt, kann in einer Skin-Vorlage eingesetzt werden. Auch Seitenspezifische Variablen können in einer Vorlage benutzt werden.

Skin-Direktiven

Neben den notwendigen <!--PageText-->- und <!--HTMLHeader-->-Direktiven stellt PmWiki andere eingebaute Direktiven zum Erzeugen der Ausgabe zur Verfügung. Es ist nicht notwendig, auch nur eine davon einzusetzen, aber sie können oft die Möglichkeiten der Skins erweitern.

<!--wiki:Main.EineSeite-->

<!--page:Main.EineSeite-->

Die <!--wiki:Main.EineSeite-->-Direktive gibt den Inhalt der Seite Main.EineSeite aus. $-Ersetzungen sind in Direktiven erlaubt, also wird eine Direktive wie <!--wiki:$Gruppe.EineSeite--> "EineSeite" aus der aktuellen Gruppe einfügen.

Wenn mehrere Seiten in der Direktive aufgelistet sind, wird diejenige benutzt, die zuerst gefunden wird. Also wird <!--wiki:$Gruppe.EineSeite Site.EineSeite--> EineSeite aus der aktuellen Gruppe ausgeben, wenn die Seite existiert, andernfalls Site.EineSeite. Wenn Site.EineSeite immer ausgegeben werden soll, sogar, wenn $Gruppe.EineSeite existiert, muss man zwei aufeinanderfolgende <!--wiki:...-->-Direktive, für jede Seite eine, einsetzen.

Die <!--wiki:...-->-Direktive zeigt nur Seiten an, für die der Browser Leserechte hat, Die <!--page:...-->-Direktive zeigt die Seite auch dann an, wenn der Browser kein Leserecht für diese Seite hat.

<!--file:einedatei.txt-->

Die <!--file:einedatei.txt-->-Direktive gibt den Inhalt einer anderen Datei aus (aus dem lokalen Dateisystem des Servers) an der Stelle, an der die Direktive steht. Wenn die einzufügende Datei ein .php-Skript ist, wird das PHP-Skript ausgeführt und seine Ausgabe an den Browser geschickt.

Wie in der <!--wiki:...-->-Direktive oben werden $-Ersetzungen auf Basis der aktuellen Gruppe und des Namens der aktuellen Datei durchgeführt.

<!--markup:...-->

Die Markup-Direktive bearbeitet jeden Text, der auf den Doppelpunkt folgt, als Wikiquelltext und zeigt das Ergebnis der Bearbeitung an.

<!--function:EineFunktion args-->

Die Direktive ruft eine PHP-Funktion namens "EineFunktion" auf, übergibt den Namen der aktuellen Seite und den Text, der dem Funktionsnamen folgt, als Argumente. PHP-Funktionen, die auf diese Weise aufgerufen werden, sind typischerweise in einer lokalen Anpassungsdatei definiert. Args erlaubt nur ein Argument, das dann zerlegt werden muss. <!--function:EineFunktion arg1 arg2 arg3--> erzeugt einen Parameter "arg1 arg2 arg3".

Seitenabschnitte

Eine Vorlagendatei kann "Abschnitte" enthalten, die in die Ausgabe eingeschlossen oder von ihr ausgeschlossen werden auf der Basis von Seitendirektiven oder anderen Kriterien. Ein Abschnitt beginnt immer mit <!--Page...Fmt--> und geht bis zum nächsten Abschnitt, dem Ende der Vorlagendatei oder <!--/Page...Fmt-->. Eine Vorlage kann zum Beispiel einen <!--PageLeftFmt-->-Abschnitt angeben, der immer dann von der Ausgabe ausgeschlossen wird, wenn die (:noleft:)-Direktive in dem Seiteninhalt auftaucht. PmWikis vordefinierte Abschnitte (und ihre zugehörigen Seitendirektiven) sind:

<!--PageHeaderFmt-->          (:noheader:)
<!--PageFooterFmt-->          (:nofooter:)
<!--PageTitleFmt-->           (:notitle:)
<!--PageLeftFmt-->            (:noleft:)
<!--PageRightFmt-->           (:noright:)
<!--PageActionFmt-->          (:noaction:)

Skindesigner können eigene Abschnitte und Markups definieren, aber zur Zeit müssen alle Abschnittnamen mit 'Page' beginnen und auf 'Fmt' enden. Wie erwähnt muss dazu auch ein entsprechendes Markup (zum Beispiel in der config.php) definiert werden:

Markup('noxyz', 'directives',  '/\\(:noxyz:\\)/ei',
    "SetTmplDisplay('PageXYZFmt',0)");

Und, besser, kompatibel mit PHP Version 5.5, für PmWiki 2.2.58+ :

Markup_e('noxyz', 'directives',  '/\\(:noxyz:\\)/i',
    "SetTmplDisplay('PageXYZFmt',0)");

Hinweis: Das Rezept Skins:TestPageDirectives kann Ihnen helfen, Ihre Skins mit einer Kombination der obigen Direktiven zu testen.

Internationalisierung (i18n)

Skins können auch internationalisiert werden, indem man $[...]-Stellvertreter benutzt. Jeder String, der innerhalb von $[...] geschrieben wird, wird als übersetzbare Wendung behandelt. Die Wendung wird in der aktuellen Übersetzungstabelle nachgesehen und ggf. durch den passenden Ausgabetext ersetzt. Gibt es keine Übersetzung, wird der Originalstring unverändert übernommen.

Der Stellvertreter $[Edit] wird durch die vorhandene Übersetzung von "Edit" ersetzt, wenn eine bekannt ist, sonst wird "Edit" ausgegeben. So kann die gleiche Vorlage für verschiedene Sprachen benutzt werden, weil z. B. an der Stelle "Editer" angezeigt wird, wenn eine französische Übersetzungstabelle vorliegt, "Bearbeiten" bei einer deutschen und "Edit", wenn es keine Übersetzung gibt.

FAQ

für die Liste aller Seiten