Seitenlisten

für die Liste aller Seiten

PmWiki kommt mit zwei Direktiven zum Erzeugen von Seitenlisten – (:pagelist:) und (:searchresults:). Beide Direktiven sind im Grunde das Gleiche und jede nimmt die unten beschriebenen Parameter entgegen. Der eigentliche Unterschied ist, dass (:searchresults:) die Nachrichten "Suche nach ..." und "### Treffer aus insgesamt ### durchsuchten Seiten" um das Ergebnis erzeugt.

Die (:searchbox:)-Direktive erzeugt ein Such-Formular (Texteingabefeld), um die Suche anzustoßen. Das Markup nimmt die gleichen Parameter wie (:pagelist:) entgegen, wodurch es möglich ist, das Suchergebnis in gleicher Weise einzuschränken, zu sortieren und zu formatieren wie es unten für (:pagelist:) beschrieben ist. Für weitere Informationen über die (:searchbox:)-Direktive und die Art, wie sie sich von (:pagelist:) unterscheidet, springe vor zum Abschnitt Searchbox.

Grundlegende Syntax

• (:pagelist:) ohne irgendein Argument zeigt eine unnummerierte Liste aller Seiten als Links, alphabetisch und in Gruppen geordnet.
• (:pagelist group=ab name=cd fmt=template list=ef order=gh count=123 link=ij trail=kl wrap=mn passwd=op if=qr $:stv=st $sv=uv cache=0 argument1 -argument2 etc variable=value class=class :)

• (:searchbox value=abc size=99 target=def:)
• (:searchresults request=1 req=1 :)

Parameter

Alle Argumente, die in (:pagelist:) auftauchen und nicht von der Form 'Schlüssel=Wert' sind, werden als Text behandelt, der im Seitentext vorkommen muss (oder nicht darf).

Das Minus-Zeichen (-) kann benutzt werden um anzuzeigen, dass Dinge ausgeschlossen werden sollen. So listet

alle "normalen" Seiten im Dokumentations-Index auf, die "Apfel" aber nicht "Strudel" enthalten.

Mit Seiten-Text-Variablen (STV)

In der englischen Dokumentation wird die Abkürzung PTV (page text variable) benutzt.

Man kann auch Seiten-Text-Variablen als Schlüssel benutzen, um Seiten gemäß der Existenz von Seiten-Text-Variablen aufzulisten.

listet alle Seiten auf, in denen $:seitentextvar auf einwert gesetzt ist.
Minuszeichen (-), Joker (?*) und kommagetrennte Listen von Werten funktionieren auch, wenn eine Auswahl auf Seiten-Text-Variablen beruht.

Z. B. listet

alle Seiten auf, deren Variable $:eineseitentextvar auf 't*' passt, aber nicht 'test' ist.

Beispiele:

Seien Sie auf der Hut, wenn Sie (:pagelist $:MySTV=$:YourSTV :) benutzen, Seiten-Text-Variablen enthalten Formatierungen, Sie könnten nicht die Treffer erhalten, die Sie eigentlich erwartet haben. Momentan ist der einzige Weg, darum herum zu kommen, der Gebrauch von Jokern; wenn Formatstrings enthalten sind, könnten Sie sich vom Glück verlassen fühlen.

Mit Seiten-Variablen (SV)

In der englischen Dokumentation wird die Abkürzung PV (page variable) benutzt.

Seitenspezifische Variablen können in Seitenlisten auf die gleiche Weise benutzt werden wie Seiten-Text-Variablen. Siehe oben für weitere Einzelheiten. Man benutzt einfach $var statt $:var.

group= und name=

Die "group="- und "name="-Parameter begrenzen das Ergebnis auf Seiten in einer bestimmten Gruppe oder mit einem bestimmten Namen:

Joker

Namen- und Gruppenparameter können Joker-Zeichen enthalten, die nur Seiten zeigen, die auf das Muster passen:

• Ein Stern (*) steht für null oder mehr Zeichen.
• Ein Fragezeichen (?) steht für genau ein Zeichen.

Beispiele:

(:pagelist group=Cookbook  name=A*,B*   :)
(:pagelist group=Cookbook  name="A* B*" :)
(:pagelist group=Cookbook  name=[AB]*   :)
(:pagelist group=Cookbook, name=[AB]*   :)

