]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/write.mdwn
po plugin: initial documentation, along with huge TODO list
[git.ikiwiki.info.git] / doc / plugins / write.mdwn
index 920fb8797cfa4a1d09e0947e261dc7455f1f89c7..6d2622272f01eaa5ed65d0fc496e886633fdf8c7 100644 (file)
@@ -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:
@@ -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($$)`
@@ -808,3 +856,32 @@ to a hash containing all the config items. They should also implement a
 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 `<script>` tags to be added to the pages that
+use your javascript. This can be done using a `format` hook.
+
+Ikiwiki provides some utility functions in `ikiwiki.js`, for use by other
+javascript code. These include:
+
+#### `getElementsByClass(cls, node, tag)` 
+
+Returns an array of elements with the given class. The node and tag are
+optional and define what document node and element names to search.
+
+#### `hook(name, call)`
+
+The function `call` will be run as part of the hook named `name`.
+
+Note that to hook into `window.onload`, you can use the `onload' hook.
+
+#### `run_hooks(name)`
+
+Runs the hooks with the specified name.