* Finally implemented a simple per-page data storage mechanism for plugins,

  via the %pagestate hash.
* Use pagestate in meta to detect potential redir loops.

2 files changed, 19 insertions, 0 deletions

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 3ed0a3017..1cb26a076 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -313,6 +313,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
diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn
index 0abc9b0a0..a1a3811dc 100644
--- a/doc/plugins/write/external.mdwn
+++ b/doc/plugins/write/external.mdwn
@@ -49,6 +49,11 @@ to access any such global hash. To get the "url" configuration value,
 call `getvar("config", "url")`. To set it, call 
 `setvar("config", "url", "http://example.com/)`.
 
+The `%pagestate` is a special hash with a more complex format. To access
+it, external plugins can use the `getstate` and `setstate` RPCs. To access
+stored state, call `getstate("page", "id", "key")`, and to store state,
+call `setstate("page", "id", "key", "value")`.
+
 ## Notes on function parameters
 
 The [[plugin_interface_documentation|write]] talks about functions that take