* Change formbuilder hook to not be responsible for displaying a form,

[git.ikiwiki.info.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 3ed0a3017a9717b491264a6c146056fd7f090399..b7c487ee223a3926c093ee77c49d854c35d7e2dc 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -279,10 +279,8 @@ it's a form that it needs to modify, will call various methods to
 add/remove/change fields, tweak the validation code for the fields, etc. It
 will not validate or display the form.
 
-Form validation and display can be overridden by the formbuilder hook.
-By default, ikiwiki will do a basic validation and display of the form,
-but if this hook is registered, it will stop that and let the hook take
-over.
+Just before a form is displayed to the user, the `formbuilder` hook is
+called. It can be used to validate the form, but should not display it.
 
 ### savestate
 
@@ -313,6 +311,20 @@ A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
 [[ikiwiki.setup]], which sets the hash content to configure the wiki.
 
+### %pagestate
+
+The `%pagestate` hash can be used by plugins to save state that they will need
+next time ikiwiki is run. The hash holds per-page state, so to set a value,
+use `%pagestate{$page}{$id}{$key}=$value`, and to retrieve the value,
+use `%pagestate{$page}{$id}{$key}`.
+
+`$key` can be any string you like, but `$id` must be the same as the "id"
+parameter passed to `hook()` when registering the plugin. This is so
+ikiwiki can know when to delete pagestate for plugins that are no longer
+used.
+
+When pages are deleted, ikiwiki automatically deletes their pagestate too.
+
 ### Other variables
 
 If your plugin needs to access data about other pages in the wiki. It can