X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/832d4d31d177d5d5f848250496048a00e9d70e2f..18695056917a2f34a36e5e89df7f01deff9ab640:/doc/plugins/write.mdwn diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index ef14f18db..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 @@ -368,8 +358,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 +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. @@ -428,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 @@ -484,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 @@ -575,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 @@ -683,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 @@ -724,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($;$)` @@ -789,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]]. @@ -958,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