doc/todo/allow_plugins_to_add_sorting_methods.mdwn

   1 [[!template id=gitbranch branch=smcv/sort-hooks author="[[Simon_McVittie|smcv]]"]]
   2 [[!tag patch]]
   3
   4 The available [[ikiwiki/pagespec/sorting]] methods are currently hard-coded in
   5 IkiWiki.pm, making it difficult to add any extra sorting mechanisms. I've
   6 prepared a branch which adds 'sort' as a hook type and uses it to implement a
   7 new `meta_title` sort type.
   8
   9 Someone could use this hook to make `\[[!inline sort=title]]` prefer the meta
  10 title over the page name, but for compatibility, I'm not going to (I do wonder
  11 whether it would be worth making sort=name an alias for the current sort=title,
  12 and changing the meaning of sort=title in 4.0, though).
  13
  14 Gitweb:
  15 <http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-hooks>
  16
  17 I briefly tried to turn *all* the current sort types into hook functions, and
  18 have some of them pre-registered, but decided that probably wasn't a good idea.
  19 That earlier version of the branch is also available for comparison:
  20
  21 <http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-hooks-excessive>
  22
  23 ## Documentation extracted from the branch
  24
  25 ### sort hook (added to [[plugins/write]])
  26
  27        hook(type => "sort", id => "foo", call => \&sort_by_foo);
  28
  29 This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides
  30 an existing one. The callback is given two page names as arguments, and
  31 returns negative, zero or positive if the first page should come before,
  32 close to (i.e. undefined order), or after the second page.
  33
  34 For instance, the built-in `title` sort order could be reimplemented as
  35
  36        sub sort_by_title {
  37                pagetitle(basename($_[0])) cmp pagetitle(basename($_[1]));
  38        }
  39
  40 ### meta_title sort order (conditionally added to [[ikiwiki/pagespec/sorting]])
  41
  42 * `meta_title` - Order according to the `\[[!meta title="foo" sort="bar"]]`
  43   or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no
  44   full title was set.
  45
  46 ### meta title sort parameter (added to [[ikiwiki/directive/meta]])
  47
  48 An optional `sort` parameter will be used preferentially when
  49 [[ikiwiki/pagespec/sorting]] by `meta_title`:
  50
  51        \[[!meta title="The Beatles" sort="Beatles, The"]]
  52
  53        \[[!meta title="David Bowie" sort="Bowie, David"]]