web commit by JoshTriplett: Fix incomplete sentence. Sign.

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index a78785e0286b900afbf97bc1a583d7789c1bc96a..71239ac82d3b1d41a2252179306e64e98102753e 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -30,6 +30,16 @@ hook, a "id" paramter, which should be a unique string for this plugin, and
 a "call" parameter, which is a reference to a function to call for the
 hook.
 
 a "call" parameter, which is a reference to a function to call for the
 hook.
 

+An optional "scan" parameter, if set to a true value, makes the hook be
+called during the preliminary scan that ikiwiki makes of updated pages,
+before begining to render pages. This parameter should be set to true if
+the hook modifies data in `%links`. Note that doing so will make the hook
+be run twice per page build, so avoid doing it for expensive hooks.
+
+An optional "last" parameter, if set to a true value, makes the hook run
+after all other hooks of its type. Useful if the hook depends on some other
+hook being run first.
+

 ## Types of hooks
 
 In roughly the order they are called.
 ## Types of hooks
 
 In roughly the order they are called.


@@ -64,6 +74,14 @@ 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` and
 `content` and should return the filtered content.
 

+### scan
+
+       hook(type => "scan", id => "foo", call => \&scan);
+
+This is identical to a preprocess hook (see below), except that it is
+called in the initial pass that scans pages for data that will be used in
+later passes. Scan hooks are the only hook that should modify 
+

 ### preprocess
 
 Adding a [[PreProcessorDirective]] is probably the most common use of a
 ### preprocess
 
 Adding a [[PreProcessorDirective]] is probably the most common use of a


@@ -77,10 +95,12 @@ the preprocessor directive.
 Each time the directive is processed, the referenced function (`preprocess`
 in the example above) is called, and is passed named parameters. A "page"
 parameter gives the name of the page that embedded the preprocessor
 Each time the directive is processed, the referenced function (`preprocess`
 in the example above) is called, and is passed named parameters. A "page"
 parameter gives the name of the page that embedded the preprocessor

-directive, while a "destpage" parameter gices the name of the page the
-content is going to (different for inlined pages). All parameters included
-in the directive are included as named parameters as well. Whatever the
-function returns goes onto the page in place of the directive.
+directive, while a "destpage" parameter gives the name of the page the
+content is going to (different for inlined pages), and a "preview"
+parameter is set to a true value if the page is being previewed. All
+parameters included in the directive are included as named parameters as
+well. Whatever the function returns goes onto the page in place of the
+directive.

 
 Note that if the [[htmlscrubber]] is enabled, html in
 [[PreProcessorDirective]] output is sanitised, which may limit what your
 
 Note that if the [[htmlscrubber]] is enabled, html in
 [[PreProcessorDirective]] output is sanitised, which may limit what your


@@ -105,13 +125,13 @@ return the htmlized content.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 

-Each time a page (or part of a blog page, or an rss feed) is rendered, a
-[[template|templates]] is filled out. This hook allows modifying that
-template. The function is passed named parameters. The "page" and
-"destpage" parameters are the same as for a preprocess hook. The "template"
-parameter is a `HTML::Template` object that is the template that will be
-used to generate the page. The function can manipulate that template
-object.
+[[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.

 
 The most common thing to do is probably to call $template->param() to add
 a new custom parameter to the template.
 
 The most common thing to do is probably to call $template->param() to add
 a new custom parameter to the template.


@@ -161,6 +181,55 @@ 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
 terminate the program.
 
 parameters, and if it will handle this CGI request, output a page and
 terminate the program.
 

+### auth
+
+       hook(type => "auth", id => "foo", call => \&auth);
+
+This hook can be used to implement a different authentication method than
+the standard web form. When a user needs to be authenticated, each registered
+auth hook is called in turn, and passed a CGI object and a session object. 
+
+If the hook is able to authenticate the user, it should set the session
+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.
+
+### canedit
+
+       hook(type => "canedit", id => "foo", call => \&pagelocked);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be edited using the web interface (commits from revision control
+bypass it). When a page is edited, each registered canedit hook is called
+in turn, and passed the page name, a CGI object, and a session object.
+
+If edit can proceed, the hook should return "". If the edit is not allowed
+by this hook, the hook should return an error message for the user to see.
+If the hook has no opinion about whether the edit can proceed, return
+`undef`, and the next plugin will be asked to decide.
+
+### formbuilder
+
+       hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
+       hook(type => "formbuilder", id => "foo", call => \&formbuilder);
+
+These hooks allow tapping into the parts of ikiwiki that use [[cpan
+CGI::FormBuilder]] to generate web forms. These hooks are passed named
+parameters: `cgi`, `session`, and `form`. These are, respectively, the
+`CGI` object, the user's `CGI::Session`, and a `CGI::FormBuilder`.
+
+Each time a form is set up, the formbuilder_setup hook is called.
+Typically the formbuilder_setup hook will check the form's title, and if
+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. This hook is passed an additional named parameter: `buttons` is an
+array of the submit buttons for the form.
+

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


@@ -197,23 +266,34 @@ use the following hashes, using a page name as the key:
 
 * `%links` lists the names of each page that a page links to, in an array
   reference.
 
 * `%links` lists the names of each page that a page links to, in an array
   reference.

-* `%renderedfiles` contains the name of the file rendered by a page.
+* `%renderedfiles` lists names of the files rendered by a page, in an array
+  reference.

 * `%pagesources` contains the name of the source file for a page.
 
 * `%pagesources` contains the name of the source file for a page.
 

+Also, the %IkiWiki::version variable contains the version number for the
+ikiwiki program.
+

 ### Library functions
 
 #### `hook(@)`
 
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
 ### Library functions
 
 #### `hook(@)`
 
 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
+will not override any existing hook with the same id. This is useful if
+the id can be controled by the user.
+

 #### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned
 on.
 
 #### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned
 on.
 

-#### `error($)`
+#### `error($;$)`

 
 

-Aborts with an error message.
+Aborts with an error message. If the second parameter is passed, it is a
+function that is called after the error message is printed, to do any final
+cleanup.

 
 Note that while any plugin can use this for a fatal error, plugins should
 try to avoid dying on bad input, as that will halt the entire wiki build
 
 Note that while any plugin can use this for a fatal error, plugins should
 try to avoid dying on bad input, as that will halt the entire wiki build


@@ -223,8 +303,8 @@ appear on the wiki page, rather than calling error().
 
 #### `template($;@)`
 
 
 #### `template($;@)`
 

-Creates and returns a 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.
 
 #### `htmlpage($)`
 parameters are passed to HTML::Template->new.
 
 #### `htmlpage($)`


@@ -236,10 +316,12 @@ page created from it. (Ie, it appends ".html".)
 
 Makes the specified page depend on the specified [[PageSpec]].
 
 
 Makes the specified page depend on the specified [[PageSpec]].
 

-#### `pagespec_match($$)`
+#### `pagespec_match($$;$)`

 
 

-Passed a page name, and a [[PageSpec]], returns true if the [[PageSpec]]
-matches the page.
+Passed a page name, a [[PageSpec]], and the location the [[PageSpec]] should
+be matched against, returns true if the [[PageSpec]] matches the page. (If
+the third parameter is not passed, relative PageSpecs will match relative to
+the top of the wiki.)

 
 #### `bestlink($$)`
 
 
 #### `bestlink($$)`
 


@@ -249,7 +331,7 @@ subdirectory with the same name as the source page, failing that
 goes down the directory tree to the base looking for matching
 pages, as described in [[SubPage/LinkingRules]].
 
 goes down the directory tree to the base looking for matching
 pages, as described in [[SubPage/LinkingRules]].
 

-#### `htmllink($$$;$$$)`
+#### `htmllink($$$;@)`

 
 Many plugins need to generate html links and add them to a page. This is
 done by using the `htmllink` function. The usual way to call
 
 Many plugins need to generate html links and add them to a page. This is
 done by using the `htmllink` function. The usual way to call


@@ -266,11 +348,13 @@ Here `$destpage` is the inlining page. A `destpage` parameter is passed to
 some of the hook functions above; the ones that are not passed it are not used
 during inlining and don't need to worry about this issue.
 
 some of the hook functions above; the ones that are not passed it are not used
 during inlining and don't need to worry about this issue.
 

-The remaining three optional parameters to `htmllink` are:
+After the three required parameters, named parameters can be used to
+control some options. These are:

 
 

-1. noimageinline - set to true to avoid turning links into inline html images
-1. forcesubpage  - set to force a link to a subpage
-1. linktext - set to force the link text to something
+* noimageinline - set to true to avoid turning links into inline html images
+* forcesubpage  - set to force a link to a subpage
+* linktext - set to force the link text to something
+* anchor - set to make the link include an anchor

 
 #### `readfile($;$)`
 
 
 #### `readfile($;$)`
 


@@ -281,18 +365,31 @@ in binary mode.
 
 A failure to read the file will result in it dying with an error.
 
 
 A failure to read the file will result in it dying with an error.
 

-#### `writefile($$$;$)`
+#### `writefile($$$;$$)`

 
 Given a filename, a directory to put it in, and the file's content,
 writes a file. 
 
 
 Given a filename, a directory to put it in, and the file's content,
 writes a file. 
 

-The optional second parameter, if set to a true value, makes the file be
+The optional fourth parameter, if set to a true value, makes the file be

 written in binary mode.
 
 written in binary mode.
 

+The optional fifth parameter can be used to pass a function reference that
+will be called to handle writing to the file. The function will be called
+and passed a file descriptor it should write to, and an error recovery
+function it should call if the writing fails. (You will not normally need to
+use this interface.)
+

 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.
 
 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.
 

+### `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
+being rendered. It's important to call this before writing to any file in
+the destination directory.
+

 #### `pagetype($)`
 
 Given the name of a source file, returns the type of page it is, if it's
 #### `pagetype($)`
 
 Given the name of a source file, returns the type of page it is, if it's


