update for rename of recentchanges.mdwn to json.tl.ph.mdwn

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 2b820265582aaabf140e2b1457ce124b0e800122..7480a61489f86076206500a357cc3342362a1b2a 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -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.
 
 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);
 ### <a name="filter">filter</a>
 
        hook(type => "filter", id => "foo", call => \&filter);


@@ -435,6 +458,9 @@ object's "name" parameter to the authenticated user's name. Note that
 if the name is set to the name of a user who is not registered,
 a basic registration of the user will be automatically performed.
 
 if the name is set to the name of a user who is not registered,
 a basic registration of the user will be automatically performed.
 

+Auth plugins can use the loginselector helper plugin to let the user
+select which authentication method to use.
+

 ### <a name="sessioncgi">sessioncgi</a>
 
        hook(type => "sessioncgi", id => "foo", call => \&sessioncgi);
 ### <a name="sessioncgi">sessioncgi</a>
 
        hook(type => "sessioncgi", id => "foo", call => \&sessioncgi);


@@ -505,6 +531,10 @@ should return a message stating what the problem is, or a function
 that can be run to perform whatever action is necessary to allow the user
 to post the content.
 
 that can be run to perform whatever action is necessary to allow the user
 to post the content.
 

+If the hook is ran on a comment, it will be put in the moderation queue if
+anything but `undef` is returned. The function or error message will not
+be ran or displayed.
+

 ### <a name="editcontent">editcontent</a>
 
        hook(type => "editcontent", id => "foo", call => \&editcontent);
 ### <a name="editcontent">editcontent</a>
 
        hook(type => "editcontent", id => "foo", call => \&editcontent);


@@ -633,7 +663,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
   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
 
 
 ### genwrapper
 


@@ -684,7 +714,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
 
 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.
 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.


@@ -715,21 +745,28 @@ Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in
 
 ### `%pagesources`
 
 
 ### `%pagesources`
 

-The `%pagesources` has can be used to look up the source filename
+The `%pagesources` hash 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.
 
 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{"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,
 
 ### `%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()`.
 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
 
 
 ## Library functions
 


@@ -1259,6 +1296,20 @@ and an error message on failure.
 This hook and `rcs_preprevert` are optional, if not implemented, no revert
 web interface will be available.
 
 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
 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to