Angepasste Seitenlistenreihenfolge

für die Liste aller Seiten

PmWiki kann für Seitenlisten angepasste order=-Werte enthalten, die der Administrator in der /local/config.php vordefiniert. Zuerst müssen wir PmWiki mitteilen, welche Funktion aufgerufen werden soll für unseren selbstdefinierten order=-Parameter.

Als Beispiel nehmen wir eine Daten-Seite, die Seitentext-Variablen enthält, in denen Daten über Bücher gespeichert werden. Die Seite Daten-Gruppe.SeitenName enthält die kommaseparierten Werte $:Year (Jahr der Veröffentlichung, $:Work (Titel des Buches) und $:Author (Autor des Buches). In manchen Fällen sollen die Daten für die Sortierreihenfolge für Gruppe.SeitenName von diesen korrespondierenden Daten-Seiten stammen.

Es gibt zwei Wege, die angepassten Kriterien für die Seitenlistenreihenfolge zu erzeugen.

Methode 1

Wenn die gewünschte Sortierreihenfolge $:Year,$:Work,$:Author ist, benutzen wir 'yearworkauthor' als unseren eigenen Parameter für die Sortierfunktion, so dass das Seitenlistenkriterium so aussieht:

Das Array, das die order=-Parameter auf die angepassten Sortierfunktionen abbildet, die dafür aufgerufen werden sollen, ist $PageListSortCmp:

$PageListSortCmp['yearworkauthor'] = 'YearWorkAuthor'; # nur der Funktionsname (empfohlen)

oder früher

$PageListSortCmp['yearworkauthor'] = 'YearWorkAuthor($x, $y)'; # überholt seit PHP 7.2

$PageListSortCmp ist ein Array von Seitenlistenfunktionen. Jede gelistete Funktion (nach dem =) erwartet zwei Parameter – jeder Parameter enthält den Seitennamen für eine der Seiten, die sortiert werden sollen, es werden immer nur zwei Seiten miteinander verglichen. Das heißt, um einen Vergleich zwischen zwei Seiten in der Seitenliste durchzuführen (die durch $x und $y gegeben sind), rufe die Funktion YearWorkAuthor() auf und übergib die beiden Seitennamen als Argumente.

Die YearWorkAuthor()-Funktion gibt einen Wert kleiner als Null zurück, wenn $x in der Liste vor $y erscheinen soll, größer als null, wenn $x nach $y erscheinen soll und null, wenn beide Namen 'gleichwertig' im Sinne der Sortierung sind.

Natürlich enthalten in diesem Szenario die Seiten, die durch $x und $y gegeben sind, nicht die Werte, nach denen wir sortieren wollten – jene Werte sind in den korrespondierenden "Daten-*"-Seiten von $x und $y –, sonst müssten wir die Sortierung nicht anpassen. Darum suchen wir nach den korrespondierenden "Daten-"-Seiten und vergleichen die Seitentext-Variablen aus diesen Seiten:

function YearWorkAuthor($x, $y) {
      ## zuerst holen wir die "Daten-"-Version der Seitennamen
      $datax = 'Daten-' . PageVar($x, '$BaseName');
      $datay = 'Daten-' . PageVar($y, '$BaseName');

      ## vergleiche die $:Year-Werte 
      $c = strcmp(PageVar($datax, '$:Year'), PageVar($datay, '$:Year'));
      if ($c != 0) return $c;

      ## vergleiche die $:Work-Werte 
      $c = strcmp(PageVar($datax, '$:Work'), PageVar($datay, '$:Work'));
      if ($c != 0) return $c;

      ## vergleiche die $:Author-Werte
      $c = strcmp(PageVar($datax, '$:Author'), PageVar($datay, '$:Author'));
      return $c;
}

In der obigen Funktion finden die ersten beiden Zeilen den Namen der korrespondierenden "Daten-*"-Seiten von $x und $y heraus und speichern sie in $datax und $datay. Die nächsten zwei Zeilen holen die $:Year-Seitentext-Variablen aus $datax und $datay und geben einen positiven oder negativen Wert zurück, wenn sie verschieden sind. "strcmp()" ist eine eingebaute PHP-Funktion ("string compare", Stringvergleich), und die gibt einen numerischen Wert zurück, der aussagt, wie verschieden zwei Datenteile (Text) sind. Wenn sie gleich sind (d. h. $c == 0), fallen wir durch zum Test der $:Work-Seitentext-Variablen mit der gleiche Logik, und wenn auch die gleich sind, testen wir die $:Author-Seitentext-Variablen und geben das Ergebnis zurück.

So wie die Funktion geschrieben ist, gibt es ein kleines bisschen Overhead durch den wiederholten Aufruf von PageVar(), den wir vermeiden könnten, wenn Geschwindigkeit eine Rolle spielt, aber der obige Kode illustriert das Basiskonzept hinter der angepassten Sortierung.

Methode 2

Um den Wikibenutzern mehr Flexibilität zu geben, ist eine andere Annäherung, zunächst eine generische DataCompare()-Funktion für den Vergleich von Seitentext-Variablen in "Daten-*"-Seiten zu erstellen, und dann getrennte "year"-, "work"-, und "author"-Optionen für den "order="-Parameter zu definieren, die ein passendes Argument an DataCompare() übergeben.

function DataCompare($x, $y, $order) {
      $var = "$:" . ucfirst($order); # year -> $:Year
      ## hole zuerst die "Daten-"-Version der Seitennamen,
      $datax = 'Daten-' . PageVar($x, '$BaseName');
      $datay = 'Daten-' . PageVar($y, '$BaseName');

      ## führe dann den geforderten Vergleich durch.
      $c = strcmp(PageVar($datax, $var), PageVar($datay, $var));
      return $c;
}

$PageListSortCmp['year']    = 'DataCompare';
$PageListSortCmp['work']    = 'DataCompare';
$PageListSortCmp['author']  = 'DataCompare';

Beachten Sie, der folgende Kode war früher gültig, wird aber Deprecated-Warnungen in PHP 7.2 erzeugen. Siehe oben für ein Update.

Dann können Sie jede Menge an Seitenlisten-"order="-Kombinationen wählen wie:

order=year           # sortieren nach $:Year aus den "Daten-*"-Seiten
order=year,work      # sortieren nach $:Year, dann nach $:Work
order=year,-author  # sortieren nach $:Year, dann rückwärts nach $:Author
order=author        # sortieren nur nach $:Author

Das ist näher dran an dem, was ein Autor erwarten würde, weil andere Sortierkriterien vom Benutzer geformt und verschachtelt werden können. Wenn Sie Ihre Benutzer in die Lage versetzen wollen, die Sortierreihenfolge anzupassen, ohne dass Sie eine Neuprogrammierung in der config.php wegen neuer Anforderungen durchführen müssen, ist dies möglicherweise die bessere Methode.

Alternativer Weg

Berücksichtigen Sie, dass Seiten-Variablen der generelle PmWiki-Aufhänger sind (oder sein sollten), um angepasste Dinge mit den Attributen und Eigenschaften von Seiten zu machen.

Tatsächlich ist hier ein *weiterer* Weg, das Sortieren/Gruppen/Anzeigen-Problem zu behandeln, indem angepasste Seiten-Variablen definiert werden, die genau das Erwünschte haben, ohne dass irgendein benutzerdefiniertes Sortierfeature für (:pagelist:) definiert werden müsste.

Lassen Sie uns $Year-, $Work- und $Author-Seiten-Variablen für jede Seite so definieren, dass die Werte von $Year, $Work, und $Author für jede Gruppe.XYZ-Seite immer die $:Year-, $:Work-, und $:Author-Seitentext-Variablen von Gruppe.XYZs korrespondierender "Daten-*"-Seite sind. Mit anderen Worten, {$Year} für jede Seite wird immer so funktionieren, als hätten Sie {Daten-{$BaseName}$:Year} angegeben.

Hier folgen die Definitionen:

$FmtPV['$Year'] =
  "PageTextVar('Daten-'.MakeBaseName(\$pn), 'Year')";

$FmtPV['$Work'] =
  "PageTextVar('Daten-'.MakeBaseName(\$pn), 'Work')";

$FmtPV['$Author'] =
  "PageTextVar('Daten-'.MakeBaseName(\$pn), 'Author')";

Tja, was haben wir jetzt davon? Nun, der Wert von {$Year} ist immer der Wert von {$:Year} der korrespondierenden "Daten-"-Seite. Dadurch gibt {Gruppe.Steinbeck$Year} immer den Wert von {Daten-Gruppe.Steinbeck$Year} zurück. Darüber hinaus funktioniert das sogar, wenn die aktuelle Seite im Daten-Bereich ist – d. h., der Wert von {Daten-Gruppe.Steinbeck$Year} ist der gleiche wie {Daten-Gruppe.Steinbeck$:Year}. (Die erste ist eine Seiten-Variable, die zweite ist eine Seitentext-Variable.)

Was wir damit getan haben ist die Verlagerung aller Ergebnisse der den" Daten-"-Seiten entsprechenden Seiten aus den Seitenlistenvorlagen in einige relativ einfache Definitionen von Seiten-Variablen. Damit sehen unsere Seitenlisten-Direktiven so aus:

(:pagelist group=Gruppe order=$Year,$Work,$Author:)
(:pagelist group=Daten-Gruppe order=$Year,$Work,$Author:)

Die Angabe von order=$Year,$Work,$Author (Seiten-Variablen) bedeutet, dass wir die Seitenlisten auf der Basis der $:Year-, $:Work-, und $:Author-Seitentext-Variablen der korrespondierenden Seiten in der Gruppe Daten-Gruppe sortieren.

Beachten Sie, dass wir uns auch keine Sorgen darum machen müssen, ob die Seitenliste durch die Gruppe selbst oder die entsprechende "Daten-*"-Gruppe läuft, da unsere angepassten Seiten-Variablen immer die Seitennamen auf die "Daten-"-Form der Gruppen abbildet.

Das vereinfacht die Seitenlisten-Vorlage, denn wir können nun einfach schreiben:

(:if ! equal {<$Year} {=$Year}:)
!! {=$Year}
(:ifend:)

Nochmal, die '$Year'-Seiten-Variable achtet selbst auf die Details bei der Beschaffung von $:Year aus der korrekten Daten-{$BaseName}-Seite, anstatt zu versuchen, die Auswertung durch das Markup vorzunehmen.

Siehe auch

• $PageListSortCmpFunction
• Cookbook:CustomPagelistSortOrderFunctions - (angepasste Funktionen zum Erstellen von angepassten Sortierreihenfolgen bei Seitenlisten, englisch)

für die Liste aller Seiten