Seitenlistenvorlagen

für die Liste aller Seiten

PmWikis Standardvorlagen für Seitenlisten sind in Site.PageListTemplates (wikilib.d) zu finden, diese Seite wird bei Upgrades ersetzt. Die darin enthaltenen Standardvorlagen können ergänzt oder überschrieben werden mit angepassten Vorlagen, die an anderer Stelle gespeichert werden.

Standard-Seitenlisten-Vorlage

PmWikis Standardkonfiguration sucht in den folgenden Seiten in dieser Reihenfolge nach der Vorlage:

1. in der Seite, deren Name als Teil der Vorlage angegeben ist,
2. in der aktuelle Seite,
3. in Site.LocalTemplates? und schließlich
4. in Site.PageListTemplates

Wenn die Vorlage in einer Seitenleiste (sidebar), im Kopf- oder Fußbereich der Gruppe (groupheader/-footer), etc. definiert ist, muss der Seitenname als Teil des Vorlagennamen angegeben werden.
Administratoren können diese Orte ändern, indem sie die Variable $FPLTemplatePageFmt benutzen.

Wenn die Vorlage in die aktuellen Seite eingebettet ist, muss die aktuelle Seite erst gespeichert werden, bevor Auswirkungen an Änderungen der Vorlage sichtbar werden. Die Vorschau allein reicht dafür nicht aus.

Angepasste Seitenlistenvorlagen

Angepasste Vorlagen werden in der gleichen Weise benutzt wie die Standardvorlagen: durch Verweisen auf das gewünschte Format mit der fmt=#anker-Option. Es gibt verschiedene Wege anzuzeigen, welche Vorlage gewünscht wird:

• fmt=#custom benutzt den #custom-Abschnitt der aktuellen Seite, der Seite Site.LocalTemplates? oder der Seite Site.PageListTemplates, je nachdem, wo der Abschnitt zuerst gefunden wird (Abschnitte sind gekennzeichnet durch [[#custom]]- und [[#customend]]-Anker).
• fmt=MeineVorlagenSeite#custom benutzt ein angepasstes Format, das in der Seite MeineVorlagenSeite im Abschnitt #custom zu finden ist.
• fmt=MeineVorlagenSeite benutzt ein angepasstes Format aus der kompletten Seite MeineVorlagenSeite.
• fmt=custom benutzt ein angepasstes Format, das in einem Kochbuchskript namens custom definiert ist. Beachten Sie das Fehlen des '#' vor custom.

Siehe Cookbook:PagelistTemplateSamples für Beispiele von angepassten Seitenlistenformaten.

Seitenlistenvorlagen erzeugen

Eine Seitenlistenvorlage enthält Standard-PmWiki-Markups. Wenn man eine Seitenlistenausgabe erzeugt, iteriert PmWiki über jede Seite, die die Seitenliste ausgibt und dekoriert jede einzelne Seite mit Formatierungsanweisungen (Markups).

Spezielle Verweise

Während der Seitenlisteniteration setzt PmWiki drei spezielle Seitenverweise: =, < und >. Diese speziellen Verweise werden für jede Seitenlisteniteration aufgefrischt und können mit der Seitenvariablen-Syntax benutzt werden, wie etwa {=$variable}, um eine Seitenlistenvorlage zu definieren, die die Seitenlistenausgabe gestaltet. Die Bedeutung dieser speziellen Verweise sind:

Die >- und <-Verweise sind höchst nützlich, um die Seitenlistenausgabe vor und nach der aktuellen Seitenliste zu strukturieren. Einige gebräuchliche Tests, mit denen man die Listenausgabe strukturieren kann, sind:

Anmerkung: Die Markups in der mittleren Spalte sind veraltet

Spezielle Markups für Seitenlistenvorlagen

Seitenlistenvorlagen können spezielle Abschnitte haben,

• (:template first ...:) und (:template ! first ...:),
• (:template last ...:) und (:template ! last ...:),

um die Ausgabe für die erste oder letzte Seite in der Gruppe zu bezeichnen (benutze !first und !last für die Ausgabe aller Seiten außer der erste/letzte Seite).

Es gibt auch ein