Wenn Sie mehrfache Bedingungen in name benutzen wollen, müssen Sie Anführungszeichen als Stringbegrenzer oder Kommata ohne Leerzeichen als Trenner einsetzen. Zum Beispiel

trail=

Die "trail="-Option besorgt sich die Liste der anzuzeigenden Seiten aus einem WikiTrail:

• Zeige die Seiten in der Dokumentation an, geordnet nach der Änderungszeit

• Zeige die fünf zuletzt geänderten Seiten an

list=

Die "list="-Option erlaubt einer Suche, Seiten ein- oder auszuschließen bezüglich vom Administrator vordefinierter Muster

• "list=normal" ist vordefiniert und schließt Seiten wie AllRecentChanges, RecentChanges, GroupHeader, GroupFooter, GroupAttributes, und Ähnliches von der angezeigten Ergebnisliste aus. Beachten Sie, dass list=normal auch die aktuelle Seite ausschließt.
• "list=all" überschreibt einen Standard, den der Administrator gesetzt haben könnte, um Gruppen wie PmWiki oder Site von den gewöhnlichen Suchergebnissen auszuschließen.
• Wikiadministratoren können angepasste Listen über das Suchmuster-Array $SearchPatterns definieren (siehe Cookbook:SearchResults).

fmt=

Die "fmt="-Option bestimmt, wie das Ergebnis angezeigt wird. PmWiki definiert mehrere Formate vor:

• fmt=#bygroup - Zeige Seiten innerhalb der Gruppen an (Standardformat).
• fmt=#simple - Zeige eine einfachgeordnete Listevon Seiten an in der Form Gruppe.Name.
• fmt=#title - Zeige in der Liste die Seitentitel statt der Namen an. Um die Liste auch nach den Titeln zu sortieren, muss "order=title" hinzugefügt werden, der Standard ist eine Sortierung nach dem Seitennamen.
• fmt=#group - Zeige eine Liste von Wikigruppen (ohne die Seiten in den Gruppen).
• fmt=#include - Zeige den Inhalt jeder Seiten in der Liste an (Beachten Sie, das kann seeehr lange dauern für eine lange Liste!).

Diese Formate werden definiert in Seitenlistenvorlagen, die angepasst werden können (Siehe auch Seitenlisten mit Standardvorlagen).

fmt=count

Dies Format ist nicht in der Seitenlistenvorlage definiert:

• fmt=count - Zeige die Anzahl der Seiten in der Liste an (Beachten Sie das Fehlen des '#'). In einem 'trail' zählt fmt=count existierende und nicht existierende Seiten; um count auf existierende Seiten zu beschränken, benutzen Sie if="exists {=$FullName}" fmt=count (mailing list).

link=

Die "link="-Option implementiert Rückverweise – d. h. sie liefert eine Liste von Seiten, die auf die Zielseite verweisen. Das ist insbesondere nützlich für Kategorien und zum Finden zugehöriger Seiten.

• Alle Seiten mit einem Verweis auf den Dokumentationsindex von PmWikiDe

• Alle Seiten mit Verweisen auf die aktuelle Seite

• Alle Seiten in der "Skins"-Kategorie

Beachte, dass die "link="-Option weder negative Ziele, noch mehrere Ziele noch Joker-Zeichen entgegen nimmt. Siehe hierfür Cookbook:PageListMultiTargets.

Außerdem ignoriert link= die Direktiven (:if...:), (:include...:), (:redirect...:), (:pagelist...:) und Seitentextvariablen-Direktiven, während nach Verweisen in einer Seite gesucht wird. Das bedeutet, Verweise in eingeschlossenen Seiten werden nicht gefunden, und Verweise innerhalb nicht angezeigter bedingter Auszeichnungen werden gefunden. Im Kapitel über Seiten-Text-Variablen werden Wege beschrieben, einen Verweis auf einer Seite zu verstecken und doch link= zu erlauben, ihn zu finden.

count=

Die "count="-Option bietet die Möglichkeit,

• die Seitenliste auf ein bestimmte Anzahl von Seiten zu begrenzen,
• Ausschnitte aus der Liste anzuzeigen,
• einen Abschnitt des Listenendes anzuzeigen,
• Seiten in umgekehrter Reihenfolge anzuzeigen.

count=10       # Zeige die ersten zehn Seiten an

count=-10      # Zeige die letzten zehn Seiten an

