]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/write.mdwn
Added a comment
[git.ikiwiki.info.git] / doc / plugins / write.mdwn
index 2b820265582aaabf140e2b1457ce124b0e800122..c3f531b66aa706f7b44eb4a0b52250f16d4ca732 100644 (file)
@@ -211,6 +211,29 @@ them to `%links`. Present in IkiWiki 2.40 and later.
 The function is passed named parameters "page" and "content". Its return
 value is ignored.
 
+### <a name="readtemplate">readtemplate</a>
+
+       hook(type => "readtemplate", id => "foo", call => \&readtemplate);
+
+Runs on the raw source of a page or `*.tmpl` file that is being
+used as a template, before it is parsed by [[!cpan HTML::Template]].
+For instance, the [[plugins/templatebody]] plugin uses this to return
+the content of the [[ikiwiki/directive/templatebody]] directive (if there
+is one) instead of the page's full content.
+
+The function is passed named parameters:
+
+* `id`: the name under which the template was looked up,
+  such as `page.tmpl` or `note`
+* `page`: the name of the template as a page or attachment in the wiki,
+  such as `templates/note`, or `undef` if it's outside the wiki (e.g. in
+  `/usr/share/ikiwiki/templates`)
+* `content`: the content of the corresponding file
+* `untrusted`: true if the template was loaded from the wiki or an underlay,
+  false if it was loaded from a trusted location
+
+It should return the replacement content.
+
 ### <a name="filter">filter</a>
 
        hook(type => "filter", id => "foo", call => \&filter);
@@ -633,7 +656,7 @@ describes the plugin as a whole. For example:
   strictly required.
 * `section` can optionally specify which section in the config file
   the plugin fits in. The convention is to name the sections the
-  same as the tags used for [[plugins|plugin]] on this wiki.
+  same as the tags used for [[plugins]] on this wiki.
 
 ### genwrapper
 
@@ -684,7 +707,7 @@ wiki updates.
 
 The `%wikistate` hash can be used by a plugin to store persistant state
 that is not bound to any one page. To set a value, use
-`$wikistate{$id}{$key}=$value, where `$value` is anything Storable can
+`$wikistate{$id}{$key}=$value`, where `$value` is anything Storable can
 serialize, `$key` is any string you like, and `$id` must be the same as the
 "id" parameter passed to `hook()` when registering the plugin, so that the
 state can be dropped if the plugin is no longer used.
@@ -719,17 +742,24 @@ The `%pagesources` has can be used to look up the source filename
 of a page. So the key is the page name, and the value is the source
 filename. Do not modify this hash.
 
+Attachments also appear in this hash, with the same key and value.
+
        $pagesources{"foo"} = "foo.mdwn";
+       $pagesources{"logo/ikiwiki.png"} = "logo/ikiwiki.png";
+
 
 ### `%destsources`
 
 The `%destsources` hash records the name of the source file used to
 create each destination file. The key is the output filename (ie,
-"foo/index.html"), and the value is the source filename that it was built
-from (eg, "foo.mdwn"). Note that a single source file may create multiple
+"foo/index.html"), and the value is the name of the page that it was built
+from (eg, "foo"). Note that a single source file may create multiple
 destination files. Do not modify this hash directly; call `will_render()`.
-       
-       $destsources{"foo/index.html"} = "foo.mdwn";
+
+Attachments also appear in this hash, with the same key and value.
+
+       $destsources{"foo/index.html"} = "foo";
+       $destsources{"logo/ikiwiki.png"} = "logo/ikiwiki.png";
 
 ## Library functions
 
@@ -1259,6 +1289,20 @@ and an error message on failure.
 This hook and `rcs_preprevert` are optional, if not implemented, no revert
 web interface will be available.
 
+### `rcs_find_changes($)`
+
+Finds changes committed since the passed RCS-specific rev. Returns
+a hash of the files changed, a hash of the files deleted, and the
+current rev.
+
+This hook is optional.
+
+### `rcs_get_current_rev()`
+
+Gets a RCS-specific rev, which can later be passed to `rcs_find_changes`.
+
+This hook is optional.
+
 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to