diff options
Diffstat (limited to 'doc/plugins/write.mdwn')
| -rw-r--r-- | doc/plugins/write.mdwn | 111 |
1 files changed, 74 insertions, 37 deletions
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 857d176d5..abcabbdc3 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -360,13 +360,6 @@ 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. -### displaytime - - hook(type => "displaytime", id => "foo", call => \&display); - -This hook can be registered to override the regular `displaytime` function. -Only the last displaytime hook will be used. - ### renamepage hook(type => "renamepage", id => "foo", call => \&renamepage); @@ -434,36 +427,6 @@ 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. - -### 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 To import the ikiwiki plugin interface: @@ -857,6 +820,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 @@ -884,6 +871,56 @@ 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 "<time>".formattime(@_)."</time>"; + }); + +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. |