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 Sie den Wert von $Skin in einer Konfigurationsdatei wie local/config.php wie hier setzen,

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

dann weisen Sie 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 sie eine enthäutete PmWiki-Seite 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.

1. 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.
2. 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           der Seitentitel (z. B. "SkinTemplates")
$Titlespaced     der Seitentitel mit Leerzeichen (e.g., "Skin Templates")
$Group           der Name 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 des Logo der 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 machen es $-Ersetzungen möglich, Dateien auf der Basis der aktuellen Gruppe oder des Namens der aktuellen Datei auszugeben.

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

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

<!--function:EineFunktion args-->

Diese Direktive ruft eine PHP-Funktion namens "EineFunktion" auf und übergibt den Namen der aktuellen Seite als erstes Argument und den optionalen Text hinter dem Funktionsnamen als zweites Argument. PHP-Funktionen, die auf diese Weise aufgerufen werden, sind typischerweise in einer lokalen Anpassungsdatei definiert. Args erlaubt nur ein Argument, das dann in Ihrer Funktion zerlegt werden muss. <!--function:EineFunktion arg1 arg2 arg3--> ruft EineFunktion($pagename, "arg1 arg2 arg3") auf, wenn die Vorlage abgearbeitet wird. Indes können dabei auch Variablen (wie $LastModifiedBy) eingesetzt werden.

<!--IncludeTemplate: header.tmpl-->

<!--IncludeTemplate: {$Group}.tmpl default.tmpl-->

Diese Direktive erlaubt das Einschließen einer weiteren Vorlagendatei. Die Argumente sind Dateinamen im Verzeichnis 'skins', die erste gefundene Datei wird dann in die Hauptvorlage eingefügt. Dieses Feature gibt es seit der Version 2.2.114, es ist aber per Voreinstellung deaktiviert; es muss in Ihrer Skinvorlagedatei pub/skins/mein-skin/mein-skin.php durch die Zeile SDV($GLOBALS['SkinTemplateIncludeLevel'], 1); aktiviert werden, wobei 1 die Anzahl der erlaubten Level ist, d. h. wenn eine eingeschlossene Vorlage ebenfalls eine IncludeTemplate-Direktive enthält, setzen Sie diese Zahl auf 2, bis zu einem Maximum von 10.

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 müssen Sie dazu auch ein entsprechendes Markup (zum Beispiel in der config.php) definieren:

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

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

Markup('noxyz', 'directives',  '/\\(:noxyz:\\)/i',
  "HideXYZ");
function HideXYZ() {
  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 Sie auch internationalisieren, indem Sie $[...]-Ersetzungen benutzen. 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 die Originalwendung unverändert übernommen.

Beispielsweise wird die Ersetzung $[Edit] 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