summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ikiwiki.setup2
-rw-r--r--doc/plugins.mdwn7
-rw-r--r--doc/plugins/passwordauth.mdwn9
-rw-r--r--doc/plugins/write.mdwn44
4 files changed, 49 insertions, 13 deletions
diff --git a/doc/ikiwiki.setup b/doc/ikiwiki.setup
index 7d0eb71fe..c6aa08ddd 100644
--- a/doc/ikiwiki.setup
+++ b/doc/ikiwiki.setup
@@ -97,7 +97,7 @@ use IkiWiki::Setup::Standard {
# wikitext camelcase pagestats htmltidy fortune
# sidebar map rst toc linkmap openid}],
# If you want to disable any of the default plugins, list them here.
- #disable_plugins => [qw{inline htmlscrubber}],
+ #disable_plugins => [qw{inline htmlscrubber passwordauth}],
# For use with the tag plugin, make all tags be located under a
# base page.
diff --git a/doc/plugins.mdwn b/doc/plugins.mdwn
index 6de17adc7..cd6037c2b 100644
--- a/doc/plugins.mdwn
+++ b/doc/plugins.mdwn
@@ -7,9 +7,10 @@ wiki, or just have [[type/fun]].
There's documentation if you want to [[write]] your own plugins, or you can
install and use plugins contributed by others.
-The [[mdwn]], [[inline]], and [[htmlscrubber]] plugins are enabled by default.
-To enable other plugins, use the `--plugin` switch described in [[usage]],
-or the equivalent `add_plugins` line in [[ikiwiki.setup]].
+The [[mdwn]], [[inline]], [[htmlscrubber]], and [[passwordauth]] plugins
+are enabled by default. To enable other plugins, use the `--plugin` switch
+described in [[usage]], or the equivalent `add_plugins` line in
+[[ikiwiki.setup]].
# Plugin directory
diff --git a/doc/plugins/passwordauth.mdwn b/doc/plugins/passwordauth.mdwn
new file mode 100644
index 000000000..aded8829f
--- /dev/null
+++ b/doc/plugins/passwordauth.mdwn
@@ -0,0 +1,9 @@
+[[template id=plugin name=passwordauth core=1 included=1 author="[[Joey]]"]]
+[[tag type/auth]]
+
+This plugin lets ikiwiki prompt for a user name and password when logging
+into the wiki. It also handles registering users, mailing passwords, and
+changing passwords in the prefs page.
+
+It is enabled by default, but can be turned off if you want to only use
+some other form of authentication, such as [[openid]].
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 651023701..f808d2e1e 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -36,6 +36,10 @@ before begining to render pages. This parameter should be set to true if
the hook modifies data in `%links`. Note that doing so will make the hook
be run twice per page build, so avoid doing it for expensive hooks.
+An optional "last" parameter, if set to a true value, makes the hook run
+after all other hooks of its type. Useful if the hook depends on some other
+hook being run first.
+
## Types of hooks
In roughly the order they are called.
@@ -119,13 +123,13 @@ return the htmlized content.
hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
-[[Templates]] 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 those templates. The function is passed named
+[[Templates]] 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 those templates. The function is passed named
parameters. The "page" and "destpage" parameters are the same as for a
-preprocess hook. The "template" parameter is a `HTML::Template` object that
-is the template that will be used to generate the page. The function can
-manipulate that template object.
+preprocess hook. The "template" parameter is a [[cpan HTML::Template]]
+object that is the template that will be used to generate the page. The
+function can manipulate that template object.
The most common thing to do is probably to call $template->param() to add
a new custom parameter to the template.
@@ -177,7 +181,7 @@ terminate the program.
### auth
- hook(type => "cgi", id => "foo", call => \&auth);
+ hook(type => "auth", id => "foo", call => \&auth);
This hook can be used to implement a different authentication method than
the standard web form. When a user needs to be authenticated, each registered
@@ -188,6 +192,28 @@ object's "name" parameter to the authenticated user's name. Note that
if the name is set to the name of a user who is not registered,
a basic registration of the user will be automatically performed.
+### formbuilder
+
+ hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
+ hook(type => "formbuilder", id => "foo", call => \&formbuilder);
+
+These hooks allow tapping into the parts of ikiwiki that use [[cpan
+CGI::FormBuilder]] to generate web forms. These hooks are passed named
+parameters: `cgi`, `session`, and `form`. These are, respectively, the
+`CGI` object, the user's `CGI::Session`, and a `CGI::FormBuilder`.
+
+Each time a form is set up, the formbuilder_setup hook is called.
+Typically the formbuilder_setup hook will check the form's title, and if
+it's a form that it needs to modify, will call various methods to
+add/remove/change fields, tweak the validation code for the fields, etc. It
+will not validate or display the form.
+
+Form validation and display can be overridden by the formbuilder hook.
+By default, ikiwiki will do a basic validation and display of the form,
+but if this hook is registered, it will stop that and let the hook take
+over. This hook is passed an additional named parameter: `buttons` is an
+array of the submit buttons for the form.
+
### savestate
hook(type => "savestate", id => "foo", call => \&savestate);
@@ -259,8 +285,8 @@ appear on the wiki page, rather than calling error().
#### `template($;@)`
-Creates and returns a HTML::Template object. The first parameter is the
-name of the file in the template directory. The optional remaining
+Creates and returns a [[cpan HTML::Template]] object. The first parameter
+is the name of the file in the template directory. The optional remaining
parameters are passed to HTML::Template->new.
#### `htmlpage($)`