X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/251fe8dae6e0bdf5a3d3ad4fc413b2163fecbb75..66af1428f04d8b709be5854bb1fa74da7b25fb2d:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index d0f6a09e1..45f083b42 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -201,6 +201,17 @@ like `Makefile` that have no extension. If `hook` is passed an optional "longname" parameter, this value is used when prompting a user to choose a page type on the edit page form. +### postscan + + hook(type => "postscan", id => "foo", call => \&postscan); + +This hook is called once the page has been converted to html (but before +the generated html is put in a template). The most common use is to +update search indexes. Added in ikiwiki 2.54. + +The function is passed named parameters "page" and "content". Its return +value is ignored. + ### pagetemplate hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); @@ -237,17 +248,6 @@ modify the body of a page after it has been fully converted to html. The function is passed named parameters: "page", "destpage", and "content", and should return the sanitized content. -### postscan - - hook(type => "postscan", id => "foo", call => \&postscan); - -This hook is called once the full page body is available (but before the -format hook). The most common use is to update search indexes. Added in -ikiwiki 2.54. - -The function is passed named parameters "page" and "content". Its return -value is ignored. - ### format hook(type => "format", id => "foo", call => \&format); @@ -330,6 +330,26 @@ 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, +but is passed the named parameters `cgi` (a CGI object), `session` +(a session object) and `page` (the page subject to deletion). + +### 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` 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); @@ -342,8 +362,9 @@ 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. +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 @@ -394,9 +415,28 @@ they're saved, etc. hook(type => "renamepage", id => "foo", call => \&renamepage); 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 => \&rename); + +When a page or set of pages is renamed, the referenced function is +called for every page, and is passed named parameters: + +* `torename`: a reference to a hash with keys: `src`, `srcfile`, + `dest`, `destfile`, `required`. +* `cgi`: a CGI object +* `session`: a session object. + +Such a hook function returns any additional rename hashes it wants to +add. This hook is applied recursively to returned additional rename +hashes, so that it handles the case where two plugins use the hook: +plugin A would see when plugin B adds a new file to be renamed. ### getsetup @@ -456,6 +496,13 @@ describes the plugin as a whole. For example: and undef if a rebuild could be needed in some circumstances, but is not strictly required. +### genwrapper + + hook(type => "genwrapper", id => "foo", call => \&genwrapper); + +This hook is used to inject C code (which it returns) into the `main` +function of the ikiwiki wrapper when it is being generated. + ## Plugin interface To import the ikiwiki plugin interface: @@ -562,33 +609,75 @@ page created from it. (Ie, it appends ".html".) Use this when constructing the filename of a html file. Use `urlto` when generating a link to a page. -#### `add_depends($$)` +### `deptype(@)` + +Use this function to generate ikiwiki's internal representation of a +dependency type from one or more of these keywords: + +* `content` is the default. Any change to the content + of a page triggers the dependency. +* `presence` is only triggered by a change to the presence + of a page. +* `links` is only triggered by a change to the links of a page. + This includes when a link is added, removed, or changes what + it points to due to other changes. It does not include the + addition or removal of a duplicate link. + +If multiple types are specified, they are combined. + +#### `pagespec_match_list($$;@)` + +Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages +in the wiki that match the [[ikiwiki/PageSpec]]. + +The page will automatically be made to depend on the specified +[[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This +is often significantly more efficient than calling `add_depends` and +`pagespec_match` in a loop. You should use this anytime a plugin +needs to match a set of pages and do something based on that list. + +Unlike pagespec_match, this may throw an error if there is an error in +the pagespec. + +Additional named parameters can be specified: + +* `deptype` optionally specifies the type of dependency to add. Use the + `deptype` function to generate a dependency type. +* `filter` is a reference to a function, that is called and passed a page, + and returns true if the page should be filtered out of the list. +* `sort` specifies a sort order for the list. See + [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. +* `reverse` if true, sorts in reverse. +* `num` if nonzero, specifies the maximum number of matching pages that + will be returned. +* `list` makes it only match amoung the specified list of pages. + Default is to match amoung all pages in the wiki. + +Any other named parameters are passed on to `pagespec_match`, to further +limit the match. + +#### `add_depends($$;$)` Makes the specified page depend on the specified [[ikiwiki/PageSpec]]. +By default, dependencies are full content dependencies, meaning that the +page will be updated whenever anything matching the PageSpec is modified. +This can be overridden by passing a `deptype` value as the third parameter. + #### `pagespec_match($$;@)` -Passed a page name, and [[ikiwiki/PageSpec]], returns true if the +Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the [[ikiwiki/PageSpec]] matches the page. -Additional named parameters can be passed, to further limit the match. -The most often used is "location", which specifies the location the -PageSpec should match against. If not passed, relative PageSpecs will match -relative to the top of the wiki. - -#### `pagespec_match_list($$;@)` - -Passed a reference to a list of page names, and [[ikiwiki/PageSpec]], -returns the set of pages that match the [[ikiwiki/PageSpec]]. +Note that the return value is overloaded. If stringified, it will be a +message indicating why the PageSpec succeeded, or failed, to match the +page. Additional named parameters can be passed, to further limit the match. The most often used is "location", which specifies the location the PageSpec should match against. If not passed, relative PageSpecs will match relative to the top of the wiki. -Unlike pagespec_match, this may throw an error if there is an error in -the pagespec. - #### `bestlink($$)` Given a page and the text of a link on the page, determine which @@ -601,7 +690,7 @@ pages, as described in [[ikiwiki/SubPage/LinkingRules]]. Many plugins need to generate html links and add them to a page. This is done by using the `htmllink` function. The usual way to call -`htmlllink` is: +`htmllink` is: htmllink($page, $page, $link) @@ -623,6 +712,7 @@ control some options. These are: * anchor - set to make the link include an anchor * rel - set to add a rel attribute to the link * class - set to add a css class to the link +* title - set to add a title attribute to the link #### `readfile($;$)` @@ -810,7 +900,7 @@ of the page with the rcs's conflict markers on failure. Passed a message, user, and ip address. Should commit all staged changes. Returns undef on success, and an error message on failure. -Changes can be staged by calls to `rcs_add, `rcs_remove`, and +Changes can be staged by calls to `rcs_add`, `rcs_remove`, and `rcs_rename`. #### `rcs_add($)` @@ -919,6 +1009,15 @@ an IkiWiki::FailReason object if the match fails. If the match cannot be attempted at all, for any page, it can instead return an IkiWiki::ErrorReason object explaining why. +When constructing these objects, you should also include information about +of any pages whose contents or other metadata influenced the result of the +match. Do this by passing a list of pages, followed by `deptype` values. + +For example, "backlink(foo)" is influenced by the contents of page foo; +"link(foo)" and "title(bar)" are influenced by the contents of any page +they match; "created_before(foo)" is influenced by the metadata of foo; +while "glob(*)" is not influenced by the contents of any page. + ### Setup plugins The ikiwiki setup file is loaded using a pluggable mechanism. If you look