X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/14b49376dc03672f896e5f1df3945a718a39d5a0..de4dc8befe7ede3cd34daf3f2bce5dd6305599f0:/doc/plugins/write.mdwn?ds=inline diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index ef14f18db..3976f9adf 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -98,7 +98,7 @@ function is passed no values. 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 pages that will be rebuilt, and can modify the array, either +array of files that will be rebuilt, and can modify the array, either adding or removing files from it. ### scan @@ -107,8 +107,8 @@ adding or removing files from it. This hook is called early in the process of building the wiki, and is used as a first pass scan of the page, to collect metadata about the page. It's -mostly used to scan the page for WikiLinks, and add them to `%links`. -Present in IkiWiki 2.40 and later. +mostly used to scan the page for [[WikiLinks|ikiwiki/WikiLink]], and add +them to `%links`. Present in IkiWiki 2.40 and later. The function is passed named parameters "page" and "content". Its return value is ignored. @@ -151,11 +151,11 @@ parameter is set to a true value if the page is being previewed. If `hook` is passed an optional "scan" parameter, set to a true value, this makes the hook be called during the preliminary scan that ikiwiki makes of updated pages, before begining to render pages. This should be done if the -hook modifies data in `%links`. Note that doing so will make the hook be -run twice per page build, so avoid doing it for expensive hooks. (As an -optimisation, if your preprocessor hook is called in a void context, you -can assume it's being run in scan mode, and avoid doing expensive things at -that point.) +hook modifies data in `%links` (typically by calling `add_link`). Note that +doing so will make the hook be run twice per page build, so avoid doing it +for expensive hooks. (As an optimisation, if your preprocessor hook is +called in a void context, you can assume it's being run in scan mode, and +avoid doing expensive things at that point.) Note that if the [[htmlscrubber]] is enabled, html in preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what @@ -168,13 +168,14 @@ htmlize the page) along with the rest of the page. hook(type => "linkify", id => "foo", call => \&linkify); -This hook is called to convert [[WikiLinks|WikiLink]] on the page into html +This hook is called to convert [[WikiLinks|ikiwiki/WikiLink]] on the page into html links. The function is passed named parameters "page", "destpage", and "content". It should return the linkified content. Present in IkiWiki 2.40 and later. Plugins that implement linkify must also implement a scan hook, that scans -for the links on the page and adds them to `%links`. +for the links on the page and adds them to `%links` (typically by calling +`add_link`). ### htmlize @@ -189,9 +190,17 @@ The function is passed named parameters: "page" and "content" and should return the htmlized content. If `hook` is passed an optional "keepextension" parameter, set to a true -value, then this extension will not be stripped from the source filename when +value, then the extension will not be stripped from the source filename when generating the page. +If `hook` is passed an optional "noextension" parameter, set to a true +value, then the id parameter specifies not a filename extension, but +a whole filename that can be htmlized. This is useful for files +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. + ### pagetemplate hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); @@ -321,28 +330,15 @@ 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. +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 @@ -350,11 +346,9 @@ bypass it). It works exactly like the `canedit` hook. 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`. +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 @@ -368,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 @@ -415,9 +410,9 @@ 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. -### renamelink +### renamepage - hook(type => "renamelink", id => "foo", call => \&renamelink); + hook(type => "renamepage", id => "foo", call => \&renamepage); This hook is called by the [[plugins/rename]] plugin when it renames something, once per page linking to the renamed page's old location. @@ -428,16 +423,20 @@ new page. ### rename - hook(type => "rename", id => "foo", call => \&renamepages); + hook(type => "rename", id => "foo", call => \&rename); When a page or set of pages is renamed, the referenced function is -called, and is passed: +called for every page, and is passed named parameters: -* 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 +* `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 @@ -484,7 +483,7 @@ describes the plugin as a whole. For example: * `example` can be set to an example value. * `description` is a short description of the option. * `link` is a link to further information about the option. This can either - be a wikilink, or an url. + be a [[ikiwiki/WikiLink]], or an url. * `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 @@ -575,10 +574,6 @@ 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 @@ -621,6 +616,19 @@ 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]]. + +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 @@ -633,7 +641,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) @@ -683,6 +691,16 @@ A failure to write the file will result in it dying with an error. If the destination directory doesn't exist, it will first be created. +The filename and directory are separate parameters because of +some security checks done to avoid symlink attacks. Before writing a file, +it checks to make sure there's not a symlink with its name, to avoid +following the symlink. If the filename parameter includes a subdirectory +to put the file in, it also checks if that subdirectory is a symlink, etc. +The directory parameter, however, is not checked for symlinks. So, +generally the directory parameter is a trusted toplevel directory like +the srcdir or destdir, and any subdirectories of this are included in the +filename parameter. + #### `will_render($$)` Given a page name and a destination file name (not including the base @@ -724,7 +742,7 @@ a wiki page name. #### `linkpage($)` This converts text that could have been entered by the user as a -[[WikiLink]] into a wiki page name. +[[ikiwiki/WikiLink]] into a wiki page name. #### `srcfile($;$)` @@ -779,6 +797,11 @@ 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($$)` + +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. + ## Miscellaneous ### Internal use pages @@ -789,7 +812,7 @@ are collected together to form the RecentChanges page, for example. To make an internal use page, register a filename extension that starts with "_". Internal use pages cannot be edited with the web interface, -generally shouldn't contain wikilinks or preprocessor directives (use +generally shouldn't contain [[WikiLinks|ikiwiki/WikiLink]] or preprocessor directives (use either on them with extreme caution), and are not matched by regular PageSpecs glob patterns, but instead only by a special `internal()` [[ikiwiki/PageSpec]]. @@ -827,7 +850,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($)` @@ -929,9 +952,12 @@ It's also possible to write plugins that add new functions to IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is how it will be accessed in a [[ikiwiki/PageSpec]]. The function will be passed two parameters: The name of the page being matched, and the thing to match -against. It may also be passed additional, named parameters. It should return -a IkiWiki::SuccessReason object if the match succeeds, or an -IkiWiki::FailReason object if the match fails. +against. It may also be passed additional, named parameters. + +It should return a IkiWiki::SuccessReason object if the match succeeds, or +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. ### Setup plugins @@ -958,7 +984,7 @@ or wrap one of the functions. For example, your plugin might want to override `displaytime`, to change the html markup used when displaying a date. Or it might want to override `IkiWiki::formattime`, to change how a date is formatted. Or perhaps you -want to override `bestlink` and change how ikiwiki deals with WikiLinks. +want to override `bestlink` and change how ikiwiki deals with [[WikiLinks|ikiwiki/WikiLink]]. By venturing into this territory, your plugin is becoming tightly tied to ikiwiki's internals. And it might break if those internals change. But