`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
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
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`.
+
### editcontent
hook(type => "editcontent", id => "foo", call => \&editcontent);
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
and undef if a rebuild could be needed in some circumstances, but is not
strictly required.
-### targetpage
-
- hook(type => "targetpage", id => "foo", call => \&targetpage);
-
-This hook can be used to override the name of the file a page should
-be compiled into.
-
-It should return the target filename.
-
-### tweakurlpath
-
- hook(type => "tweakurlpath", id => "foo", call => \&tweakurlpath);
-
-This hook can be used to modify the internal urls generated by
-ikiwiki; it is run just after ikiwiki has removed the trailing
-`index.html`, in case `usedirs` is enabled.
-
-It should return the modified url.
-
-### tweakbestlink
-
- hook(type => "tweakbestlink", id => "foo", call => \&tweakbestlink);
-
-This hook can be used to modify the page returned by `bestlink`. It is
-passed named parameters `page` and `link`. These are, respectively,
-the page where the link will appear and the link ikiwiki would choose
-as the best one, if no `tweakbestlink` hook was in effect.
-
-It should return the modified link.
-
## Plugin interface
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,
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
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