count=1..10    # die ersten zehn Seiten
count=5..10    # 5. bis 10. Seite

count=-10..-5  # 10. von hinten, 9. von hinten, 
                 ..., 5. von hinten

count=10..     # überspringe die ersten zehn Seiten
count=..10     # 1. bis 10. Seite
count=-10..    # die letzten zehn Seiten
count=..-10    # Alle bis auf die letzten neun Seiten

count=5..10    # 5. bis 10. Seite
count=10..5    # das gleiche rückwärts
count=-1..1    # Alle Seiten von hinten 
                 nach vorn aufgelistet

(:pagelist order=-name count=10:)
(:pagelist order=-name count=1..10:)
(:pagelist order=name  count=-1..-10:) 

Vergleiche fmt=count

wrap=

Die "wrap"-Option hat die Werte none und inline.

Mit "wrap=inline" und "wrap=none" wird die Ausgabe der Seitenliste (Markup oder HTML) direkt im Markup der Seite eingebettet ohne irgendwelche umgebenden <div class=...> - </div>-Tags.

Mit "wrap=inline" wird eine umgebende <ul> fortgesetzt. Ohne "wrap=inline" startet die HTML-Ausgabe eine neue <ul> (nicht umgekehrt?). Das ist wichtig, wenn man möchte, dass die Seitenliste eine zweite Ebene in der <ul> erzeugt, denn der Beginn einer neuen Liste mit "**" führt nicht zu einer zweiten <ul>-Ebene sondern zu <dl><dd><ul>...

"wrap=inline" hat außerdem noch andere Effekte, da es den Aufruf von $FPLTemplateMarkupFunction unterdrückt (die standardmäßig MarkupToHTML ist).

class=

Standardmäßig hat eine Seitenliste die 'fpltemplate'-Klasse. Die 'bygroup'-, 'simple'-, 'group'- und 'title'-Seitenlistenformate haben eigene Klassennamen fplbygroup, fplsimple etc. Man kann selbst eine Klasse mit dem class=-Parameter angeben oder durch setzen des $FPLFormatOpt-Arrays.

request=1

Mit (:pagelist [andere Parameter] request=1:) können Sie die meisten Seitenlisten-Parameter überschreiben, indem Sie die Parameter in den URL einfügen.
Beispiele:

• (:pagelist order=name request=1:) sortiert normalerweise die Liste nach Namen. Wenn aber der URL der Seite ?order=time enthält, wird die Liste nach der Zeit sortiert.
• Enthält der URL ?order=, bleibt die Liste unsortiert.

Hinweise: Kodieren Sie jedes "#" in dem URL als "%23".
Da dieser Parameter Benutzern ohne Bearbeiten-Recht die Möglichkeit gibt, Seitenlisten nach ihrer Façon zu gestalten, sollten sie seine Sicherheitsauswirkungen für Ihre Website beachten, bevor Sie ihn einsetzen.

Seit Version 2.2.71 ist es möglich, explizit nur bei ausgewählten Parametern zu erlauben, sie zu überschreiben, oder bei einigen Parametern zu verbieten, sie zu überschreiben. Wenn Sie das brauchen, setzen Sie statt der 1 den Parameternamen ein.

Alle Parameter zum Überschreiben frei geben:
(:pagelist request=1:)

Nur die Parameter 'order' und 'count' dürfen überschrieben werden:
(:pagelist request=order,count:)

Erlaube, alle Parameter zu überschreiben, außer 'fmt' und 'trail', beachten Sie das Minuszeichen vor jedem verbotenen Parameter.
(:pagelist request=-fmt,-trail:)

req=1

Der req=1-Parameter erfordert, dass Suchbegriffe übertragen werden (das heißt, dass der Benutzer "Suchen" in einem Suchenformular angeklickt hat oder einen Verweis mit zusätzlichen Parametern folgt wie [[Page?q=terms&order=-name]]), bevor die Seitenliste erzeugt wird.
Beachten Sie, dass (:pagelist request=1 req=1:) fast wie (:searchresults:) funktioniert, wenn auch ohne die Zeilen "Suche nach ..." und "X Treffer aus insgesamt Y durchsuchten Seiten.". Beide Parameter "request=1" and "req=1" sind nötig.

