This reverts commit cc98f947cc3ddd86dc001e19a75b41daf1f0524a

[git.ikiwiki.info.git] / doc / plugins / contrib / field.mdwn

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
index 09646d28ad2dfdf94ab3aa67e985898b2b1e85a5..363d3a7eb487bd3712e936ed3306a9dd9629d4dd 100644 (file)
--- a/doc/plugins/contrib/field.mdwn
+++ b/doc/plugins/contrib/field.mdwn
@@ -13,9 +13,22 @@ IkiWiki::Plugin::field - front-end for per-page record fields.
     # simple registration
     field_register => [qw{meta}],
 
     # 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,
 
     # 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
 ## DESCRIPTION
 
 This plugin is meant to be used in conjunction with other plugins


@@ -25,13 +38,14 @@ 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
 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:
+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 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.
 
 * 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
+## CONFIGURATION OPTIONS

 
 The following options can be set in the ikiwiki setup file.
 
 
 The following options can be set in the ikiwiki setup file.
 


@@ -40,34 +54,106 @@ The following options can be set in the ikiwiki setup file.
     field_allow_config => 1,
 
 Allow the $config hash to be queried like any other field; the 
     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.
+keys of the config hash are the field names with a prefix of "CONFIG-".

 
 **field_register**
 
     field_register => [qw{meta}],
 
 
 **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.
+    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.
 
 
 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
+**field_tags**

 
 

-The "field" PageSpec function can be used to match the value of a field for a page.
+    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.

 
 

-**field(*name* *glob*)**
+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:
 
 
 For example:
 

-field(bar Foo*) will match if the "bar" field starts with "Foo".
+       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>]]

 
 

-**destfield(*name* *glob*)**
+would give:

 
 

-is the same, except that it tests the destination page (that is, in cases
-when the source page is being included in another page).
+       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
 
 
 ## FUNCTIONS
 


@@ -75,16 +161,18 @@ when the source page is being included in another page).
 
 field_register(id=>$id);
 
 
 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.
+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**
 
 
 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.
+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;
 
     sub myfunc ($$) {
        my $field = shift;


@@ -92,22 +180,38 @@ the value of that field, or undef if there is no field by that name.
 
        ...
 
 
        ...
 

-       return $value;
+       return (wantarray ? @values : $value);

     }
 
 **first=>1**
 
     }
 
 **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.
+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**
 
 
 **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.
+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)
 
 
 ### 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.
 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
 
 
 ## DOWNLOAD