X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/60edd2dc3157f756f4f7a213ee15836fe7bbb769..5faf0c08ff583e2b3cea7e296ff38dde47632230:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1010e76e4..adc20af72 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,4 +1,4 @@
-Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be
+lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be
 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].
@@ -39,7 +39,7 @@ built.
 Now that it knows what pages it needs to build, ikiwiki runs two
 compile passes. First, it runs `scan` hooks, which collect metadata about
 the pages. Then it runs a page rendering pipeline, by calling in turn these
-hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `postscan`,
+hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,
 `pagetemplate`, `sanitize`, `format`.
 
 After all necessary pages are built, it calls the `change` hook. Finally,
@@ -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
 
@@ -198,8 +203,8 @@ value is ignored.
 
 	hook(type => "filter", id => "foo", call => \&filter);
 
-Runs on the raw source of a page, before anything else touches it, and can
-make arbitrary changes. The function is passed named parameters "page",
+Runs on the full raw source of a page, before anything else touches it, and
+can make arbitrary changes. The function is passed named parameters "page",
 "destpage", and "content". It should return the filtered content.
 
 ### preprocess
@@ -282,22 +287,22 @@ 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
+### indexhtml
 
-	hook(type => "postscan", id => "foo", call => \&postscan);
+	hook(type => "indexhtml", id => "foo", call => \&indexhtml);
 
 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.
+The function is passed named parameters "page", "destpage", and "content".
+Its return value is ignored.
 
 ### pagetemplate
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] are filled out for many different things in
 ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
 a cgi. This hook allows modifying the variables available on those
 templates. The function is passed named parameters. The "page" and
@@ -313,11 +318,20 @@ a new custom parameter to the template.
 
 	hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] that is
 used for a page in the wiki. The hook is passed a "page" parameter, and
-should return the name of the template file to use, or undef if it doesn't
-want to change the default ("page.tmpl"). Template files are looked for in
-/usr/share/ikiwiki/templates by default.
+should return the name of the template file to use (relative to the
+template directory), or undef if it doesn't want to change the default
+("page.tmpl").
+
+### pageactions
+
+	hook(type => "pageactions", id => "foo", call => \&pageactions);
+
+This hook allows plugins to add arbitrary actions to the action bar on a
+page (next to Edit, RecentChanges, etc). The hook is passed a "page"
+parameter, and can return a list of html fragments to add to the action
+bar.
 
 ### sanitize
 
@@ -586,37 +600,17 @@ describes the plugin as a whole. For example:
 	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.
-
-### sort
-
-	hook(type => "sort", id => "foo", call => \&sort_by_foo);
+function of the ikiwiki wrapper when it is being generated. 
 
-This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides
-an existing one.
+The code runs before anything else -- in particular it runs before
+the suid wrapper has sanitized its environment.
 
-The callback is given two page names followed by the parameter as arguments, and
-returns negative, zero or positive if the first page should come before,
-close to (i.e. undefined order), or after the second page.
+### disable
 
-For instance, the built-in `title` sort order could be reimplemented as
+	hook(type => "disable", id => "foo", call => \&disable);
 
-	sub sort_by_title {
-		pagetitle(basename($_[0])) cmp pagetitle(basename($_[1]));
-	}
-
-and to sort by an arbitrary `meta` value, you could use:
-
-	# usage: sort="meta(description)"
-	sub sort_by_meta {
-		my $param = $_[2];
-		error "sort=meta requires a parameter" unless defined $param;
-		my $left = $pagestate{$_[0]}{meta}{$param};
-		$left = "" unless defined $left;
-		my $right = $pagestate{$_[1]}{meta}{$param};
-		$right = "" unless defined $right;
-		return $left cmp $right;
-	}
+This hook is only run when a previously enabled plugin gets disabled
+during ikiwiki setup. Plugins can use this to perform cleanups.
 
 ## Exported variables
 
@@ -663,6 +657,22 @@ reference. Do not modify this hash directly; call `add_link()`.
 
 	$links{"foo"} = ["bar", "baz"];
 
+### `%typedlinks`
+
+The `%typedlinks` hash records links of specific types. Do not modify this
+hash directly; call `add_link()`. The keys are page names, and the values
+are hash references. In each page's hash reference, the keys are link types
+defined by plugins, and the values are hash references with link targets
+as keys, and 1 as a dummy value, something like this:
+
+	$typedlinks{"foo"} = {
+		tag => { short_word => 1, metasyntactic_variable => 1 },
+		next_page => { bar => 1 },
+	};
+
+Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in
+`%typedlinks`.
+
 ### `%pagesources`
 
 The `%pagesources` has can be used to look up the source filename
@@ -715,10 +725,31 @@ the entire wiki build and make the wiki unusable.
 
 ### `template($;@)`
 
