X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/3cb1c8fa3b1fac58f8a84deef9b72b334c17c97a..fae57e807a6367708b8137109d79d75c5b2c75e6:/doc/plugins/write.mdwn?ds=sidebyside diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index cde0b50fd..6d2622272 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -188,6 +188,10 @@ 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); @@ -424,6 +428,15 @@ describes the plugin as a whole. For example: 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. + ## Plugin interface To import the ikiwiki plugin interface: @@ -449,8 +462,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 @@ -463,6 +476,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 @@ -518,6 +540,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]]. @@ -620,6 +645,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 @@ -658,6 +700,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 @@ -719,8 +767,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. @@ -728,9 +776,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($$)` @@ -805,6 +853,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 `