X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/4691a2ad39cce273231fddd9a589b4f8fdc1b063..78e34fbdc255fd3f71f5b43ce1acd1fa0678e1ce:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 3dd8bdaa1..cde0b50fd 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -123,34 +123,42 @@ make arbitrary changes. The function is passed named parameters "page", ### preprocess -Adding a [[ikiwiki/PreProcessorDirective]] is probably the most common use +Adding a preprocessor [[ikiwiki/directive]] is probably the most common use 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 +preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what your plugin can do. Also, the rest of the page content is not in html format at preprocessor time. Text output by a preprocessor directive will be linkified and passed through markdown (or whatever engine is used to @@ -184,6 +192,7 @@ return the htmlized content. hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); + [[Templates|wikitemplates]] 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 @@ -348,7 +357,7 @@ This hook is called whenever ikiwiki normally saves its state, just before the state is saved. The function can save other state, modify values before they're saved, etc. -## renamepage +### renamepage hook(type => "renamepage", id => "foo", call => \&renamepage); @@ -357,6 +366,64 @@ something. The hook is passed named parameters: `page`, `oldpage`, `newpage`, and `content`, and should try to modify the content to reflect the name change. For example, by converting links to point to the new page. +### getsetup + + hook(type => "getsetup", id => "foo", call => \&getsetup); + +This hooks is not called during normal operation, but only when setting up +the wiki, or generating a setup file. Plugins can use this hook to add +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 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. There can also be an item named "plugin", which +describes the plugin as a whole. For example: + + return + option_foo => { + type => "boolean", + description => "enable foo?", + advanced => 1, + safe => 1, + rebuild => 1, + }, + option_bar => { + type => "string", + example => "hello", + description => "option bar", + safe => 1, + rebuild => 0, + }, + plugin => { + description => "description of this plugin", + safe => 1, + rebuild => 1, + }, + +* `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. +* `link` is a link to further information about the option. This can either + be a wikilink, or an url. +* `advanced` can be set to true if the option is more suitable for advanced + users. +* `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. + If a plugin is marked as unsafe, that prevents it from being + enabled/disabled. +* `rebuild` should be true if changing the option (or enabling/disabling + the plugin) will require a wiki rebuild, false if no rebuild is needed, + and undef if a rebuild could be needed in some circumstances, but is not + strictly required. + ## Plugin interface To import the ikiwiki plugin interface: @@ -376,7 +443,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 @@ -433,7 +500,7 @@ function that is called after the error message is printed, to do any final cleanup. If called inside a preprocess hook, error() does not abort the entire -wiki build, but instead replaces the [[ikiwiki/PreProcessorDirective]] with +wiki build, but instead replaces the preprocessor [[ikiwiki/directive]] with a version containing the error message. In other hooks, error() is a fatal error, so use with care. Try to avoid @@ -582,12 +649,15 @@ time. This is the standard gettext function, although slightly optimised. -#### `urlto($$)` +#### `urlto($$;$)` 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`. +If the third parameter is passed and is true, an absolute url will be +constructed instead of the default relative url. + #### `targetpage($$)` Passed a page and an extension, returns the filename that page will be @@ -610,15 +680,107 @@ PageSpecs glob patterns, but instead only by a special `internal()` ### RCS plugins -ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable -perl modules. These are in the `IkiWiki::RCS` namespace, for example -`IkiWiki::RCS::svn`. +ikiwiki's support for [[revision_control_systems|rcs]] is also done via +plugins. See [[RCS_details|rcs/details]] for some more info. + +RCS plugins must register a number of hooks. Each hook has type 'rcs', +and the 'id' field is set to the name of the hook. For example: + + hook(type => "rcs", id => "rcs_update", call => \&rcs_update); + hook(type => "rcs", id => "rcs_prepedit", call => \&rcs_prepedit); + +#### `rcs_update()` + +Updates the working directory with any remote changes. + +#### `rcs_prepedit($)` + +Is passed a file to prepare to edit. It can generate and return an arbitrary +token, that will be passed into `rcs_commit` when committing. For example, +it might return the current revision ID of the file, and use that +information later when merging changes. + +#### `rcs_commit($$$;$$)` + +Passed a file, message, token (from `rcs_prepedit`), user, and ip address. +Should try to commit the file. Returns `undef` on *success* and a version +of the page with the rcs's conflict markers on failure. + +#### `rcs_commit_staged($$$)` + +Passed a message, user, and ip address. Should commit all staged changes. +Returns undef on success, and an error message on failure. + +Changes can be staged by calls to `rcs_add, `rcs_remove`, and +`rcs_rename`. + +#### `rcs_add($)` + +Adds the passed file to the archive. The filename is relative to the root +of the srcdir. + +Note that this should not check the new file in, it should only +prepare for it to be checked in when rcs_commit (or `rcs_commit_staged`) is +called. Note that the file may be in a new subdir that is not yet in +to version control; the subdir can be added if so. + +#### `rcs_remove($)` + +Remove a file. The filename is relative to the root of the srcdir. + +Note that this should not check the removal in, it should only prepare for it +to be checked in when `rcs_commit` (or `rcs_commit_staged`) is called. Note +that the new file may be in a new subdir that is not yet inversion +control; the subdir can be added if so. + +#### `rcs_rename($$)` + +Rename a file. The filenames are relative to the root of the srcdir. + +Note that this should not commit the rename, it should only +prepare it for when `rcs_commit` (or `rcs_commit_staged`) is called. +The new filename may be in a new subdir, that is not yet added to +version control. If so, the subdir will exist already, and should +be added to revision control. + +#### `rcs_recentchanges($)` + +Examine the RCS history and generate a list of recent changes. +The parameter is how many changes to return. + +The data structure returned for each change is: + + { + rev => # the RCSs id for this commit + user => # name of user who made the change, + committype => # either "web" or the name of the rcs, + when => # time when the change was made, + message => [ + { line => "commit message line 1" }, + { line => "commit message line 2" }, + # etc, + ], + pages => [ + { + page => # name of page changed, + diffurl => # optional url to a diff of changes + }, + # repeat for each page changed in this commit, + ], + } + +#### `rcs_diff($)` + +The parameter is the rev from `rcs_recentchanges`. +Should return a list of lines of the diff (including \n) in list +context, and the whole diff in scalar context. + +#### `rcs_getctime($)` -Each RCS plugin must support all the `IkiWiki::rcs_*` functions. -See IkiWiki::RCS::Stub for the full list of functions. It's ok if -`rcs_getctime` does nothing except for throwing an error. +This is used to get the page creation time for a file from the RCS, by looking +it up in the history. -See [[RCS_details|rcs/details]] for some more info. +It's ok if this is not implemented, and throws an error. ### PageSpec plugins @@ -633,15 +795,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: