added field plugin

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..f7c2f4b1b
--- /dev/null
+++ b/doc/plugins/contrib/field.mdwn
@@ -0,0 +1,97 @@
+[[!template id=plugin name=pod 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