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.
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
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
+directive, while a "destpage" parameter gives 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.
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
+[[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 `HTML::Template` object that
-is the template that will be used to generate the page. The function can
-manipulate that template object.
+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.
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);
reference.
* `%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.
+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
#### `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($)`
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($$)`
Given a time, formats it for display.
+#### `gettext`
+
+This is the standard gettext function, although slightly optimised.
+
## RCS plugins
ikiwiki's support for revision control systems also uses pluggable perl