220 lines
6.8 KiB
Markdown
220 lines
6.8 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}],
|
|
|
|
# simple registration with priority
|
|
field_register => {
|
|
meta => 'last'
|
|
foo => 'DD'
|
|
},
|
|
|
|
# allow the config to be queried as a field
|
|
field_allow_config => 1,
|
|
|
|
# flag certain fields as "tags"
|
|
field_tags => {
|
|
BookAuthor => '/books/authors',
|
|
BookGenre => '/books/genres',
|
|
MovieGenre => '/movies/genres',
|
|
}
|
|
|
|
## 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 a few 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.
|
|
* In SortSpecs; the "field" function can be used for sorting pages by 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.
|
|
|
|
## CONFIGURATION 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 with a prefix of "CONFIG-".
|
|
|
|
**field_register**
|
|
|
|
field_register => [qw{meta}],
|
|
|
|
field_register => {
|
|
meta => 'last'
|
|
foo => 'DD'
|
|
},
|
|
|
|
A hash of plugin-IDs to register. The keys of the hash are the names of the
|
|
plugins, and the values of the hash give the order of lookup of the field
|
|
values. The order can be 'first', 'last', 'middle', or an explicit order
|
|
sequence between 'AA' and 'ZZ'. If the simpler type of registration is used,
|
|
then the order will be 'middle'.
|
|
|
|
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.
|
|
|
|
**field_tags**
|
|
|
|
field_tags => {
|
|
BookAuthor => '/books/authors',
|
|
BookGenre => '/books/genres',
|
|
MovieGenre => '/movies/genres',
|
|
}
|
|
|
|
A hash of fields and their associated pages. This provides a faceted
|
|
tagging system.
|
|
|
|
The way this works is that a given field-name will be associated with a given
|
|
page, and the values of that field will be linked to sub-pages of that page,
|
|
the same way that the \[[!tag ]] directive does.
|
|
|
|
This also provides a field with the suffix of `-tagpage` which gives
|
|
the name of the page to which that field-value is linked.
|
|
|
|
For example:
|
|
|
|
BookGenre: SF
|
|
|
|
will link to "/books/genres/SF", with a link-type of "bookgenre".
|
|
|
|
If one was using a template, then the following template:
|
|
|
|
Genre: <TMPL_VAR BOOKGENRE>
|
|
GenrePage: <TMPL_VAR BOOKGENRE-TAGPAGE>
|
|
GenreLink: \[[<TMPL_VAR BOOKGENRE-TAGPAGE>]]
|
|
|
|
would give:
|
|
|
|
Genre: SF
|
|
GenrePage: /books/genres/SF
|
|
GenreLink: <a href="/books/genres/SF/">SF</a>
|
|
|
|
## PageSpec
|
|
|
|
The `field` plugin provides a few PageSpec functions to match values
|
|
of fields for pages.
|
|
|
|
* field
|
|
* **field(*name* *glob*)**
|
|
* field(bar Foo\*) will match if the "bar" field starts with "Foo".
|
|
* destfield
|
|
* **destfield(*name* *glob*)**
|
|
* as for "field" but matches against the destination page (i.e when the source page is being included in another page).
|
|
* field_item
|
|
* **field_item(*name* *glob*)**
|
|
* field_item(bar Foo) will match if one of the values of the "bar" field is "Foo".
|
|
* destfield_item
|
|
* **destfield_item(*name* *glob*)**
|
|
* as for "field_item" but matches against the destination page.
|
|
* field_null
|
|
* **field_null(*name*)**
|
|
* matches if the field is null, that is, if there is no value for that field, or the value is empty.
|
|
* field_tagged
|
|
* **field_tagged(*name* *glob*)**
|
|
* like `tagged`, but this uses the tag-bases and link-types defined in the `field_tags` configuration option.
|
|
* destfield_tagged
|
|
* **destfield_tagged(*name* *glob*)**
|
|
* as for "field_tagged" but matches against the destination page.
|
|
|
|
## SortSpec
|
|
|
|
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**.
|
|
|
|
field(*name*)
|
|
|
|
For example:
|
|
|
|
sort="field(bar)" will sort by the value og the "bar" field.
|
|
|
|
Additionally, the "field_natural" SortSpec function will use the
|
|
Sort::Naturally module to do its comparison (though it will fail if that
|
|
module is not installed).
|
|
|
|
## 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 (a) an array of the values of that field
|
|
if "wantarray" is true, or (b) a concatenation of the values of that field
|
|
if "wantarray" is not true, or (c) undef if there is no field by that name.
|
|
|
|
sub myfunc ($$) {
|
|
my $field = shift;
|
|
my $page = shift;
|
|
|
|
...
|
|
|
|
return (wantarray ? @values : $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.
|
|
This is equivalent to "order=>'first'".
|
|
|
|
**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.
|
|
This is equivalent to "order=>'last'".
|
|
|
|
**order=>$order**
|
|
|
|
Set the explicit ordering in the sequence of calls looking for values. Since
|
|
the first found value is the one which is returned, ordering is significant.
|
|
|
|
The values allowed for this are "first", "last", "middle", or a two-character
|
|
ordering-sequence between 'AA' and 'ZZ'.
|
|
|
|
### field_get_value($field, $page)
|
|
|
|
my $value = field_get_value($field, $page);
|
|
|
|
my $value = field_get_value($field, $page, foo=>'bar');
|
|
|
|
Returns the value of the field for that page, or undef if none is found.
|
|
It is also possible to override the value returned by passing in
|
|
a value of your own.
|
|
|
|
## DOWNLOAD
|
|
|
|
* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
|
|
* git repo at git://github.com/rubykat/ikiplugins.git
|