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
+later passes. Scan hooks are the only hook that should modify `%links`.
### 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 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.
+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
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
+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.
If your plugin needs to access data about other pages in the wiki. It can
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
+* `links` lists the names of each page that a page links to, in an array
reference.
-* `%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.
+* `%destsources` contains the name of the source file used to create each
+ destination file.
+* `%pagesources` contains the name of the source file for each page.
Also, the %IkiWiki::version variable contains the version number for the
ikiwiki program.
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
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($;$)`
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
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 two
-parameters: The name of the page being matched, and the thing to match
-against. It should return true if the page matches.
+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.