• (:template defaults ...:), damit eine Vorlage die Standardoption angeben kann,
• (:template each ...:), um den wiederholten Teil zu bezeichnen und
• (:template none:), dessen Inhalt erscheint, wenn keine Seite gefunden wurde (ab Version 2.2.5).

Diese erlauben Seitenlistenvorlagen einfach in Abschnitte aufzuteilen, die eingeschlossen oder nicht eingeschlossen werden in die Ausgabe, basierend auf einer Vielfalt von Bedingungen. Diese sind erweiterte Versionen der (:if ...:)-Bedingungen, die traditionell benutzt wurden, um die Seitenlistenausgabe zu steuern (trotzdem funktionieren die (:if:)-Bedingungen nach wie vor).

First, Each, Last, None

Die einfachsten Versionen der Direktiven sind:

(:template first:)      # Markup, das nur für die erste Seite angezeigt wird
(:template ! first:)    # Markup, das für jede Seite außer der ersten angezeigt wird
(:template each:)       # Markup, das für jede Seite der Liste angezeigt wird
(:template last:)       # Markup  das nur für die letzte Seite angezeigt wird
(:template ! last:)     # Markup, das für jede Seite außer der letzten angezeigt wird
(:template none:)       # Markup, das nur angezeigt wird, wenn keine Seite gefunden wurde

Eine Seitenlistenvorlage kann also Folgendes festlegen

(:template first:)
Seiten in der Liste:
(:template each:)
* [[{=$FullName}]] [-{=$:Summary}-]
(:template last:)
{$$PageCount} Seiten angezeigt.

Zusätzlich können die "first"- und "last"-Optionen weitere Argumente enthalten, die die Kontrolle unterbrechen, wenn etwas für die erste oder letzte Seite eines Kontrollabschnitts erledigt werden soll. Wenn zum Beispiel etwas ausgegeben werden soll beim Erreichen der ersten oder letzten Seite einer Gruppe, schreibt man:

(:template first {=$Group}:)
(:template last {=$Group}:)

Anstatt also Kontrollunterbrechungen zu schreiben, die die -Direktive benutzen, wie diese:

(:if ! equal {<$Group} {=$Group}:)
Gruppe: {=$Group}
(:ifend:)
* [[{=$FullName}]]

schreibt man nun:

(:template first {=$Group}:)
Gruppe: {=$Group}
(:template each:)
* [[{=$FullName}]]

Seiten-Text-Variablen und Seitenspezifische Variablen können ebenso benutzt werden, zum Beispiel

(:template default $:Maintainer=- order=$Maintainer,name:)
(:template first {=$:Maintainer}:)

Standardoptionen

Zusätzlich kann eine Vorlage Standardoptionen festlegen, die in Seitenlistenkommandos genutzt werden. Zum Beispiel würde eine Vorlage, die von einer Liste von Seiten die Titel ausgibt (und diese nach den Titeln sortiert), so geschrieben werden:

