X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/25447bccae0439ea56da7a788482a4807c7c459d..4f5fa747be9763b99cff93adb7939e4eac774695:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 335320394..4c66e51f8 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -177,10 +177,15 @@ function is passed no values. hook(type => "needsbuild", id => "foo", call => \&needsbuild); -This allows a plugin to manipulate the list of files that need to be -built when the wiki is refreshed. The function is passed a reference to an -array of files that will be rebuilt, and can modify the array, either -adding or removing files from it. +This allows a plugin to observe or even manipulate the list of files that +need to be built when the wiki is refreshed. + +As its first parameter, the function is passed a reference to an array of +files that will be built. It should return an array reference that is a +modified version of its input. It can add or remove files from it. + +The second parameter passed to the function is a reference to an array of +files that have been deleted. ### scan @@ -194,17 +199,6 @@ them to `%links`. Present in IkiWiki 2.40 and later. The function is passed named parameters "page" and "content". Its return value is ignored. -### rescan - - hook(type => "rescan", id => "foo", call => \&scan); - -This hook is called after the scan hook has been run, as well as the -preprocess hook in scan mode. It is used to collect additional -metadata that depends on a first scan to have been performed already. - -The function is passed named parameters "page" and "content". Its return -value is ignored. - ### filter hook(type => "filter", id => "foo", call => \&filter); @@ -362,21 +356,48 @@ when the page is being previewed.) The function is passed named parameters: "page" and "content", and should return the formatted content. +### build_affected + + hook(type => "build_affected", id => "foo", call => \&build_affected); + +This hook is called after the directly changed pages have been built, +and can cause extra pages to be built. If links and backlinks were provided +by a plugin, this would be where that plugin would rebuild pages whose +backlinks have changed, for instance. The [[trail]] plugin uses this hook +to rebuild pages whose next or previous page has changed. + +The function should currently ignore its parameters. It returns a list with +an even number of items (a hash in list context), where the first item of +each pair is a page name to be rebuilt (if it was not already rebuilt), and +the second is a log message resembling +`building plugins/write because the phase of the moon has changed`. + ### delete hook(type => "delete", id => "foo", call => \&delete); -Each time a page or pages is removed from the wiki, the referenced function +After a page or pages is removed from the wiki, the referenced function is called, and passed the names of the source files that were removed. -### change +### rendered - hook(type => "change", id => "foo", call => \&render); + hook(type => "rendered", id => "foo", call => \&rendered); -Each time ikiwiki renders a change or addition (but not deletion) to the +After ikiwiki renders a change or addition (but not deletion) to the wiki, the referenced function is called, and passed the names of the source files that were rendered. +(This hook used to be called "change", but that was not accurate. +For now, plugins using the old hook name will still work.) + +### changes + + hook(type => "changes", id => "foo", call => \&changes); + +After ikiwiki renders changes to the wiki, the referenced function is +called, and passed the names of the source files that were added, modified, +or deleted. + ### cgi hook(type => "cgi", id => "foo", call => \&cgi); @@ -586,6 +607,7 @@ describes the plugin as a whole. For example: * `description` is a short description of the option. * `link` is a link to further information about the option. This can either be a [[ikiwiki/WikiLink]], or an url. +* `htmldescription` is displayed instead of the description by websetup. * `advanced` can be set to true if the option is more suitable for advanced users. * `safe` should be false if the option should not be displayed in unsafe @@ -746,6 +768,8 @@ with no ".tmpl" extension. Template pages are normally looked for in the templates/ directory. If the page name starts with "/", a page elsewhere in the wiki can be used. +If the template is not found, or contains a syntax error, an error is thrown. + ### `template_depends($$;@)` Use this instead of `template()` if the content of a template is being @@ -986,14 +1010,22 @@ This is the standard gettext function, although slightly optimised. This is the standard ngettext function, although slightly optimised. -### `urlto($$;$)` +### `urlto($;$$)` Construct a relative url to the first parameter from the page named by the second. The first parameter can be either a page name, or some other destination file, as registered by `will_render`. -If the third parameter is passed and is true, an absolute url will be -constructed instead of the default relative url. +Provide a second parameter whenever possible, since this leads to better +behaviour for the [[plugins/po]] plugin and `file:///` URLs. + +If the second parameter is not specified (or `undef`), the URL will be +valid from any page on the wiki, or from the CGI; if possible it'll +be a path starting with `/`, but an absolute URL will be used if +the wiki and the CGI are on different domains. + +If the third parameter is passed and is true, the url will be a fully +absolute url. This is useful when generating an url to publish elsewhere. ### `newpagefile($$)` @@ -1105,9 +1137,7 @@ to version control; the subdir can be added if so. Remove a file. The filename is relative to the root of the srcdir. Note that this should not commit the removal, it should only prepare for it -to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. Note -that the new file may be in a new subdir that is not yet in version -control; the subdir can be added if so. +to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. #### `rcs_rename($$)` @@ -1147,19 +1177,19 @@ The data structure returned for each change is: ], } -#### `rcs_diff($)` +#### `rcs_diff($;$)` + +The first parameter is the rev from `rcs_recentchanges`. +The optional second parameter is how many lines to return (default: all). -The parameter is the rev from `rcs_recentchanges`. Should return a list of lines of the diff (including \n) in list -context, and the whole diff in scalar context. +context, and a string containing the whole diff in scalar context. #### `rcs_getctime($)` This is used to get the page creation time for a file from the RCS, by looking it up in the history. -It's ok if this is not implemented, and throws an error. - If the RCS cannot determine a ctime for the file, return 0. #### `rcs_getmtime($)` @@ -1180,9 +1210,9 @@ 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 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: +removes, and changes. If something bad is found, it should die, 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 @@ -1195,6 +1225,28 @@ files that were changed, in the form: The list will then be checked to make sure that each change is one that is allowed to be made via the web interface. +#### `rcs_preprevert($)` + +This is called by the revert web interface. It is passed a RCS-specific +change ID, and should determine what the effects would be of reverting +that change, and return the same data structure as `rcs_receive`. + +Like `rcs_receive`, it should do whatever sanity checks are appropriate +for the RCS to limit changes to safe changes, and die if a change would +be unsafe to revert. + +#### `rcs_revert($)` + +This is called by the revert web interface. It is passed a named +parameter rev that is the RCS-specific change ID to revert. + +It should try to revert the specified rev, and leave the reversion staged +so `rcs_commit_staged` will complete it. It should return undef on _success_ +and an error message on failure. + +This hook and `rcs_preprevert` are optional, if not implemented, no revert +web interface will be available. + ### PageSpec plugins It's also possible to write plugins that add new functions to