From 9169c3247ffae04ae2fbc9ceda4176ffb5f263d3 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sat, 26 Jul 2008 13:07:48 -0400 Subject: [PATCH] standardising and documenting getsetup --- IkiWiki/Plugin/pinger.pm | 2 +- IkiWiki/Plugin/recentchanges.pm | 2 +- doc/plugins/write.mdwn | 43 +++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 2 deletions(-) diff --git a/IkiWiki/Plugin/pinger.pm b/IkiWiki/Plugin/pinger.pm index 89b4365ab..0aee17f8a 100644 --- a/IkiWiki/Plugin/pinger.pm +++ b/IkiWiki/Plugin/pinger.pm @@ -19,7 +19,7 @@ sub import { #{{{ sub getsetup () { #{{{ return pinger_timeout => { - type => "int", + type => "integer", default => 15, description => "how many seconds to try pinging before timing out", safe => 1, diff --git a/IkiWiki/Plugin/recentchanges.pm b/IkiWiki/Plugin/recentchanges.pm index 04a878b20..6ab4f9d03 100644 --- a/IkiWiki/Plugin/recentchanges.pm +++ b/IkiWiki/Plugin/recentchanges.pm @@ -24,7 +24,7 @@ sub getsetup () { #{{{ rebuild => 1, }, recentchangesnum => { - type => "int", + type => "integer", default => 100, description => "number of changes to track", safe => 1, diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 7c28088de..271d8d641 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -357,6 +357,49 @@ something. The hook is passed named parameters: `page`, `oldpage`, `newpage`, and `content`, and should try to modify the content to reflect the name change. For example, by converting links to point to the new page. +### getsetup + + hook(type => "getsetup", id => "foo", call => \&getsetup); + +This hooks is not called during normal operation, but only when setting up +the wiki, or generating a setup file. Plugins can use this hook to add +configuration options. + +The hook is passed no parameters. It returns data about the configuration +options added by the plugin. It can also check if the plugin is usable, and +die if the plugin is not available, which will cause the plugin to not be +offered in the configuration interface. + +The data returned is a list of `%config` options, followed by a hash +describing the option. For example: + + return + option_foo => { + type => "boolean", + default => 0, + description => "enable foo", + safe => 1, + rebuild => 1, + }, + option_bar => { + type => "string", + example => "hello", + description => "what to say", + safe => 1, + rebuild => 0, + }, + +* `type` can be "boolean", "string", "integer", or `undef` (use for complex + types). Note that the type is the type of the leaf values; the `%config` + option may be an array or hash of these. +* `default` should be set to the default value of the option, if any. +* `example` can be set to an example value, which will not be used by default. +* `description` is a short description of the option. +* `safe` should be false if the option should not be displayed in unsafe + configuration methods, such as the web interface. Anything that specifies + a command to run, a path on disk, or a regexp should be marked as unsafe. +* `rebuild` should be true if changing the option will require a wiki rebuild. + ## Plugin interface To import the ikiwiki plugin interface: -- 2.26.2