getfield: query field (meta-data) values
[ikiwiki.git] / doc / plugins / contrib / getfield.mdwn
1 [[!template id=plugin name=getfield author="[[rubykat]]"]]
2 [[!tag type/meta]]
3 [[!toc]]
4 ## NAME
5
6 IkiWiki::Plugin::getfield - query the values of fields
7
8 ## SYNOPSIS
9
10     # activate the plugin
11     add_plugins => [qw{goodstuff getfield ....}],
12
13 ## DESCRIPTION
14
15 This plugin provides a way of querying the meta-data (data fields) of a page
16 inside the page content (rather than inside a template) This provides a way to
17 use per-page structured data, where each page is treated like a record, and the
18 structured data are fields in that record.  This can include the meta-data for
19 that page, such as the page title.
20
21 This plugin is meant to be used in conjunction with the B<field> plugin.
22
23 ### USAGE
24
25 One can get the value of a field by using special markup in the page.
26 This does not use directive markup, in order to make it easier to
27 use the markup inside other directives.  There are two forms:
28
29 * {{$*fieldname*}}
30
31   This queries the value of *fieldname* for the source page.
32
33   For example:
34
35         \[[!meta title="My Long and Complicated Title With Potential For Spelling Mistakes"]]
36         # {{$title}}
37
38   When the page is processed, this will give you:
39
40         <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
41
42 * {{+$*fieldname*+}}
43
44   This queries the value of *fieldname* for the destination page; that is,
45   the value when this page is included inside another page.
46
47   For example:
48
49   On PageA:
50
51         \[[!meta title="I Am Page A"]]
52         # {{+$title+}}
53
54         Stuff about A.
55
56   On PageB:
57
58         \[[!meta title="I Am Page B"]]
59         \[[!inline pagespec="PageA"]]
60
61   When PageA is displayed:
62
63         <h1>I Am Page A</h1>
64         <p>Stuff about A.</p>
65
66   When PageB is displayed:
67
68         <h1>I Am Page B</h1>
69         <p>Stuff about A.</p>
70
71 ### More Examples
72
73 Listing all the sub-pages of the current page:
74
75     \[[!map pages="{{$page}}/*"]]
76
77 ### LIMITATIONS
78
79 One cannot query the values of fields on pages other than the current
80 page or the destination page.
81
82 ## DOWNLOAD
83
84 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
85 * git repo at git://github.com/rubykat/ikiplugins.git