diff options
Diffstat (limited to 'doc/plugins/contrib/field.mdwn')
-rw-r--r-- | doc/plugins/contrib/field.mdwn | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn new file mode 100644 index 000000000..745a36bcd --- /dev/null +++ b/doc/plugins/contrib/field.mdwn @@ -0,0 +1,97 @@ +[[!template id=plugin name=field author="[[rubykat]]"]] +[[!toc]] +## NAME + +IkiWiki::Plugin::field - front-end for per-page record fields. + +## SYNOPSIS + + # activate the plugin + add_plugins => [qw{goodstuff field ....}], + + # simple registration + field_register => [qw{meta}], + +## DESCRIPTION + +This plugin is meant to be used in conjunction with other plugins +in order to provide a uniform interface to access per-page structured +data, where each page is treated like a record, and the structured data +are fields in that record. This can include the meta-data for that page, +such as the page title. + +Plugins can register a function which will return the value of a "field" for +a given page. This can be used in three ways: + +* In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing. +* In PageSpecs; the "field" function can be used to match the value of a field in a page. +* 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. + +## OPTIONS + +The following options can be set in the ikiwiki setup file. + +**field_register** + +A list of plugin-IDs to register. This assumes that the plugins in +question store data in the %pagestatus hash using the ID of that plugin, +and thus the field values are looked for there. + +This is the simplest form of registration, but the advantage is that it +doesn't require the plugin to be modified in order for it to be +registered with the "field" plugin. + +## PageSpec + +The "field" PageSpec function can be used to match the value of a field for a page. + +field(*name* *glob*) + +For example: + +field(bar Foo*) will match if the "bar" field starts with "Foo". + +## FUNCTIONS + +### field_register + +field_register(id=>$id); + +Register a plugin as having field data. The above form is the simplest, where the field value +is looked up in the %pagestatus hash under the plugin-id. + +Additional Options: + +**call=>&myfunc** + +A reference to a function to call rather than just looking up the value in the %pagestatus hash. +It takes two arguments: the name of the field, and the name of the page. It is expected to return +the value of that field, or undef if there is no field by that name. + + sub myfunc ($$) { + my $field = shift; + my $page = shift; + + ... + + return $value; + } + +**first=>1** + +Set this to be called first in the sequence of calls looking for values. Since the first found +value is the one which is returned, ordering is significant. + +**last=>1** + +Set this to be called last in the sequence of calls looking for values. Since the first found +value is the one which is returned, ordering is significant. + +### field_get_value($field, $page) + +Returns the value of the field for that page, or undef if none is found. + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm> +* git repo at git://github.com/rubykat/ikiplugins.git |