Wenn eine Suche durchgeführt wird, entweder über eine searchbox-Direktive oder das Suchfeld des Skins, wird die Seite zum Darstellen des Suchergebnisses benutzt, wenn die Seite eine searchresults-Direktive enthält; enthält die Seite die searchresults-Direktive nicht, wird Site.Search für die Ausgabe des Suchergebnisses benutzt.

passwd=

Die "passwd"-Option liefert nur jene Seiten zurück, die eins der Passwortattribute gesetzt haben (z. B. passwd=write).

if=

Die "if"-Option erlaubt Bedingungen für die Erzeugung von Seitenlisten zu setzen, statt dies in den Seitenlistenvorlagen zu tun. Nur die Seiten, für die die Bedingung wahr ist, werden ausgeliefert. Alles, was in einem (:if ...:) funktioniert, kann als Bedingung genommen werden. Zum Beispiel liefert

alle Seiten aus, deren Namen in der gleiche Woche liegt wie der Name der aktuellen Seite (also der Seite, in die die Liste eingebettet ist).

Wenn ein Argument innerhalb der Anführungszeichen Leerzeichen enthalten kann, muss es in Anführungszeichen gesetzt werden.

  (:pagelist if="date 2009-01-01..2009-12-31 '{=$:Mydate}'" :)

order=

Die "order="-Option erlaubt es, die gelisteten Seiten nach unterschiedlichen Kriterien zu sortieren. Mit einem Minuszeichen erreicht man eine umgedrehte Sortierreihenfolge. Mehrfache Sortierkriterien können durch Kommata getrennt angegeben werden. Außerdem können Sie Ihre eigenen Sortierreihenfolgen erzeugen:

• order=name - alphabetisch nach Namen (Standardreihenfolge)
• order=$Name - alphabetisch nach Namen gruppenübergreifend
• order=title - alphabetisch nach Titeln statt nach Namen
• order=time - zuletzt geänderte Seiten am Ende
• order=ctime - Erstellungszeit (siehe Anmerkung)
• order=group,title - mehrfache Kriterien, in diesem Fall sortiert nach Titeln innerhalb sortierter Gruppen
• order=random - verwürfle die Seiten in eine zufällige Reihenfolge
• order=$:pagetextvarname - alphabetisch nach Seiten-Text-Variablen-Werten (keine geschweiften Klammern)
• order=$pagevarname - alphabetisch nach Seiten-Variablen-Werten (keine geschweiften Klammern)

Außerdem erlaubt die order=-Option angepasste Sortierfunktionen zu schreiben.

• Anmerkung: trail= erhält die Reihenfolge der Seiten, so wie sie in der entspechenden Seite angeordnet sind (es sei denn, man hat ausdrücklich order= eingesetzt oder es gibt eine vorgegebene Reihenfolge in der Seitenlistenvorlage). Also ist PmWikis alphabetische Standardreihenfolge außer Kraft gesetzt, wenn trail= eingesetzt wird.
• Annmerkung: ctime (Erstellungszeit) wird in den Seiten erst von PmWiki 2.1.beta15 an aufwärts gespeichert. Seiten, die mit vorherigen Versionen angelegt wurden, enthalten das ctime-Attribut nicht und können danach nicht sortiert werden.

cache=0

Seitenlisten können zwischengespeichert werden, was den Prozess erheblich beschleunigt (wenn $PageListCacheDir gesetzt ist). Hin und wieder führt dieses Zwischenspeichern zu unerwünschten Ergebnissen, die Angabe von cache=0 schaltet das Zwischenspeichern ab.

Variablen als Parameter angeben

Man kann auch Variablen innerhalb der Seitenlistenanweisung angeben und sich in der Vorlage auf diese Variablen beziehen, indem man das {$$variable1}-Format benutzt.

Das setzt voraus, dass die Site $EnableRelativePageVars gesetzt hat, was in PmWiki 2.2.0 empfohlen wird – aber standardmäßig ausgeschaltet ist, um ein Upgraden von 2.1.x zu erleichtern.

Zum Beispiel mit der Vorlage

