X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/0a081d78c4b4f24592f19e896b4f7daea30e9ef1..832d4d31d177d5d5f848250496048a00e9d70e2f:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 5ee4acb53..ef14f18db 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,61 @@ 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. +### cansave + + hook(type => "cansave", id => "foo", call => \&cansave); + +This hook can be used to implement arbitrary access methods to control +when a page being edited can be saved using the web interface (commits +from revision control bypass it). + +When a page is about to be saved, each registered cansave hook is +called in turn, and passed the page name, the edited content, a CGI +object and a session object. + +The return value of a cansave hook is interpreted the same as for the +canedit hook. + +### 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: +* a CGI object +* a session object +* the named parameters `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, the passed `content` 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 +415,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 +501,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 +556,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 @@ -505,6 +575,10 @@ the id can be controled by the user. Logs a debugging message. These are supressed unless verbose mode is turned on. +#### `warning($)` + +Logs a warning message. + #### `error($;$)` Aborts with an error message. If the second parameter is passed, it is a @@ -696,11 +770,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 @@ -837,8 +915,8 @@ 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", and only if the file is an - # attachment, not a page + # 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