web commit by JordaPolo: Updated status and URLs.

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 8b0cdfdaa2fc1c25e13096447fba577ab9e0b62f..a122845af470fa4f40c46b5ad8caf93900590ebd 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -62,13 +62,22 @@ configuration. It's called early in the startup process. The
 function is passed no values. It's ok for the function to call
 `error()` if something isn't configured right.
 
 function is passed no values. It's ok for the function to call
 `error()` if something isn't configured right.
 

+### needsbuild
+
+       hook(type => "needsbuild", id => "foo", call => \&needsbuild);
+
+This allows a plugin the manipulate the list of files that need to be
+built when the wiki is refreshed. The function is passed a reference to an
+array of pages that will be rebuilt, and can modify the array, either
+adding or removing files from it.
+

 ### filter
 
        hook(type => "filter", id => "foo", call => \&filter);
 
 Runs on the raw source of a page, before anything else touches it, and can
 ### filter
 
        hook(type => "filter", id => "foo", call => \&filter);
 
 Runs on the raw source of a page, before anything else touches it, and can

-make arbitrary changes. The function is passed named parameters `page` and
-`content` and should return the filtered content.
+make arbitrary changes. The function is passed named parameters "page",
+"destpage", and "content". It should return the filtered content.

 
 ### preprocess
 
 
 ### preprocess
 


@@ -119,17 +128,28 @@ return the htmlized content.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 

-[[Templates]] are filled out for many different things in ikiwiki, like
-generating a page, or part of a blog page, or an rss feed, or a cgi. This
-hook allows modifying those templates. The function is passed named
-parameters. The "page" and "destpage" parameters are the same as for a
-preprocess hook. The "template" parameter is a [[cpan HTML::Template]]
-object that is the template that will be used to generate the page. The
-function can manipulate that template object.
+[[Templates|wikitemplate]] are filled out for many different things in
+ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
+a cgi. This hook allows modifying the variables available on those
+templates. The function is passed named parameters. The "page" and
+"destpage" parameters are the same as for a preprocess hook. The "template"
+parameter is a [[cpan HTML::Template]] object that is the template that
+will be used to generate the page. The function can manipulate that
+template object.

 
 

-The most common thing to do is probably to call $template->param() to add
+The most common thing to do is probably to call `$template->param()` to add

 a new custom parameter to the template.
 
 a new custom parameter to the template.
 

+### templatefile
+
+       hook(type => "templatefile", id => "foo", call => \&templatefile);
+
+This hook allows plugins to change the [[template|wikitemplate]] that is
+used for a page in the wiki. The hook is passed a "page" parameter, and
+should return the name of the template file to use, or undef if it doesn't
+want to change the default ("page.tmpl"). Template files are looked for in
+/usr/share/ikiwiki/templates by default.
+

 ### sanitize
 
        hook(type => "sanitize", id => "foo", call => \&sanitize);
 ### sanitize
 
        hook(type => "sanitize", id => "foo", call => \&sanitize);


@@ -172,7 +192,7 @@ source files that were rendered.
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the

-parameters, and if it will handle this CGI request, output a page and
+parameters, and if it will handle this CGI request, output a page (including the http headers) and

 terminate the program.
 
 ### auth
 terminate the program.
 
 ### auth


@@ -274,7 +294,7 @@ ikiwiki program.
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
 Note that in addition to the named parameters described above, a parameter
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
 Note that in addition to the named parameters described above, a parameter

-named no_override is supported, If it's set to a true value, then this hook
+named `no_override` is supported, If it's set to a true value, then this hook

 will not override any existing hook with the same id. This is useful if
 the id can be controled by the user.
 
 will not override any existing hook with the same id. This is useful if
 the id can be controled by the user.
 


@@ -299,7 +319,7 @@ appear on the wiki page, rather than calling error().
 
 Creates and returns a [[cpan HTML::Template]] object. The first parameter
 is the name of the file in the template directory. The optional remaining
 
 Creates and returns a [[cpan HTML::Template]] object. The first parameter
 is the name of the file in the template directory. The optional remaining

-parameters are passed to HTML::Template->new.
+parameters are passed to `HTML::Template->new`.

 
 #### `htmlpage($)`
 
 
 #### `htmlpage($)`
 


@@ -380,7 +400,7 @@ A failure to write the file will result in it dying with an error.
 
 If the destination directory doesn't exist, it will first be created.
 
 
 If the destination directory doesn't exist, it will first be created.
 

-### `will_render($$)`
+#### `will_render($$)`

 
 Given a page name and a destination file name (not including the base
 destination directory), register that the page will result in that file
 
 Given a page name and a destination file name (not including the base
 destination directory), register that the page will result in that file


@@ -413,7 +433,9 @@ This is the standard gettext function, although slightly optimised.
 
 #### `urlto($$)`
 
 
 #### `urlto($$)`
 

-Construct a relative url to the first parameter from the second.
+Construct a relative url to the first parameter from the page named by the
+second. The first parameter can be either a page name, or some other
+destination file, as registered by `will_render`.

 
 #### `targetpage($$)`
 
 
 #### `targetpage($$)`
 


@@ -426,9 +448,9 @@ ikiwiki's support for revision control systems also uses pluggable perl
 modules. These are in the `IkiWiki::RCS` namespace, for example
 `IkiWiki::RCS::svn`. 
 
 modules. These are in the `IkiWiki::RCS` namespace, for example
 `IkiWiki::RCS::svn`. 
 

-Each RCS plugin must support all the IkiWiki::rcs\_* functions.
+Each RCS plugin must support all the `IkiWiki::rcs_*` functions.

 See IkiWiki::RCS::Stub for the full list of functions. It's ok if
 See IkiWiki::RCS::Stub for the full list of functions. It's ok if

-rcs\_getctime does nothing except for throwing an error.
+`rcs_getctime` does nothing except for throwing an error.

 
 See [[about_RCS_backends]] for some more info.
 
 
 See [[about_RCS_backends]] for some more info.