X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/b86276ffed7ee001b35cd610e5d56e5afb4088cf..86484c109d30c0062c5a5056f4adf41c0581b5e9:/doc/plugins/write.mdwn?ds=inline diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index de2b47015..a9ea7db73 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -297,7 +297,7 @@ value is ignored. 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 +313,11 @@ 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"). ### sanitize @@ -633,6 +633,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 @@ -685,10 +701,29 @@ 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. + +### `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 @@ -718,7 +753,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. @@ -939,11 +977,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 @@ -1063,6 +1121,17 @@ 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($)` + +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 @@ -1114,24 +1183,19 @@ while "glob(*)" is not influenced by the contents of any page. 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::PageSpec package named `cmp_foo`, which will be used when sorting +the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting by `foo` or `foo(...)` is requested. -The function will be passed three or more parameters. The first two are -page names, and the third is `undef` if invoked as `foo`, or the parameter -`"bar"` if invoked as `foo(bar)`. It may also be passed additional, named -parameters. - -It should return the same thing as Perl's `cmp` and `<=>` operators: negative -if the first argument is less than the second, positive if the first argument -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. - -You can also define a function called `check_cmp_foo` in the same package. -If you do, it will be called while preparing to sort by `foo` or `foo(bar)`, -with argument `undef` or `"bar"` respectively; it may raise an error using -`error`, if sorting like that isn't going to work. +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