X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/6154dd03cb9f46f58c04f91c12ac9e42c696dbbb..efcbb32f7c54ad8ffa2e56d52e651c18bd8be55a:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 896b98827..b31722dd7 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -128,26 +128,34 @@ of a plugin. hook(type => "preprocess", id => "foo", call => \&preprocess); -Replace "foo" with the command name that will be used inside brackets for -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 -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 +Replace "foo" with the command name that will be used for the preprocessor directive. -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. (As an -optimisation, if your preprocessor hook is called in a void contets, you -can assume it's being run in scan mode.) +Each time the directive is processed, the referenced function (`preprocess` +in the example above) is called. Whatever the function returns goes onto +the page in place of the directive. Or, if the function aborts using +`error()`, the directive will be replaced with the error message. + +The function is passed named parameters. First come the parameters set +in the preprocessor directive. These are passed in the same order as +they're in the directive, and if the preprocessor directive contains a bare +parameter (example: `\[[!foo param]]`), that parameter will be passed with +an empty value. + +After the parameters from the preprocessor directive some additional ones +are passed: 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), and a "preview" +parameter is set to a true value if the page is being previewed. + +If `hook` is passed an optional "scan" parameter, set to a true value, this +makes the hook be called during the preliminary scan that ikiwiki makes of +updated pages, before begining to render pages. This should be done 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. (As an +optimisation, if your preprocessor hook is called in a void context, you +can assume it's being run in scan mode, and avoid doing expensive things at +that point.) Note that if the [[htmlscrubber]] is enabled, html in [[ikiwiki/PreProcessorDirective]] output is sanitised, which may limit what @@ -367,8 +375,8 @@ configuration options. The hook is passed no parameters. It returns data about the configuration options added by the plugin. It can also check if the plugin is usable, and -die if the plugin is not available, which will cause the plugin to not be -offered in the configuration interface. +die if not, which will cause the plugin to not be offered in the configuration +interface. The data returned is a list of `%config` options, followed by a hash describing the option. For example: @@ -388,11 +396,13 @@ describing the option. For example: rebuild => 0, }, -* `type` can be "boolean", "string", "integer", "internal" (used for values - that are not user-visible). The type is the type of the leaf values; - the `%config` option may be an array or hash of these. +* `type` can be "boolean", "string", "integer", "pagespec", + or "internal" (used for values that are not user-visible). The type is + the type of the leaf values; the `%config` option may be an array or + hash of these. * `example` can be set to an example value. * `description` is a short description of the option. +* `description_html` is an optional short description, that can contain html * `safe` should be false if the option should not be displayed in unsafe configuration methods, such as the web interface. Anything that specifies a command to run, a path on disk, or a regexp should be marked as unsafe. @@ -417,7 +427,7 @@ it's not exported, the wise choice is to not use it. A plugin can access the wiki's configuration via the `%config` hash. The best way to understand the contents of the hash is to look at -[[ikiwiki.setup]], which sets the hash content to configure the wiki. +your ikiwiki setup file, which sets the hash content to configure the wiki. ### %pagestate @@ -769,15 +779,15 @@ IkiWiki::FailReason object if the match fails. ### Setup plugins -The ikiwiki setup file is loaded using a pluggable mechanism. If you -look at the top of [[ikiwiki.setup]], it starts with -'use IkiWiki::Setup::Standard', and the rest of the file is passed to -that module's import method. +The ikiwiki setup file is loaded using a pluggable mechanism. If you look +at the top of a setup file, it starts with 'use IkiWiki::Setup::Standard', +and the rest of the file is passed to that module's import method. It's possible to write other modules in the `IkiWiki::Setup::` namespace that can be used to configure ikiwiki in different ways. These modules should, when imported, populate `$IkiWiki::Setup::raw_setup` with a reference -to a hash containing all the config items. +to a hash containing all the config items. They should also implement a +`gendump` function. By the way, to parse a ikiwiki setup file, a program just needs to do something like: