X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/a3726968bc13f19f458c372cbd7cf92ae4c6fce5..18695056917a2f34a36e5e89df7f01deff9ab640:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 7ba01ae53..cccfb9bba 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -107,7 +107,7 @@ 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`. +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 @@ -168,7 +168,7 @@ 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. @@ -189,9 +189,14 @@ 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. + ### pagetemplate hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); @@ -321,28 +326,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 +342,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 @@ -416,9 +406,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. @@ -429,16 +419,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: + +* `torename`: a reference to a hash with keys: `src`, `srcfile`, + `dest`, `destfile`, `required`. +* `cgi`: a CGI object +* `session`: a session object. -* 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 +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 @@ -485,7 +479,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 @@ -576,10 +570,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 @@ -684,6 +674,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 @@ -725,7 +725,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($;$)` @@ -790,7 +790,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]]. @@ -959,7 +959,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