X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/4f06e7402ab09ebc1baa2ff0b3af50ccfc37a67e..32cc0b336ae830831787b2024b855ed7db0a1589:/doc/plugins/write.mdwn?ds=sidebyside diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 6d5056162..884c7eefb 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 @@ -180,10 +188,15 @@ languages to ikiwiki. The function is passed named parameters: "page" and "content" and should return the htmlized content. +If `hook` is passed an optional "keepextension" parameter, set to a true +value, then this extension will not be stripped from the source filename when +generating the page. + ### pagetemplate 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 +361,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); @@ -371,32 +384,79 @@ 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: +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", + description => "enable foo?", + advanced => 1, safe => 1, rebuild => 1, }, option_bar => { type => "string", example => "hello", - description => "what to say", + description => "option bar", safe => 1, rebuild => 0, }, + plugin => { + description => "description of this plugin", + safe => 1, + rebuild => 1, + }, -* `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. +* `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. -* `rebuild` should be true if changing the option will require a wiki rebuild. + 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. + +### targetpage + + hook(type => "targetpage", id => "foo", call => \&targetpage); + +This hook can be used to override the name of the file a page should +be compiled into. + +It should return the target filename. + +### tweakurlpath + + hook(type => "tweakurlpath", id => "foo", call => \&tweakurlpath); + +This hook can be used to modify the internal urls generated by +ikiwiki; it is run just after ikiwiki has removed the trailing +`index.html`, in case `usedirs` is enabled. + +It should return the modified url. + +### tweakbestlink + + hook(type => "tweakbestlink", id => "foo", call => \&tweakbestlink); + +This hook can be used to modify the page returned by `bestlink`. It is +passed named parameters `page` and `link`. These are, respectively, +the page where the link will appear and the link ikiwiki would choose +as the best one, if no `tweakbestlink` hook was in effect. + +It should return the modified link. ## Plugin interface @@ -423,8 +483,8 @@ your ikiwiki setup file, which sets the hash content to configure the wiki. The `%pagestate` hash can be used by plugins to save state that they will need next time ikiwiki is run. The hash holds per-page state, so to set a value, -use `%pagestate{$page}{$id}{$key}=$value`, and to retrieve the value, -use `%pagestate{$page}{$id}{$key}`. +use `$pagestate{$page}{$id}{$key}=$value`, and to retrieve the value, +use `$pagestate{$page}{$id}{$key}`. The `$value` can be anything that perl's Storable module is capable of serializing. `$key` can be any string you like, but `$id` must be the same @@ -437,6 +497,15 @@ When pages are deleted, ikiwiki automatically deletes their pagestate too. Note that page state does not persist across wiki rebuilds, only across wiki updates. +### %wikistate + +The `%wikistate` hash can be used by a plugin to store persistant state +that is not bound to any one page. To set a value, use +`$wikistate{$id}{$key}=$value, where `$value` is anything Storable can +serialize, `$key` is any string you like, and `$id` must be the same as the +"id" parameter passed to `hook()` when registering the plugin, so that the +state can be dropped if the plugin is no longer used. + ### Other variables If your plugin needs to access data about other pages in the wiki. It can @@ -474,7 +543,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 @@ -492,6 +561,9 @@ parameters are passed to `HTML::Template->new`. Passed a page name, returns the base name that will be used for a the html page created from it. (Ie, it appends ".html".) +Use this when constructing the filename of a html file. Use `urlto` when +generating a link to a page. + #### `add_depends($$)` Makes the specified page depend on the specified [[ikiwiki/PageSpec]]. @@ -594,6 +666,23 @@ a type that ikiwiki knowns how to htmlize. Otherwise, returns undef. Given the name of a source file, returns the name of the wiki page that corresponds to that file. +#### `pagetitle($)` + +Give the name of a wiki page, returns a version suitable to be displayed as +the page's title. This is accomplished by de-escaping escaped characters in +the page name. "_" is replaced with a space, and '__NN__' is replaced by +the UTF character with code NN. + +#### `titlepage($)` + +This performs the inverse of `pagetitle`, ie, it converts a page title into +a wiki page name. + +#### `linkpage($)` + +This converts text that could have been entered by the user as a +[[WikiLink]] into a wiki page name. + #### `srcfile($;$)` Given the name of a source file in the wiki, searches for the file in @@ -632,6 +721,12 @@ 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. +#### `newpagefile($$)` + +This can be called when creating a new page, to determine what filename +to save the page to. It's passed a page name, and its type, and returns +the name of the file to create, relative to the srcdir. + #### `targetpage($$)` Passed a page and an extension, returns the filename that page will be @@ -693,8 +788,8 @@ Changes can be staged by calls to `rcs_add, `rcs_remove`, and 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 +Note that this should not commit the new file, it should only +prepare for it to be committed 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. @@ -702,9 +797,9 @@ to version control; the subdir can be added if so. 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 +Note that this should not commit the removal, it should only prepare for it +to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. Note +that the new file may be in a new subdir that is not yet in version control; the subdir can be added if so. #### `rcs_rename($$)` @@ -779,6 +874,35 @@ when imported, populate `$IkiWiki::Setup::raw_setup` with a reference 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: -`use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)` +By the way, to parse a ikiwiki setup file and populate `%config`, a +program just needs to do something like: +`use IkiWiki::Setup; IkiWiki::Setup::load($filename)` + +### Javascript + +Some plugins use javascript to make ikiwiki look a bit more web-2.0-ish. + +All javascript code should be put in `.js` files in the `javascript` +underlay, and plugins using those files can enable use of the underlay by +calling `add_underlay("javascript");` in their `import` function. + +You'll have to arrange for `