web commit by martin

[git.ikiwiki.info.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 3030d65585d2cf4daea20dc74ee7d7d8348bb430..beaa251253ba3f6f5c860c203d4c160f46fb5ebc 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -148,7 +148,7 @@ return the htmlized content.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates|wikitemplate]] are filled out for many different things in
+[[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
 templates. The function is passed named parameters. The "page" and
@@ -164,7 +164,7 @@ a new custom parameter to the template.
 
        hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-This hook allows plugins to change the [[template|wikitemplate]] that is
+This hook allows plugins to change the [[template|wikitemplates]] that is
 used for a page in the wiki. The hook is passed a "page" parameter, and
 should return the name of the template file to use, or undef if it doesn't
 want to change the default ("page.tmpl"). Template files are looked for in
@@ -251,6 +251,17 @@ by this hook, the hook should return an error message for the user to see.
 If the hook has no opinion about whether the edit can proceed, return
 `undef`, and the next plugin will be asked to decide.
 
+### editcontent
+
+       hook(type => "editcontent", id => "foo", call => \&editcontent);
+
+This hook is called when a page is saved (or previewed) using the web
+interface. It is passed named parameters: `content`, `page`, `cgi`, and
+`session`. These are, respectively, the new page content as entered by the
+user, the page name, a `CGI` object, and the user's `CGI::Session`. 
+
+It can modify the content as desired, and should return the content.
+
 ### formbuilder
 
        hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
@@ -258,8 +269,9 @@ If the hook has no opinion about whether the edit can proceed, return
 
 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`.
+parameters: `cgi`, `session`, `form`, and `buttons`. These are, respectively,
+the `CGI` object, the user's `CGI::Session`, a `CGI::FormBuilder`, and a
+reference to an array of names of buttons to go on the form.
 
 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
@@ -270,8 +282,7 @@ 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.
+over.
 
 ### savestate
 
@@ -401,7 +412,8 @@ control some options. These are:
 * forcesubpage  - set to force a link to a subpage
 * linktext - set to force the link text to something
 * anchor - set to make the link include an anchor
-* rel - set to add a rel attribute to the link.
+* rel - set to add a rel attribute to the link
+* class - set to add a css class to the link
 
 #### `readfile($;$)`
 
@@ -437,6 +449,10 @@ destination directory), register that the page will result in that file
 being rendered. It's important to call this before writing to any file in
 the destination directory.
 
+Ikiwiki uses this information to automatically clean up rendered files when
+the page that rendered them goes away or is changes to no longer render
+them. will_render also does a few important security checks.
+
 #### `pagetype($)`
 
 Given the name of a source file, returns the type of page it is, if it's
@@ -450,13 +466,24 @@ that corresponds to that file.
 #### `srcfile($)`
 
 Given the name of a source file in the wiki, searches for the file in
-the source directory and the underlay directory, and returns the full
-path to the first file found.
+the source directory and the underlay directories (most recently added
+underlays first), and returns the full path to the first file found.
 
-#### `displaytime($)`
+#### `add_underlay($)`
+
+Adds a directory to the set of underlay directories that ikiwiki will
+search for files.
+
+If the directory name is not absolute, ikiwiki will assume it is in
+the parent directory of the configured underlaydir.
+
+#### `displaytime($;$)`
 
 Given a time, formats it for display.
 
+The optional second parameter is a strftime format to use to format the
+time.
+
 #### `gettext`
 
 This is the standard gettext function, although slightly optimised.
@@ -474,15 +501,15 @@ rendered to.
 
 ## RCS plugins
 
-ikiwiki's support for revision control systems also uses pluggable perl
-modules. These are in the `IkiWiki::RCS` namespace, for example
+ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable
+perl modules. These are in the `IkiWiki::RCS` namespace, for example
 `IkiWiki::RCS::svn`. 
 
 Each RCS plugin must support all the `IkiWiki::rcs_*` functions.
 See IkiWiki::RCS::Stub for the full list of functions. It's ok if
 `rcs_getctime` does nothing except for throwing an error.
 
-See [[about_RCS_backends]] for some more info.
+See [[RCS_details|rcs/details]] for some more info.
 
 ## PageSpec plugins