@@ -313,6 +410,19 @@ path to the first file found.
 
 Given a time, formats it for display.
 
 
 Given a time, formats it for display.
 

+#### `gettext`
+
+This is the standard gettext function, although slightly optimised.
+
+#### `urlto($$)`
+
+Construct a relative url to the first parameter from the second.
+
+#### `targetpage($$)`
+
+Passed a page and an extension, returns the filename that page will be
+rendered to.
+

 ## RCS plugins
 
 ikiwiki's support for revision control systems also uses pluggable perl
 ## RCS plugins
 
 ikiwiki's support for revision control systems also uses pluggable perl


@@ -324,3 +434,13 @@ See IkiWiki::RCS::Stub for the full list of functions. It's ok if
 rcs\_getctime does nothing except for throwing an error.
 
 See [[about_RCS_backends]] for some more info.
 rcs\_getctime does nothing except for throwing an error.
 
 See [[about_RCS_backends]] for some more info.

+
+## PageSpec plugins
+
+It's also possible to write plugins that add new functions to
+[[PageSpecs|PageSpec]]. Such a plugin should add a function to the
+IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
+how it will be accessed in a [[PageSpec]]. The function will be passed
+three parameters: The name of the page being matched, the thing to match
+against, and the page that the matching is occuring on. It should return
+true if the page matches.