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     # allow the config to be queried as a field
  17     field_allow_config => 1,
  18
  19 ## DESCRIPTION
  20
  21 This plugin is meant to be used in conjunction with other plugins
  22 in order to provide a uniform interface to access per-page structured
  23 data, where each page is treated like a record, and the structured data
  24 are fields in that record.  This can include the meta-data for that page,
  25 such as the page title.
  26
  27 Plugins can register a function which will return the value of a "field" for
  28 a given page.  This can be used in three ways:
  29
  30 * In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing.
  31 * In PageSpecs; the "field" function can be used to match the value of a field in a page.
  32 * 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.
  33
  34 ## OPTIONS
  35
  36 The following options can be set in the ikiwiki setup file.
  37
  38 **field_allow_config**
  39
  40     field_allow_config => 1,
  41
  42 Allow the $config hash to be queried like any other field; the
  43 keys of the config hash are the field names.
  44
  45 **field_register**
  46
  47     field_register => [qw{meta}],
  48
  49 A list of plugin-IDs to register.  This assumes that the plugins in
  50 question store data in the %pagestatus hash using the ID of that plugin,
  51 and thus the field values are looked for there.
  52
  53 This is the simplest form of registration, but the advantage is that it
  54 doesn't require the plugin to be modified in order for it to be
  55 registered with the "field" plugin.
  56
  57 ## PageSpec
  58
  59 The "field" PageSpec function can be used to match the value of a field for a page.
  60
  61 **field(*name* *glob*)**
  62
  63 For example:
  64
  65 field(bar Foo*) will match if the "bar" field starts with "Foo".
  66
  67 **destfield(*name* *glob*)**
  68
  69 is the same, except that it tests the destination page (that is, in cases
  70 when the source page is being included in another page).
  71
  72 ## FUNCTIONS
  73
  74 ### field_register
  75
  76 field_register(id=>$id);
  77
  78 Register a plugin as having field data.  The above form is the simplest, where the field value
  79 is looked up in the %pagestatus hash under the plugin-id.
  80
  81 Additional Options:
  82
  83 **call=>&myfunc**
  84
  85 A reference to a function to call rather than just looking up the value in the %pagestatus hash.
  86 It takes two arguments: the name of the field, and the name of the page.  It is expected to return
  87 the value of that field, or undef if there is no field by that name.
  88
  89     sub myfunc ($$) {
  90         my $field = shift;
  91         my $page = shift;
  92
  93         ...
  94
  95         return $value;
  96     }
  97
  98 **first=>1**
  99
 100 Set this to be called first in the sequence of calls looking for values.  Since the first found
 101 value is the one which is returned, ordering is significant.
 102
 103 **last=>1**
 104
 105 Set this to be called last in the sequence of calls looking for values.  Since the first found
 106 value is the one which is returned, ordering is significant.
 107
 108 ### field_get_value($field, $page)
 109
 110 Returns the value of the field for that page, or undef if none is found.
 111
 112 ## DOWNLOAD
 113
 114 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
 115 * git repo at git://github.com/rubykat/ikiplugins.git