[[#bytitle]]
(:template defaults order=title:)
* [[{=$FullName}|+]]
[[#bytitleend]]

Dann schreibt der Autor (:pagelist fmt=bytitle:) und die Seiten würden automatisch nach Titeln sortiert, ohne das er "order=title" als Option in der (:pagelist:)-Direktive angeben musste.

Um mehrere Parameter für eine Option anzugeben, umschließt man sie mit doppelten Anführungszeichen, z. B. zum Sortieren nach einer Seiten-Text-Variablen und dann nach den Seitennamen

Beispiele

(:template defaults ... :)

Standardoption für Seitenlisten, die diese Vorlage benutzen

(:template each:)

Markup-Ausgabe für jede Seite der Seitenliste

(:template first:)

Markup-Ausgabe nur für die erste Seite in der Seitenliste

(:template last:)

Markup-Ausgabe nur für die letzte Seite in der Seitenliste

(:template first {=$Group}:)

Markup-Ausgabe nur für die Seite, für die der Wert von $Group sich gerade geändert hat

(:template last {=$Group}:)

Markup-Ausgabe nur für die Seite, für die der Wert von $Group sich mit der nächsten Seite ändern wird

Also haben wir:

[[#template]]
(:template defaults order=name:)
(:template first:)
Pages ordered by group
(:template first {=$Group}:)

Pages in group [[{=$Group}/]]
(:template each:)
* [[{=$FullName}]]
(:template last {=$Group}:)
   {=$Group} contains {$$GroupPageCount} pages.
(:template last:)
   {$$PageCount} pages total.
[[#templateend]] 

Zusätzliche Seitenvariablen für Seitenlistenvorlagen

Zusätliche Seitenspezifische Variablen, die nur während der Seitenlisten erreichbar sind:

{$$PageCount}       Die aktuelle Seitenzählung für diese Iteration
{$$GroupCount}      Die aktuelle Gruppenzählung für diese Iteration
{$$GroupPageCount}  Die aktuelle Seitenzählung innerhalb der Gruppe für diese Iteration
{$$EachCount}       Die aktuelle Seitenzählung innerhalb der aktuellen Schleife
{$$option}          Die Werte des Arguments 'option' von (:pagelist:)

{$$EachCount} steigt mit jeder Seite der Seitenliste und wird zurückgesetzt, wenn ein (:template first {=$Property}:)- oder ein (:template last {=$Property}:)-Abschnitt ausgegeben wird. Das kann nützlich sein, wenn eine Seitenliste nach einer Seiten(text)variablen oder einer anderen Eigenschaft sortiert ist, und die Seiten mit der gleichen Eigenschaft gruppiert werden sollen. Wenn die Sortierung $Group und die Eigenschaft "{=$Group}" ist, sind {$$EachCount} und {$$GroupPageCount} das Gleiche (Siehe Test/EachCount für Beispiele).

Gebrauch von {$$''option''}: zum Beispiel gibt {$$trail} den Seitennamen zurück, der in die trail=-Option der Seitenlisten-Direktive (:pagelist trail=...:) eingegeben wurde. Sie können eigene "Optionen" mit keinem anderen Zweck als in der Seitenliste angezeigt zu werden.

Redirect

Um die Suche nach Seiten zu ermöglichen, die nur genau eine Seite zurückliefern, und um dann anschließend gleich automatisch zu dieser Seite zu springen, fügt man das Folgende zur Seitenlistenvorlage hinzu, in der diese "Springe zu der Seite"-Funktionalität gewünscht ist:

(:template last:)
(:if equal {$$PageCount} 1:)(:redirect {=$FullName}:)(:ifend:)

Abschließen von Markups

Alle offenen Tabellen, Divs oder sonstigen Strukturen im Inneren von (:pagelist:) werden standardmäßig am Ende des Seitenlistenkommandos geschlossen. Mit anderen Worten, (:pagelist:) benimmt sich, als sei es eine komplette eigene Seite, als sei sie eben nicht dazu da, Markups zu produzieren, die dann in eine einschließende Seite eingebettet werden.

So wird z. B. eine Tabelle, die mit einer (:cell:)-Direktive im ersten (:pagelist:)-Kommando erzeugt wurde, am Ende dieser Seitenliste automatisch geschlossen. Die (:cell:)-Direktive im nächsten (:pagelist:)-Kommando startet dann eine neue Tabelle.

Anmerkung: Nicht die @(:table:)@]-Direktive öffnet eine Tabelle, es ist die (:cell:)- oder (:cellnr:)-Direktive, die das tut. Die (:table:)-Direktive ist dazu da, um ein paar Attribute für die dann folgende Tabelle setzen.

Einsatz

Es ist ratsam, die Seite Site.PageListTemplates nicht direkt zu verändern, so dass Sie weiterhin von Upgrades profitieren. Stattdessen sollten Sie die betreffende Vorlage in Ihre Site.LocalTemplates?-Seite kopieren und dort verändern (und umbenennen). Die Seite Site.LocalTemplates ist nicht Teil der PmWiki-Distribution und muss ggf. erst angelegt werden. Cookbook:PagelistTemplateSamples enthält viele Beispiele, wie Sie Seitenlistenformate an Ihre eigenen Bedürfnisse anpassen können.

Weitere Rezepte

Zusätzlich gibt es in den Kochbüchern weitere Rezepte für besondere fmt=-Optionen, einschließlich fmt=dictindex (alphabetischer Index) und fmt=forum (Forumsbeiträge).

für die Liste aller Seiten