X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/4708aeceb3ec518a00069ad7a112ab0a5596275c..9ec9d6901d444af48555abf7b4c26d1965c46017:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index b31722dd7..0e4f2fd6f 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -123,7 +123,7 @@ 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); @@ -158,7 +158,7 @@ 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 @@ -188,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 @@ -356,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); @@ -379,22 +384,29 @@ 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", "pagespec", or "internal" (used for values that are not user-visible). The type is @@ -402,11 +414,19 @@ describing the option. For example: 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 +* `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. ## Plugin interface @@ -433,8 +453,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 @@ -484,7 +504,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 @@ -502,6 +522,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]]. @@ -604,6 +627,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 @@ -703,8 +743,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. @@ -712,9 +752,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($$)` @@ -789,6 +829,6 @@ 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)`