X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/dddf5d55fd3496ba2ab28d34e6fe1e0610044299..7c173aca3e87d13fdd044cb79dac80ad83d64a38:/doc/plugins/write.mdwn
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1cdea6a77..e8ac9614b 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -196,7 +196,6 @@ generating the page.
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
@@ -428,6 +427,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:
@@ -467,6 +475,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
@@ -627,6 +644,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
@@ -665,6 +699,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
@@ -789,6 +829,30 @@ it up in the history.
It's ok if this is not implemented, and throws an error.
+#### `rcs_receive()`
+
+This is called when ikiwiki is running as a pre-receive hook (or
+equivalent), and is testing if changes pushed into the RCS from an
+untrusted user should be accepted. This is optional, and doesn't make
+sense to implement for all RCSs.
+
+It should examine the incoming changes, and do any sanity
+checks that are appropriate for the RCS to limit changes to safe file adds,
+removes, and changes. If something bad is found, it should exit
+nonzero, to abort the push. Otherwise, it should return a list of
+files that were changed, in the form:
+
+ {
+ file => # name of file that was changed
+ action => # either "add", "change", or "remove"
+ path => # temp file containing the new file content, only
+ # needed for "add"/"change", and only if the file
+ # is an attachment, not a page
+ }
+
+The list will then be checked to make sure that each change is one that
+is allowed to be made via the web interface.
+
### PageSpec plugins
It's also possible to write plugins that add new functions to
@@ -815,3 +879,82 @@ 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)`
+
+### Function overriding
+
+Sometimes using ikiwiki's pre-defined hooks is not enough. Your plugin
+may need to replace one of ikiwiki's own functions with a modified version,
+or wrap one of the functions.
+
+For example, your plugin might want to override `displaytime`, to change
+the html markup used when displaying a date. Or it might want to override
+`IkiWiki::formattime`, to change how a date is formatted. Or perhaps you
+want to override `bestlink` and change how ikiwiki deals with WikiLinks.
+
+By venturing into this territory, your plugin is becoming tightly tied to
+ikiwiki's internals. And it might break if those internals change. But
+don't let that stop you, if you're brave.
+
+Ikiwiki provides an `inject()` function, that is a powerful way to replace
+any function with one of your own. This even allows you to inject a
+replacement for an exported function, like `bestlink`. Everything that
+imports that function will get your version instead. Pass it the name of
+the function to replace, and a new function to call.
+
+For example, here's how to replace `displaytime` with a version using HTML 5
+markup:
+
+ inject(name => 'IkiWiki::displaytime', call => sub {
+ return "";
+ });
+
+Here's how to wrap `bestlink` with a version that tries to handle
+plural words:
+
+ my $origbestlink=\&bestlink;
+ inject(name => 'IkiWiki::bestlink', call => \&mybestlink);
+
+ sub deplural ($) {
+ my $word=shift;
+ $word =~ s/e?s$//; # just an example :-)
+ return $word;
+ }
+
+ sub mybestlink ($$) {
+ my $page=shift;
+ my $link=shift;
+ my $ret=$origbestlink->($page, $link);
+ if (! length $ret) {
+ $ret=$origbestlink->($page, deplural($link));
+ }
+ return $ret;
+ }
+
+### 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 `