af5bfd6c990b8508f1be492f101c9c8faa10f942
[ikiwiki.git] / 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;
87
88 -------
89
90 Bug report: `field` has an unnecessary `use YAML::Any`, presumably from before
91 you separated out `ymlfront`. Trivial patch available from
92 field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
93 <http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/field-etc>)
94 --[[smcv]]
95
96 > Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]