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);
 
 
        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
 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);
 
 
        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
 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.
 
 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);
 ### 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
 
 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
 
 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
 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
 
 
 ### 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
 * 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($;$)`
 
 
 #### `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.
 
 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
 #### `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
 #### `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.
 
 
 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.
 #### `gettext`
 
 This is the standard gettext function, although slightly optimised.


@@ -474,15 +501,15 @@ rendered to.
 
 ## RCS plugins
 
 
 ## 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.
 
 `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
 
 
 ## PageSpec plugins