CustomPagelistSortOrder
PmWiki can have custom pagelist order=
values pre-set by the wiki admin in config.php
.
First, we have to tell PmWiki which function to call in response to the custom order=
parameter.
As an example we have a Data-
page that contains page text variables storing data about books. The Data-Group.PageName
page contains the colon-delimited values $:Year
(year of publication), $:Work
(title of the book), and $:Author
(author of the book). In some cases the sort-order data for Group.PageName
needs to come from these corresponding Data-
pages.
There are two ways to create a custom pagelist order criteria for the pagelists.
Method 1
If the custom sort-order desired is $:Year,$:Work,$:Author
, let's use 'yearworkauthor
' as the custom function order parameter, in which case the pagelist criteria would be:
(:pagelist order=yearworkauthor:)
The array that maps order= parameters to custom comparison code to be called to perform comparisons is $PageListSortCmp
:
$PageListSortCmp['yearworkauthor'] = 'YearWorkAuthor';
# only a function name (recommended)
or previously
$PageListSortCmp['yearworkauthor'] = 'YearWorkAuthor($x, $y)';
# deprecated since PHP 7.2
$PageListSortComp
is an array of page list functions. Each function listed (after the =) expects two parameters -- each contains the pagenames for a page to be sorted; only two pages are compared at a time. Thus, this says that to perform a comparison between two pages in the pagelist (given by $x
and $y
), call the function YearWorkAuthor()
and pass those pagenames as arguments.
If you use a function name only, that function will be called with the order as a third argument.
The YearWorkAuthor()
function should return a value that is less than zero if $x
should be before $y
in the list, greater than zero if $x
should come after $y
, and zero if they're "equivalent" for the purposes of this comparison.
Of course, in this scenario, the pages given by $x
and $y
don't contain the values we want to sort by -- those values are in the corresponding Data-*
pages for $x
and $y
-- otherwise we wouldn't need to customize the sort order. Thus, we figure out the names of the "Data-
" pages, and then test the page text variables from those pages:
function YearWorkAuthor($x, $y) { ## first, get the Data- versions of the pagenames $datax = 'Data-' . PageVar($x, '$BaseName'); $datay = 'Data-' . PageVar($y, '$BaseName'); ## compare the $:Year values $c = strcmp(PageVar($datax, '$:Year'), PageVar($datay, '$:Year')); if ($c != 0) return $c; ## compare the $:Work values $c = strcmp(PageVar($datax, '$:Work'), PageVar($datay, '$:Work')); if ($c != 0) return $c; ## compare the $:Author values $c = strcmp(PageVar($datax, '$:Author'), PageVar($datay, '$:Author')); return $c; }
In the function above, the first two lines figure out the names of the Data-*
pages
corresponding to $x
and $y
, and store them in $datax
and $datay
.
The next two lines grab the $:Year
page text variables for
$datax
and $datay
, and return a negative or positive value
if they're different. "strcmp()
" is a built-in PHP function aka "string compare" and it returns a numeric value that represents how different two pieces of data (text) are. If they're the same (i.e., $c == 0
), we fall through to test the $:Work
page text variables, by similar logic, and if those are also the same we test the $:Author
page text variables and return that.
As written there's a slight bit of overhead in the repeated calls
to PageVar()
that we can avoid if speed becomes an issue, but the
above code illustrates the basic concept behind the custom sort.
Method 2
To give the wiki user more flexibility, another approach would be to create a generic DataCompare()
function
for comparing page text variables in Data-* pages, and then define
separate "year", "work", and "author" options for the order=
parameter that pass an appropriate argument to DataCompare()
:
function DataCompare($x, $y, $order) { $var = "$:" . ucfirst($order); # year -> $:Year ## get the Data- versions of the pagenames $datax = 'Data-' . PageVar($x, '$BaseName'); $datay = 'Data-' . PageVar($y, '$BaseName'); ## perform the requested comparison $c = strcmp(PageVar($datax, $var), PageVar($datay, $var)); return $c; } $PageListSortCmp['year'] = 'DataCompare'; $PageListSortCmp['work'] = 'DataCompare'; $PageListSortCmp['author'] = 'DataCompare';
Note, the following code was previously valid but will raise Deprecated warnings in PHP 7.2. See above how to update it.
function DataCompare($x, $y, $var) { ## get the Data- versions of the pagenames $datax = 'Data-' . PageVar($x, '$BaseName'); $datay = 'Data-' . PageVar($y, '$BaseName'); ## perform the requested comparison $c = strcmp(PageVar($datax, $var), PageVar($datay, $var)); return $c; } $PageListSortCmp['year'] = 'DataCompare($x, $y, "$:Year")'; $PageListSortCmp['work'] = 'DataCompare($x, $y, "$:Work")'; $PageListSortCmp['author'] = 'DataCompare($x, $y, "$:Author")';
Then one can do any number of pagelist order=
combinations, such as:
order=year # sort by $:Year from the Data- pages order=year,work # sort by $:Year, then $:Work order=year,-author # sort by $:Year, reverse by $:Author order=author # sort by $:Author only
This is more in keeping with what an author would expect, given that other sort criteria are malleable and nestable by the end user. If you want your users to be able to customize the sort order without requiring custom re-programming in config.php
when new needs arise, this is probably the better model.
Alternative way
Considering that page variables are (or should be) the general PmWiki hook for doing custom things with attributes and properties of pages, in whatever form.
In fact, here's *another* way to handle the sort/group/display
problem by defining custom page variables that have exactly what
you want, and without needing to define any custom sort features
for (:pagelist:)
.
Let's define $Year
, $Work
, and
page variables for
every page, such that the values of $Author
$Year
, $Work
, and
for any
page $Author
Group.XYZ
are always the $:Year
, $:Work
, and $:Author
page
text variable from Group.XYZ
's corresponding Data-*
page. In
other words, {$Year}
for any page will always act as if one had specified {Data-{$BaseName}$:Year}
.
Here are the definitions:
$FmtPV['$Year'] = "PageTextVar('Data-'.MakeBaseName(\$pn), 'Year')"; $FmtPV['$Work'] = "PageTextVar('Data-'.MakeBaseName(\$pn), 'Work')"; $FmtPV['$Author'] = "PageTextVar('Data-'.MakeBaseName(\$pn), 'Author')";
Okay, so what does this buy us? Well, the value of {$Year}
for any page will always be the value of {$:Year}
from its corresponding Data-
page.
Thus {Group.Steinbeck$Year}
always returns the value of {Data-Group.Steinbeck$Year}
.
What's more, this works even if the current page is in Data-Simile -- i.e., the value of {Data-Group.Steinbeck$Year}
is the same as {Data-Group.Steinbeck$:Year}
.
(The first is a page variable, the second is a page text variable.)
So, what we've done is to move all of the issues of relating
pages to Data-
pages out of the pagelist template and into
some relatively simple page variable definitions. With this
in place, our pagelist directives then look like:
(:pagelist group=Group order=$Year,$Work,$Author:) (:pagelist group=Data-Group order=$Year,$Work,$Author:)
The specification of order=$Year,$Work,
(page variables)
means that we will sort the list of pages based on the
$Author
$:Year
, $:Work
, and $:Author
page text variables of the
corresponding pages in the Data-Group
group.
Note that we also don't have to worry about whether the
pagelist is running through the pages of the Simile
or
Data-Simile
groups, because our custom page variables
always map the pagename into the Data-
form of the group.
This also greatly simplifies the pagelist template, because we can now write:
(:if ! equal {<$Year} {=$Year}:) !! {=$Year} (:ifend:)
Again, the '$Year
' page variable is taking care of the
details of obtaining $:Year
from the correct Data-{$BaseName}
page, instead of trying to force the evaluation through the
markup.
See Also
This page may have a more recent version on pmwiki.org: PmWiki:CustomPagelistSortOrder, and a talk page: PmWiki:CustomPagelistSortOrder-Talk.