diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/plugins/contrib/po.mdwn | 5 | ||||
| -rw-r--r-- | doc/plugins/write.mdwn | 50 | ||||
| -rw-r--r-- | doc/plugins/write/external.mdwn | 7 |
3 files changed, 58 insertions, 4 deletions
diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index 30ede95a6..c4b7f9ee9 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -47,6 +47,11 @@ Any thoughts on this? >>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed >>> the other day that such wrappers around exported functions are only visible by >>> plugins loaded after the plugin that defines them. +>>> +>>> Update: Take a look at the new "Function overriding" section of +>>> [[plugins/write]]. I think you can just inject wrappers about a few ikiwiki +>>> functions, rather than adding hooks. The `inject` function is pretty +>>> insane^Wlow level, but seems to work great. --[[Joey]] >> >> The Discussion pages issue is something I am not sure about yet. But I will >> probably decide that "slave" pages, being only translations, don't deserve diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 856b34ba1..2e11e6234 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -854,6 +854,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. diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn index 272f74a7c..e30bf2ff3 100644 --- a/doc/plugins/write/external.mdwn +++ b/doc/plugins/write/external.mdwn @@ -96,14 +96,13 @@ the sentinal. ## Function injection -Some parts of ikiwiki are extensible by adding functions. For example, the -RCS interface relies on plugins providing several IkiWiki::rcs_* functions. +Some parts of ikiwiki are extensible by adding or overriding functions. It's actually possible to do this from an external plugin too. -To make your external plugin provide an `IkiWiki::rcs_update` function, for +To make your external plugin override the `IkiWiki::formattime` function, for example, make an RPC call to `inject`. Pass it named parameters "name" and "call", where "name" is the name of the function to inject into perl (here -"Ikiwiki::rcs_update" and "call" is the RPC call ikiwiki will make whenever +"Ikiwiki::formattime" and "call" is the RPC call ikiwiki will make whenever that function is run. If the RPC call is memoizable, you can also pass a "memoize" parameter, set |