ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / plugins / contrib / field.mdwn
1 [[!template id=plugin name=field author="[[rubykat]]"]]
2 [[!tag type/meta]]
3 [[!toc]]
4 ## NAME
5
6 IkiWiki::Plugin::field - front-end for per-page record fields.
7
8 ## SYNOPSIS
9
10     # activate the plugin
11     add_plugins => [qw{goodstuff field ....}],
12
13     # simple registration
14     field_register => [qw{meta}],
15
16     # simple registration with priority
17     field_register => {
18         meta => 'last'
19         foo => 'DD'
20     },
21
22     # allow the config to be queried as a field
23     field_allow_config => 1,
24
25     # flag certain fields as "tags"
26     field_tags => {
27         BookAuthor => '/books/authors',
28         BookGenre => '/books/genres',
29         MovieGenre => '/movies/genres',
30     }
31
32 ## DESCRIPTION
33
34 This plugin is meant to be used in conjunction with other plugins
35 in order to provide a uniform interface to access per-page structured
36 data, where each page is treated like a record, and the structured data
37 are fields in that record.  This can include the meta-data for that page,
38 such as the page title.
39
40 Plugins can register a function which will return the value of a "field" for
41 a given page.  This can be used in a few ways:
42
43 * In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing.
44 * In PageSpecs; the "field" function can be used to match the value of a field in a page.
45 * In SortSpecs; the "field" function can be used for sorting pages by the value of a field in a page.
46 * By other plugins, using the field_get_value function, to get the value of a field for a page, and do with it what they will.
47
48 ## CONFIGURATION OPTIONS
49
50 The following options can be set in the ikiwiki setup file.
51
52 **field_allow_config**
53
54     field_allow_config => 1,
55
56 Allow the $config hash to be queried like any other field; the 
57 keys of the config hash are the field names with a prefix of "CONFIG-".
58
59 **field_register**
60
61     field_register => [qw{meta}],
62
63     field_register => {
64         meta => 'last'
65         foo => 'DD'
66     },
67
68 A hash of plugin-IDs to register.  The keys of the hash are the names of the
69 plugins, and the values of the hash give the order of lookup of the field
70 values.  The order can be 'first', 'last', 'middle', or an explicit order
71 sequence between 'AA' and 'ZZ'.  If the simpler type of registration is used,
72 then the order will be 'middle'.
73
74 This assumes that the plugins in question store data in the %pagestatus hash
75 using the ID of that plugin, and thus the field values are looked for there.
76
77 This is the simplest form of registration, but the advantage is that it
78 doesn't require the plugin to be modified in order for it to be
79 registered with the "field" plugin.
80
81 **field_tags**
82
83     field_tags => {
84         BookAuthor => '/books/authors',
85         BookGenre => '/books/genres',
86         MovieGenre => '/movies/genres',
87     }
88
89 A hash of fields and their associated pages.  This provides a faceted
90 tagging system.
91
92 The way this works is that a given field-name will be associated with a given
93 page, and the values of that field will be linked to sub-pages of that page,
94 the same way that the \[[!tag ]] directive does.
95
96 This also provides a field with the suffix of `-tagpage` which gives
97 the name of the page to which that field-value is linked.
98
99 For example:
100
101         BookGenre: SF
102
103 will link to "/books/genres/SF", with a link-type of "bookgenre".
104
105 If one was using a template, then the following template:
106
107         Genre: <TMPL_VAR BOOKGENRE>
108         GenrePage: <TMPL_VAR BOOKGENRE-TAGPAGE>
109         GenreLink: \[[<TMPL_VAR BOOKGENRE-TAGPAGE>]]
110
111 would give:
112
113         Genre: SF
114         GenrePage: /books/genres/SF
115         GenreLink: <a href="/books/genres/SF/">SF</a>
116
117 ## PageSpec
118
119 The `field` plugin provides a few PageSpec functions to match values
120 of fields for pages.
121
122 * field
123   * **field(*name* *glob*)**
124   * field(bar Foo\*) will match if the "bar" field starts with "Foo".
125 * destfield
126   * **destfield(*name* *glob*)**
127   * as for "field" but matches against the destination page (i.e when the source page is being included in another page).
128 * field_item
129   * **field_item(*name* *glob*)**
130   * field_item(bar Foo) will match if one of the values of the "bar" field is "Foo".
131 * destfield_item
132   * **destfield_item(*name* *glob*)**
133   * as for "field_item" but matches against the destination page.
134 * field_null
135   * **field_null(*name*)**
136   * matches if the field is null, that is, if there is no value for that field, or the value is empty.
137 * field_tagged
138   * **field_tagged(*name* *glob*)**
139   * like `tagged`, but this uses the tag-bases and link-types defined in the `field_tags` configuration option.
140 * destfield_tagged
141   * **destfield_tagged(*name* *glob*)**
142   * as for "field_tagged" but matches against the destination page.
143
144 ## SortSpec
145
146 The "field" SortSpec function can be used to sort a page depending on the value of a field for that page.  This is used for directives that take sort parameters, such as **inline** or **report**.
147
148 field(*name*)
149
150 For example:
151
152 sort="field(bar)" will sort by the value og the "bar" field.
153
154 Additionally, the "field_natural" SortSpec function will use the
155 Sort::Naturally module to do its comparison (though it will fail if that
156 module is not installed).
157
158 ## FUNCTIONS
159
160 ### field_register
161
162 field_register(id=>$id);
163
164 Register a plugin as having field data.  The above form is the simplest, where
165 the field value is looked up in the %pagestatus hash under the plugin-id.
166
167 Additional Options:
168
169 **call=>&myfunc**
170
171 A reference to a function to call rather than just looking up the value in the
172 %pagestatus hash.  It takes two arguments: the name of the field, and the name
173 of the page.  It is expected to return (a) an array of the values of that field
174 if "wantarray" is true, or (b) a concatenation of the values of that field
175 if "wantarray" is not true, or (c) undef if there is no field by that name.
176
177     sub myfunc ($$) {
178         my $field = shift;
179         my $page = shift;
180
181         ...
182
183         return (wantarray ? @values : $value);
184     }
185
186 **first=>1**
187
188 Set this to be called first in the sequence of calls looking for values.  Since
189 the first found value is the one which is returned, ordering is significant.
190 This is equivalent to "order=>'first'".
191
192 **last=>1**
193
194 Set this to be called last in the sequence of calls looking for values.  Since
195 the first found value is the one which is returned, ordering is significant.
196 This is equivalent to "order=>'last'".
197
198 **order=>$order**
199
200 Set the explicit ordering in the sequence of calls looking for values.  Since
201 the first found value is the one which is returned, ordering is significant.
202
203 The values allowed for this are "first", "last", "middle", or a two-character
204 ordering-sequence between 'AA' and 'ZZ'.
205
206 ### field_get_value($field, $page)
207
208     my $value = field_get_value($field, $page);
209
210     my $value = field_get_value($field, $page, foo=>'bar');
211
212 Returns the value of the field for that page, or undef if none is found.
213 It is also possible to override the value returned by passing in
214 a value of your own.
215
216 ## DOWNLOAD
217
218 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
219 * git repo at git://github.com/rubykat/ikiplugins.git