doc/plugins/contrib/field/discussion.mdwn

   1 Having tried out `field`, some comments (from [[smcv]]):
   2
   3 The general concept looks great.
   4
   5 The `pagetemplate` hook seems quite namespace-polluting: on a site containing
   6 a list of books, I'd like to have an `author` field, but that would collide
   7 with IkiWiki's use of `<TMPL_VAR AUTHOR>` for the author of the *page*
   8 (i.e. me). Perhaps it'd be better if the pagetemplate hook was only active for
   9 `<TMPL_VAR FIELD_AUTHOR>` or something? (For those who want the current
  10 behaviour, an auxiliary plugin would be easy.)
  11
  12 > No, please.  The idea is to be *able* to override field names if one wishes to, and choose, for yourself, non-colliding field names if one wishes not to.  I don't wish to lose the power of being able to, say, define a page title with YAML format if I want to, or to write a site-specific plugin which calculates a page title, or other nifty things.
  13 >It's not like one is going to lose the fields defined by the meta plugin; if "author" is defined by \[[!meta author=...]] then that's what will be found by "field" (provided the "meta" plugin is registered; that's what the "field_register" option is for).
  14 >--[[KathrynAndersen]]
  15
  16 >> Hmm. I suppose if you put the title (or whatever) in the YAML, then
  17 >> "almost" all the places in IkiWiki that respect titles will do the
  18 >> right thing due to the pagetemplate hook, with the exception being
  19 >> anything that has special side-effects inside `meta` (like `date`),
  20 >> or anything that looks in `$pagestate{foo}{meta}` directly
  21 >> (like `map`). Is your plan that `meta` should register itself by
  22 >> default, and `map` and friends should be adapted to
  23 >> work based on `getfield()` instead of `$pagestate{foo}{meta}`, then?
  24 >>
  25 >> (On the site I mentioned, I'm using an unmodified version of `field`,
  26 >> and currently working around the collision by tagging books' pages
  27 >> with `bookauthor` instead of `author` in the YAML.) --s
  28
  29 From a coding style point of view, the `$CamelCase` variable names aren't
  30 IkiWiki style, and the `match_foo` functions look as though they could benefit
  31 from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
  32 function (see `meta` for a similar approach).
  33
  34 I think the documentation would probably be clearer in a less manpage-like
  35 and more ikiwiki-like style?
  36
  37 > I don't think ikiwiki *has* a "style" for docs, does it?  So I followed the Perl Module style. And I'm rather baffled as to why having the docs laid out in clear sections... make them less clear. --[[KathrynAndersen]]
  38
  39 >> I keep getting distracted by the big shouty headings :-)
  40 >> I suppose what I was really getting at was that when this plugin
  41 >> is merged, its docs will end up split between its plugin
  42 >> page, [[plugins/write]] and [[ikiwiki/PageSpec]]; on some of the
  43 >> contrib plugins I've added I've tried to separate the docs
  44 >> according to how they'll hopefully be laid out after merge. --s
  45
  46 If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is
  47 accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can
  48 stop reimplementing sorting. Here's the implementation I'm using, with
  49 your "sortspec" concept (a sort-hook would be very similar): if merged,
  50 I think it should just be part of `field` rather than a separate plugin.
  51
  52         # Copyright © 2010 Simon McVittie, released under GNU GPL >= 2
  53         package IkiWiki::Plugin::fieldsort;
  54         use warnings;
  55         use strict;
  56         use IkiWiki 3.00;
  57         use IkiWiki::Plugin::field;
  58
  59         sub import {
  60                 hook(type => "getsetup", id => "fieldsort",  call => \&getsetup);
  61         }
  62
  63         sub getsetup () {
  64                 return
  65                         plugin => {
  66                                 safe => 1,
  67                                 rebuild => undef,
  68                         },
  69         }
  70
  71         package IkiWiki::SortSpec;
  72
  73         sub cmp_field {
  74                 if (!length $_[0]) {
  75                         error("sort=field requires a parameter");
  76                 }
  77
  78                 my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
  79                 my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
  80
  81                 $left = "" unless defined $left;
  82                 $right = "" unless defined $right;
  83                 return $left cmp $right;
  84         }
  85
  86         1;