version=pmwiki-2.2.10 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/532.5 (KHTML, like Gecko) Chrome/4.0.249.78 Safari/532.5
author=Peter Bowers
charset=ISO-8859-1
csum=add anchor
ctime=1161092723
host=92.60.17.45
name=PmWiki.CustomPagelistSortOrder
rev=8
targets=Cookbook.CustomPagelistSortOrderFunctions
text=(:Summary:Setting custom sort order for [[PmWiki/page lists]]:)%0aPmWiki can have custom pagelist order= values pre-set by the wiki admin in config.php.  %0aFirst, we have to tell PmWiki which function to call in response%0ato the custom order= parameter.  %0a%0aAs 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 $:WAuthor (author of the book).   In some cases the sort-order data for Group.PageName needs to come from these corresponding Data- pages.%0a%0aThere are two ways to create a custom pagelist order criteria for the pagelists.   %0a%0a!!!Method 1%0aIf the custom sort-order desired is $:Year,$:Work,$:WAuthor, let's use 'yearworkwauthor' as the %0acustom function order parameter, in which case the pagelist criteria would be:%0a-->[@(:pagelist order=yearworkwauthor:)@]%0a%0aThe array that maps order= parameters to custom comparison code to be called to perform comparisons is $PageListSortCmp:%0a%0a-->[@$PageListSortCmp['yearworkwauthor'] = 'YearWorkWAuthor($x, $y)';@]%0a%0a$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()%0aand pass those pagenames as arguments.  The YearWorkAuthor() function should return a value that is less than zero if $x %0ashould be before $y in the list, greater than zero if $x should come after $y, and zero if they're "equivalent" for the purposes %0aof this comparison.%0a%0aOf course, in this scenario, the pages given by $x and $y don't contain the values we want to sort by -- those values%0aare 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%0atest the page text variables from those pages:%0a%0a-->[@function YearWorkWAuthor($x, $y) {%0a      ## first, get the Data- versions of the pagenames%0a      $datax = 'Data-' . PageVar($x, '$BaseName');%0a      $datay = 'Data-' . PageVar($y, '$BaseName');%0a%0a      ## compare the $:Year values %0a      $c = strcmp(PageVar($datax, '$:Year'), PageVar($datay, '$:Year'));%0a      if ($c != 0) return $c;%0a%0a      ## compare the $:Work values %0a      $c = strcmp(PageVar($datax, '$:Work'), PageVar($datay, '$:Work'));%0a      if ($c != 0) return $c;%0a%0a      ## compare the $:WAuthor values%0a      $c = strcmp(PageVar($datax, '$:WAuthor'), PageVar($datay, '$:WAuthor'));%0a      return $c;%0a}@]%0a%0aIn the function above, the first two lines figure out the names of the Data-* pages%0acorresponding to $x and $y, and store them in $datax and $datay.%0aThe next two lines grab the $:Year page text variables for%0a$datax and $datay, and return a negative or positive value%0aif 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 %0afall through to test the $:Work page text variables, by%0asimilar logic, and if those are also the same we test the $:WAuthor%0apage text variables and return that.%0a%0aAs written there's a slight bit of overhead in the repeated calls%0ato PageVar() that we can avoid if speed becomes an issue, but the%0aabove code illustrates the basic concept behind the custom sort.%0a%0a%0a!!!Method 2%0aTo give the wiki user more flexibility, another approach would be to create a generic DataCompare() function%0afor comparing page text variables in Data-* pages, and then define %0aseparate "year", "work", and "wauthor" options for the order= %0aparameter that pass an appropriate argument to DataCompare():%0a%0a-->[@function DataCompare($x, $y, $var) {%0a      ## get the Data- versions of the pagenames%0a      $datax = 'Data-' . PageVar($x, '$BaseName');%0a      $datay = 'Data-' . PageVar($y, '$BaseName');%0a%0a      ## perform the requested comparison%0a      $c = strcmp(PageVar($datax, $var), PageVar($datay, $var));%0a      return $c;%0a}%0a%0a$PageListSortCmp['year'] = 'DataCompare($x, $y, "$:Year")';%0a$PageListSortCmp['work'] = 'DataCompare($x, $y, "$:Work")';%0a$PageListSortCmp['wauthor'] = 'DataCompare($x, $y, "$:WAuthor")';%0a@]%0a%0aThen one can do any number of pagelist order= combinations, such as:%0a%0a-->[@order=year           # sort by $:Year from the Data- pages%0aorder=year,work      # sort by $:Year, then $:Work%0aorder=year,-wauthor  # sort by $:Year, reverse by $:WAuthor%0aorder=wauthor        # sort by $:WAuthor only%0a@]%0a%0aThis 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.%0a%0a!!![[#alternative]]Alternative way%0aConsidering that page variables %0aare (or should be) the general pmwiki hook for doing custom things%0awith attributes and properties of pages, in whatever form.%0a%0aIn fact, here's *another* way to handle the sort/group/display%0aproblem by defining custom page variables that have exactly what%0ayou want, and without needing to define any custom sort features%0afor [@(:pagelist:)@].%0a%0aLet's define $Year, $Work, and $WAuthor page variables for%0aevery page, such that the values of $Year, $Work, and $WAuthor for any%0apage Group.XYZ are always the $:Year, $:Work, and $:WAuthor page%0atext variable from Group.XYZ's corresponding Data-* page.   In%0aother words, [@{$Year}@] for any page will always act as if one%0ahad specified [@{Data-{$BaseName}$:Year}@].%0a%0aHere are the definitions:%0a%0a-->[@$FmtPV['$Year'] =%0a  "PageTextVar('Data-'.MakeBaseName(\$pn), 'Year')";%0a%0a$FmtPV['$Work'] =%0a  "PageTextVar('Data-'.MakeBaseName(\$pn), 'Work')";%0a%0a$FmtPV['$WAuthor'] =%0a  "PageTextVar('Data-'.MakeBaseName(\$pn), 'WAuthor')";@]%0a%0aOkay, so what does this buy us?  Well, the value of [@{$Year}@] for any%0apage will always be the value of [@{$:Year}@] from its corresponding%0aData- page.  Thus [@{Group.Steinbeck$Year}@] always returns the%0avalue of [@{Data-Group.Steinbeck$Year}@].  What's more, this works%0aeven if the current page is in Data-Simile -- i.e., the value of%0a[@{Data-Group.Steinbeck$Year}@] is the same as%0a[@{Data-Group.Steinbeck$:Year}@].  (The first is a page variable,%0athe second is a page text variable.)%0a%0aSo, what we've done is to move all of the issues of relating%0apages to Data- pages out of the pagelist template and into%0asome relatively simple page variable definitions.  With this%0ain place, our pagelist directives then look like:%0a%0a-->[@(:pagelist group=Group order=$Year,$Work,$WAuthor:)%0a(:pagelist group=Data-Group order=$Year,$Work,$WAuthor:)%0a@]%0a%0aThe specification of order=$Year,$Work,$WAuthor (page variables)%0ameans that we will sort the list of pages based on the%0a$:Year, $:Work, and $:WAuthor page text variables of the%0acorresponding pages in the Data-Group group.%0a%0aNote that we also don't have to worry about whether the%0apagelist is running through the pages of the Simile or%0aData-Simile groups, because our custom page variables%0aalways map the pagename into the Data- form of the group.%0a%0aThis also greatly simplifies the pagelist template, because%0awe can now write:%0a%0a-->[@(:if ! equal {%3c$Year} {=$Year}:)%0a!! {=$Year}%0a(:if:)@]%0a%0aAgain, the '$Year' page variable is taking care of the%0adetails of obtaining $:Year from the correct [@Data-{$BaseName}@]%0apage, instead of trying to force the evaluation through the%0amarkup.%0a%0a!! See Also%0a* Cookbook:CustomPagelistSortOrderFunctions - {Cookbook.CustomPagelistSortOrderFunctions$:Summary}%0a
time=1265289137