>>comment<<
[[#tvars]]
(:template default count=1 ParamName=Simon:)
Hi, {$$ParamName}, how are you today?
[[#tvarsend]]
>><<

erhält man:

(:pagelist fmt=#tvars ParamName="Sam":)

(:pagelist fmt=#tvars ParamName="Sally":)

(:pagelist fmt=#tvars:)

Siehe auch $EnableUndefinedTemplateVars.

Beispiele

Schließe den Inhalt einer zufälligen Seite aus der Bannergruppe ein:

Zeige eine einfache Liste der zehn zuletzt geänderten Dateien an:

Zeige die "Top Twenty" der größten Kochbuch-Seiten

Die Searchbox-Direktive

Die (:searchbox:)-Direktive nimmt generell die gleichen Parameter wie die (:pagelist:)- und (:input text:)-Direktiven an:

• Seitenlisten-Parameter können zum Eingabetext der Searchbox (oder zum Markup oder zu beidem) hinzugefügt werden.
• Texteingabebox-Parameter können zum Searchbox-Markup hinzugefügt werden
  • Ein anfänglicher Suchstring kann im Searchbox-Markup angegeben werden, muss aber in der Form value='suchstring' sein. Dieser Suchstring erscheint im Eingabefeld und kann für die Suche (vor der Suche) verändert werden.
  • Die Größe des Eingabefeldes kann mit dem size-Parameter angegeben werden, wobei size=40 der aktuelle Standard ist.
    • Tipp: Wenn mehr als eine Searchbox auf der Seite erscheinen, kann man mit einem leeren Anfangswert (value='') im Markup verhindern, dass sich ein Suchstring auf alle Searchboxen ausbreitet.
• Die Zielseite für die Ausgabe des Suchergebnisses lässt sich mit dem Parameter target=GruppenName.SeitenName setzen. Der Standard ist die aktuelle Seite.
• Das ganze Searchbox-Eingabeformular kann überschrieben werden, indem man die Variable $SearchBoxFmt in seiner Konfigurationsdatei definiert. Wenn $SearchBoxFmt definiert ist, dann werden die Parameter für (:searchbox:) ignoriert und der Inhalt der $SearchBoxFmt-Variablen wird statt dessen benutzt.

Der zusätzliche Parameter label="label" kann benutzt werden, um die Aufschrift der zugehörigen Submit-Schaltfläche zu ändern.

   (:searchbox label="Durchsuche dies Wiki":)

Die Suchergebnis-Direktive

Die (:searchresults:)-Direktive nimmt generell die gleichen Parameter wie die (:pagelist:)- und (:input text:)-Direktiven an.

request=1 req=1

Die Suchergebnisse erscheinen ohne die Einleitung, die da heißt "Suche nach ..." .

Anpassen von "Suche nach ..." und "3 Treffer auf ..."

Um die Texte, die das Suchergebnis umrahmen, zu ändern, kann man das Folgende anpassen und zur local/config.php oder zur $FarmD/local/farmconfig.php hinzufügen.

XLSDV('de', array(
        'SearchFor' => 'Suchergebnis für <em>$Needle</em>:',
        'SearchFound' => 
                '$MatchCount Seiten gefunden unter $MatchSearched durchsuchten Seiten.'
));

Alternativ kann man auch die 'SearchFor'- und 'SearchFound'-Strings in der Übersetzungsseite anpassen.

Auch die $SearchResultsFmt-Variable kann in local/config.php oder $FarmD/local/farmconfig.php gesetzt werden.

SDV($SearchResultsFmt, "<div class='wikisearch'>\$[SearchFor]
    <div class='vspace'></div>\$MatchList
    <div class='vspace'></div>\$[SearchFound]</div>");

Siehe auch

• PageDirectives#attachlist - Zeige eine Liste von Anhängen an
• Site.PageListTemplates - Standard-Seitenlistenvorlagen von PmWiki
• Cookbook:PagelistTemplateSamples - beigesteuerte Seitenlistenvorlagenbeispiele
• Seitenlistenvorlagen - So erzeugt man angepasste Seitenlistenvorlagen für die fmt=-Option
• Seitenlistenvariablen - local/config.php-Anpassungen
• Cookbook:Forms - Dokumentation für (:input text:)-Markups, die für (:searchbox:) bereitgestellt werden
• Angepasste Seitenlistenreihenfolge - So setzt man eine angepasste Reihenfolge für Seitenlisten
• Cookbook:CustomPagelistSortOrderFunctions -
• Cookbook:PageListMultiTargets - (Erlaubt mehrere Ziele und Joker-Zeichen im link=-Parameter in den Seitenlisten)
• + -

für die Liste aller Seiten