116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
[[!template id=plugin name=field author="[[rubykat]]"]]
|
|
[[!tag type/meta]]
|
|
[[!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}],
|
|
|
|
# allow the config to be queried as a field
|
|
field_allow_config => 1,
|
|
|
|
## 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_allow_config**
|
|
|
|
field_allow_config => 1,
|
|
|
|
Allow the $config hash to be queried like any other field; the
|
|
keys of the config hash are the field names.
|
|
|
|
**field_register**
|
|
|
|
field_register => [qw{meta}],
|
|
|
|
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".
|
|
|
|
**destfield(*name* *glob*)**
|
|
|
|
is the same, except that it tests the destination page (that is, in cases
|
|
when the source page is being included in another page).
|
|
|
|
## 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
|