Point-i | PmWiki / 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 $Author page variables for every page, such that the values of $Year, $Work, and $Author for any page 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,$Author (page variables) means that we will sort the list of pages based on the $: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.

CustomPagelistSortOrder

Method 1

Method 2

Alternative way

See Also