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.
  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
  95 For example:
  96
  97         BookGenre: SF
  98
  99 will link to "/books/genres/SF", with a link-type of "bookgenre".
 100
 101 ## PageSpec
 102
 103 The `field` plugin provides a few PageSpec functions to match values
 104 of fields for pages.
 105
 106 * field
 107   * **field(*name* *glob*)**
 108   * field(bar Foo\*) will match if the "bar" field starts with "Foo".
 109 * destfield
 110   * **destfield(*name* *glob*)**
 111   * as for "field" but matches against the destination page (i.e when the source page is being included in another page).
 112 * field_item
 113   * **field_item(*name* *glob*)**
 114   * field_item(bar Foo) will match if one of the values of the "bar" field is "Foo".
 115 * destfield_item
 116   * **destfield_item(*name* *glob*)**
 117   * as for "field_item" but matches against the destination page.
 118 * field_tagged
 119   * **field_tagged(*name* *glob*)**
 120   * like `tagged`, but this uses the tag-bases and link-types defined in the `field_tags` configuration option.
 121 * destfield_tagged
 122   * **destfield_tagged(*name* *glob*)**
 123   * as for "field_tagged" but matches against the destination page.
 124
 125 ## SortSpec
 126
 127 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**.
 128
 129 field(*name*)
 130
 131 For example:
 132
 133 sort="field(bar)" will sort by the value og the "bar" field.
 134
 135 ## FUNCTIONS
 136
 137 ### field_register
 138
 139 field_register(id=>$id);
 140
 141 Register a plugin as having field data.  The above form is the simplest, where
 142 the field value is looked up in the %pagestatus hash under the plugin-id.
 143
 144 Additional Options:
 145
 146 **call=>&myfunc**
 147
 148 A reference to a function to call rather than just looking up the value in the
 149 %pagestatus hash.  It takes two arguments: the name of the field, and the name
 150 of the page.  It is expected to return (a) an array of the values of that field
 151 if "wantarray" is true, or (b) a concatenation of the values of that field
 152 if "wantarray" is not true, or (c) undef if there is no field by that name.
 153
 154     sub myfunc ($$) {
 155         my $field = shift;
 156         my $page = shift;
 157
 158         ...
 159
 160         return (wantarray ? @values : $value);
 161     }
 162
 163 **first=>1**
 164
 165 Set this to be called first in the sequence of calls looking for values.  Since
 166 the first found value is the one which is returned, ordering is significant.
 167 This is equivalent to "order=>'first'".
 168
 169 **last=>1**
 170
 171 Set this to be called last in the sequence of calls looking for values.  Since
 172 the first found value is the one which is returned, ordering is significant.
 173 This is equivalent to "order=>'last'".
 174
 175 **order=>$order**
 176
 177 Set the explicit ordering in the sequence of calls looking for values.  Since
 178 the first found value is the one which is returned, ordering is significant.
 179
 180 The values allowed for this are "first", "last", "middle", or a two-character
 181 ordering-sequence between 'AA' and 'ZZ'.
 182
 183 ### field_get_value($field, $page)
 184
 185     my @values = field_get_value($field, $page);
 186
 187     my $value = field_get_value($field, $page);
 188
 189 Returns the values of the field for that page, or undef if none is found.
 190 Note that it will return an array of values if you ask for an array,
 191 and a scalar value if you ask for a scalar.
 192
 193 ## DOWNLOAD
 194
 195 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
 196 * git repo at git://github.com/rubykat/ikiplugins.git