X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/4669eab596c8d90de0cf9f9d359ad8dd8f48edb5..f02672c113813c37a659991ae984a2368e15b8db:/doc/plugins/write.mdwn?ds=sidebyside

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 9f096e4f7..b60dc66f2 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -19,7 +19,7 @@ that can be fleshed out to make a useful plugin.
 `IkiWiki::Plugin::pagecount` is another simple example. All perl plugins
 should `use IkiWiki` to import the ikiwiki plugin interface. It's a good
 idea to include the version number of the plugin interface that your plugin
-expects: `use IkiWiki 2.00`.
+expects: `use IkiWiki 3.00`.
 
 An external plugin is an executable program. It can be written in any
 language. Its interface to ikiwiki is via XML RPC, which it reads from
@@ -55,8 +55,8 @@ plugin, and a "call" parameter, which tells what function to call for the
 hook.
 
 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.
+after all other hooks of its type, and an optional "first" parameter makes
+it run first. Useful if the hook depends on some other hook being run first.
 
 ## Types of hooks
 
@@ -303,7 +303,7 @@ can check if the session object has a "name" parameter set.
 
 ### canedit
 
-	hook(type => "canedit", id => "foo", call => \&pagelocked);
+	hook(type => "canedit", id => "foo", call => \&canedit);
 
 This hook can be used to implement arbitrary access methods to control when
 a page can be edited using the web interface (commits from revision control
@@ -321,6 +321,45 @@ This hook should avoid directly redirecting the user to a signin page,
 since it's sometimes used to test to see which pages in a set of pages a
 user can edit.
 
+### canremove
+
+	hook(type => "canremove", id => "foo", call => \&canremove);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be removed using the web interface (commits from revision control
+bypass it). It works exactly like the `canedit` hook.
+
+### canrename
+
+	hook(type => "canrename", id => "foo", call => \&canrename);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be renamed using the web interface (commits from revision control
+bypass it). It works exactly like the `canedit` and `canremove` hook,
+but is passed the named parameters `cgi` (a CGI object), `session` (a
+session object), `src`, `srcfile`, `dest` and `destfile`.
+
+### checkcontent
+	
+	hook(type => "checkcontent", id => "foo", call => \&checkcontent);
+
+This hook is called to check the content a user has entered on a page,
+before it is saved, and decide if it should be allowed.
+
+It is passed named parameters: `content`, `page`, `cgi`, and `session`. If
+the content the user has entered is a comment, it may also be passed some
+additional parameters: `author`, `url`, and `subject`. The `subject`
+parameter may also be filled with the user's comment about the change.
+
+Note: When the user edits an existing wiki page, this hook is also
+passed a `diff` named parameter, which will include only the lines
+that they added to the page, or modified.
+
+The hook should return `undef` on success. If the content is disallowed, it
+should return a message stating what the problem is, or a function
+that can be run to perform whatever action is necessary to allow the user
+to post the content.
+
 ### editcontent
 
 	hook(type => "editcontent", id => "foo", call => \&editcontent);
@@ -360,14 +399,29 @@ This hook is called whenever ikiwiki normally saves its state, just before
 the state is saved. The function can save other state, modify values before
 they're saved, etc.
 
-### renamepage
+### renamelink
 
-	hook(type => "renamepage", id => "foo", call => \&renamepage);
+	hook(type => "renamelink", id => "foo", call => \&renamelink);
 
 This hook is called by the [[plugins/rename]] plugin when it renames
-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.
+something, once per page linking to the renamed page's old location.
+The hook is passed named parameters: `page`, `oldpage`, `newpage`, and
+`content`, and should try to modify the content of `page` to reflect
+the name change. For example, by converting links to point to the
+new page.
+
+### rename
+
+	hook(type => "rename", id => "foo", call => \&renamepages);
+
+When a page or set of pages is renamed, the referenced function is
+called, and is passed:
+
+* a reference to an array of hashes with keys: `src`, `srcfile`,
+  `dest`, `destfile`, `required`. Such a hook function can modify
+  the array.
+* a CGI object
+* a session object
 
 ### getsetup
 
@@ -431,7 +485,7 @@ describes the plugin as a whole. For example:
 
 To import the ikiwiki plugin interface:
 
-	use IkiWiki '2.00';
+	use IkiWiki '3.00';
 
 This will import several variables and functions into your plugin's
 namespace. These variables and functions are the ones most plugins need,
@@ -486,7 +540,7 @@ use the following hashes, using a page name as the key:
   destination file.
 * `%pagesources` contains the name of the source file for each page.
 
-Also, the %IkiWiki::version variable contains the version number for the
+Also, the `%IkiWiki::version` variable contains the version number for the
 ikiwiki program.
 
 ### Library functions
@@ -696,11 +750,15 @@ This can be called when creating a new page, to determine what filename
 to save the page to. It's passed a page name, and its type, and returns
 the name of the file to create, relative to the srcdir.
 
-#### `targetpage($$)`
+#### `targetpage($$;$)`
 
 Passed a page and an extension, returns the filename that page will be
 rendered to.
 
+Optionally, a third parameter can be passed, to specify the preferred
+filename of the page. For example, `targetpage("foo", "rss", "feed")`
+will yield something like `foo/feed.rss`.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -823,19 +881,22 @@ It's ok if this is not implemented, and throws an error.
 #### `rcs_receive()`
 
 This is called when ikiwiki is running as a pre-receive hook (or
-equivilant), and is testing if changes pushed into the RCS from an
+equivalent), and is testing if changes pushed into the RCS from an
 untrusted user should be accepted. This is optional, and doesn't make
 sense to implement for all RCSs.
 
 It should examine the incoming changes, and do any sanity 
 checks that are appropriate for the RCS to limit changes to safe file adds,
-removes, and renames. If something bad is found, it should exit
+removes, and changes. If something bad is found, it should exit
 nonzero, to abort the push. Otherwise, it should return a list of
 files that were changed, in the form:
 
 	{
 		file => # name of file that was changed
 		action => # either "add", "change", or "remove"
+		path => # temp file containing the new file content, only
+			# needed for "add"/"change", and only if the file
+			# is an attachment, not a page
 	}
 
 The list will then be checked to make sure that each change is one that