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 >>> Based on `field_get_value()`, yes.  That would be my ideal.  Do you think I should implement that as an ikiwiki branch? --[[KathrynAndersen]]
  26
  27 >> (On the site I mentioned, I'm using an unmodified version of `field`,
  28 >> and currently working around the collision by tagging books' pages
  29 >> with `bookauthor` instead of `author` in the YAML.) --s
  30
  31 From a coding style point of view, the `$CamelCase` variable names aren't
  32 IkiWiki style, and the `match_foo` functions look as though they could benefit
  33 from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
  34 function (see `meta` for a similar approach).
  35
  36 I think the documentation would probably be clearer in a less manpage-like
  37 and more ikiwiki-like style?
  38
  39 > 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]]
  40
  41 >> I keep getting distracted by the big shouty headings :-)
  42 >> I suppose what I was really getting at was that when this plugin
  43 >> is merged, its docs will end up split between its plugin
  44 >> page, [[plugins/write]] and [[ikiwiki/PageSpec]]; on some of the
  45 >> contrib plugins I've added I've tried to separate the docs
  46 >> according to how they'll hopefully be laid out after merge. --s
  47
  48 If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is
  49 accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can
  50 stop reimplementing sorting. Here's the implementation I'm using, with
  51 your "sortspec" concept (a sort-hook would be very similar): if merged,
  52 I think it should just be part of `field` rather than a separate plugin.
  53
  54         # Copyright © 2010 Simon McVittie, released under GNU GPL >= 2
  55         package IkiWiki::Plugin::fieldsort;
  56         use warnings;
  57         use strict;
  58         use IkiWiki 3.00;
  59         use IkiWiki::Plugin::field;
  60
  61         sub import {
  62                 hook(type => "getsetup", id => "fieldsort",  call => \&getsetup);
  63         }
  64
  65         sub getsetup () {
  66                 return
  67                         plugin => {
  68                                 safe => 1,
  69                                 rebuild => undef,
  70                         },
  71         }
  72
  73         package IkiWiki::SortSpec;
  74
  75         sub cmp_field {
  76                 if (!length $_[0]) {
  77                         error("sort=field requires a parameter");
  78                 }
  79
  80                 my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
  81                 my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
  82
  83                 $left = "" unless defined $left;
  84                 $right = "" unless defined $right;
  85                 return $left cmp $right;
  86         }
  87
  88         1;
  89
  90 -------
  91
  92 Bug report: `field` has an unnecessary `use YAML::Any`, presumably from before
  93 you separated out `ymlfront`. Trivial patch available from
  94 field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
  95 <http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/field-etc>)
  96 --[[smcv]]
  97
  98 > Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]
  99 >> Done! -K.A.
 100
 101 ----
 102
 103 Disclaimer: I've only looked at this plugin and ymlfront, not other related
 104 stuff yet. (I quite like ymlfront, so I looked at this as its dependency. :)
 105 I also don't want to annoy you with a lot of design discussion
 106 if your main goal was to write a plugin that did exactly what you wanted.
 107
 108 My first question is: Why we need another plugin storing metadata
 109 about the page, when we already have the meta plugin? Much of the
 110 complication around the field plugin has to do with it accessing info
 111 belonging to the meta plugin, and generalizing that to be able to access
 112 info stored by other plugins too. (But I don't see any other plugins that
 113 currently store such info). Then too, it raises points of confusion like
 114 smcv's discuission of field author vs meta author above. --[[Joey]]
 115
 116 > The point is exactly in the generalization, to provide a uniform interface for accessing structured data, no matter what the source of it, whether that be the meta plugin or some other plugin.
 117
 118 > There were a few reasons for this:
 119
 120 >1. In converting my site over from PmWiki, I needed something that was equivalent to PmWiki's Page-Text-Variables (which is how PmWiki implements structured data).
 121 >2. I also wanted an equivalent of PmWiki's Page-Variables, which, rather than being simple variables, are the return-value of a function.  This gives one a lot of power, because one can do calculations, derive one thing from another.  Heck, just being able to have a "basename" variable is useful.
 122 >3. I noticed that in the discussion about structured data, it was mired down in disagreements about what form the structured data should take; I wanted to overcome that hurdle by decoupling the form from the content.
 123 >4. I actually use this to solve (1), because, while I do use ymlfront, initially my pages were in PmWiki format (I wrote (another) unreleased plugin which parses PmWiki format) including PmWiki's Page-Text-Variables for structured data.  So I needed something that could deal with multiple formats.
 124
 125 > So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also.
 126 > --[[KathrynAndersen]]
 127