-Creates and returns a [[!cpan HTML::Template]] object. The first parameter
-is the name of the file in the template directory. The optional remaining
+Creates and returns a [[!cpan HTML::Template]] object. (In a list context,
+returns the parameters needed to construct the obhect.) 
+
+The first parameter is the name of the template file. The optional remaining
 parameters are passed to `HTML::Template->new`.
 
+Normally, the template file is first looked for in the templates/ subdirectory
+of the srcdir. Failing that, it is looked for in the templatedir.
+
+Wiki pages can be used as templates. This should be done only for templates
+which it is safe to let wiki users edit. Enable it by passing a filename
+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
+included into a page. This causes the page to depend on the template,
+so it will be updated if the template is modified.
+
+Like `template()`, except the second parameter is the page.
+
 ### `htmlpage($)`
 
 Passed a page name, returns the base name that will be used for a the html
@@ -748,7 +779,10 @@ Additional named parameters can be specified:
 * `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.
+  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+  if a sort method is specified that depends on the
+  page content (such as 'meta(foo)'), the deptype needs to be set to
+  a content dependency.
 * `reverse` if true, sorts in reverse.
 * `num` if nonzero, specifies the maximum number of matching pages that
   will be returned.
@@ -930,13 +964,16 @@ search for files.
 If the directory name is not absolute, ikiwiki will assume it is in
 the parent directory of the configured underlaydir.
 
-### `displaytime($;$)`
+### `displaytime($;$$)`
 
 Given a time, formats it for display.
 
 The optional second parameter is a strftime format to use to format the
 time.
 
+If the third parameter is true, this is the publication time of a page.
+(Ie, set the html5 pubdate attribute.)
+
 ### `gettext`
 
 This is the standard gettext function, although slightly optimised.
@@ -945,14 +982,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($$)`
 
@@ -969,11 +1014,31 @@ 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`.
 
-### `add_link($$)`
+### `add_link($$;$)`
 
 This adds a link to `%links`, ensuring that duplicate links are not
 added. Pass it the page that contains the link, and the link text.
 
+An optional third parameter sets the link type. If not specified,
+it is an ordinary [[ikiwiki/WikiLink]].
+
+### `add_autofile($$$)`
+
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that. 
+
+The three parameters are the filename to create (relative to the `srcdir`),
+the name of the plugin, and a callback function. The callback will be
+called if it is appropriate to automatically add the file, and should then
+take care of creating it, and doing anything else it needs to (such as
+checking it into revision control). Note that the callback may not always
+be called. For example, if an automatically added file is deleted by the
+user, ikiwiki will avoid re-adding it again.
+
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -1011,16 +1076,20 @@ token, that will be passed into `rcs_commit` when committing. For example,
 it might return the current revision ID of the file, and use that
 information later when merging changes.
 
-#### `rcs_commit($$$;$$)`
+#### `rcs_commit(@)`
+
+Passed named parameters: `file`, `message`, `token` (from `rcs_prepedit`),
+and `session` (optional).
 
-Passed a file, message, token (from `rcs_prepedit`), user, and ip address.
 Should try to commit the file. Returns `undef` on *success* and a version
 of the page with the rcs's conflict markers on failure.
 
-#### `rcs_commit_staged($$$)`
+#### `rcs_commit_staged(@)`
+
+Passed named parameters: `message`, and `session` (optional).
 
-Passed a message, user, and ip address. Should commit all staged changes.
-Returns undef on success, and an error message on failure.
+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
 `rcs_rename`.
@@ -1063,7 +1132,9 @@ The data structure returned for each change is:
 
 	{
 		rev => # the RCSs id for this commit
-		user => # name of user who made the change,
+		user => # user who made the change (may be an openid),
+		nickname => # short name for user (optional; not an openid),
+		
 		committype => # either "web" or the name of the rcs,
 		when => # time when the change was made,
 		message => [
@@ -1091,8 +1162,17 @@ context, and the whole diff in scalar context.
 This is used to get the page creation time for a file from the RCS, by looking
 it up in the history.
 
+If the RCS cannot determine a ctime for the file, return 0.
+
+#### `rcs_getmtime($)`
+
+This is used to get the page modification 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 mtime for the file, return 0.
+
 #### `rcs_receive()`
 
 This is called when ikiwiki is running as a pre-receive hook (or
@@ -1102,9 +1182,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
@@ -1117,6 +1197,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
@@ -1140,6 +1242,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo;
 they match; "created_before(foo)" is influenced by the metadata of foo;
 while "glob(*)" is not influenced by the contents of any page.
 
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` is greater, or zero if they are considered equal. It may
+also raise an error using `error`, for instance if it needs a parameter but
+one isn't provided.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look