diff options
Diffstat (limited to 'doc/plugins/contrib/ikiwiki/directive')
9 files changed, 231 insertions, 0 deletions
diff --git a/doc/plugins/contrib/ikiwiki/directive/album.mdwn b/doc/plugins/contrib/ikiwiki/directive/album.mdwn new file mode 100644 index 000000000..433eec8bd --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/album.mdwn @@ -0,0 +1,56 @@ +The `album` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +Each page containing an `album` directive is treated as a photo album +or image gallery. Example usage is as simple as: + + \[[!album]] + +Every image attached to an album or its [[subpages|ikiwiki/subpage]] is +considered to be part of the album. A "viewer" page, with the wiki's default +page extension, will be generated in the +[[transient underlay|plugins/transient]] to display the +image, if there isn't already a page of the same name as the image: for +instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists, +then `debconf/tuesday/p100.mdwn` might be created. + +The album is treated as a [[!iki plugins/contrib/trail desc=trail]], which +gives each viewer page a link back to the album, and a link to the previous +and next viewer in the album. + +The `album` directive also produces an [[ikiwiki/directive/inline]] which +automatically includes all the viewers for this album, except those that +will appear in an [[albumsection]]. If every image in the album is in a +section, then the `album` directive is still required, but won't produce +any output in the page. + +The `inline` can include some extra information about the images, including +file size and a thumbnail made using [[ikiwiki/directive/img]]). The +default template is `albumitem.tmpl`, which takes advantage of these things. + +## Options + +The directive can have some options for the entire album. The defaults are: + + \[[!album + sort="-age" + size="full" + thumbnailsize="96x96" + viewertemplate="albumviewer" + prevtemplate="albumprev" + nexttemplate="albumnext" + +* `sort` - sets the order in which images appear, defaulting to earliest + creation date first +* `size` - if not `full`, the [[ikiwiki/directive/img]] in the viewer page + will be resized to be no larger than this +* `thumbnailsize` - the [[ikiwiki/directive/img]] in the album page, + which can also be used in the previous/next links, will be no larger than + this +* `viewertemplate` - the template used for the [[albumimage]] in each + viewer page +* `prevtemplate` - the template used to replace `<TMPL_VAR PREV>` if used in + the viewer page +* `nexttemplate` - the template used to replace `<TMPL_VAR NEXT>` if used in + the viewer page + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn new file mode 100644 index 000000000..2385bb535 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn @@ -0,0 +1,26 @@ +The `albumimage` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +Each viewer page produced by the [[album]] directive +contains an `albumimage` directive, which is replaced by an +[[ikiwiki/directive/img]], wrapped in some formatting using a +template (by default it's `albumviewer.tmpl`). That template can also include +links to the next and previous photos, in addition to those provided by the +[[!iki plugins/contrib/trail desc=trail]] plugin. + +The next/previous links are themselves implemented by evaluating a template, +either `albumnext.tmpl` or `albumprev.tmpl` by default. + +The directive can also have parameters: + +* `title`, `date`, `updated`, `author`, `authorurl`, `copyright`, `license` + and `description` are short-cuts for the corresponding + [[ikiwiki/directive/meta]] directives + +* `caption` sets a caption which is displayed near this image in the album + and viewer pages + +The viewer page can also contain any text and markup before or after the +`albumimage` directive, which will appear before or after the image in the +viewer page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn new file mode 100644 index 000000000..7e5749e05 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn @@ -0,0 +1,29 @@ +The `albumsection` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +The `albumsection` directive is used to split an album into sections. It can +only appear on a page that also has the [[album]] directive. + +The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages +are matched. The `albumsection` directive displays all the images that match +the filter, and the `album` directive displays any leftover images, like +this: + + # Holiday photos + + \[[!album]] + <!-- replaced with a list of any uncategorized photos; it will be + empty if they're all tagged as 'people' and/or 'landscapes' --> + + ## People + + \[[!albumsection filter="tagged(people)"]] + <!-- replaced with a list of photos tagged 'people', including + any that are also tagged 'landscapes' --> + + ## Landscapes + + \[[!albumsection filter="tagged(landscapes)"]] + <!-- replaced with a list of photos tagged 'landscapes', including + any that are also tagged 'people' --> + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn b/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn new file mode 100644 index 000000000..5d338901d --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn @@ -0,0 +1,42 @@ +The `jssearchfield` directive is supplied by the [[!iki plugins/contrib/jssearchfield desc=jssearchfield]] plugin. + +This enables one to search the structured data ("field" values) of +multiple pages. A search form is constructed, and the searching is +done with Javascript, which means that the entire thing is self-contained. +This depends on the [[!iki plugins/contrib/field]] plugin. + +The pages to search are selected by a PageSpec given by the "pages" +parameter. +The fields to search are given by the "fields" parameter. By default, +the field name is given, and the user can type the search parameter for +that field into a text input field. + +## OPTIONS + +**pages**: A PageSpec to determine the pages to search through. + +**fields**: The fields to put into the search form, and to display +in the results. + +**tagfields**: Display the given fields as a list of tags that can +be selected from, rather than having a text input field. Every distinct +value of that field will be listed, so it is best used for things with +short values, like "Author" rather than long ones like "Description". +Note that "tagfields" must be a subset of "fields". + +**sort**: A SortSpec to determine how the matching pages should be sorted; this is the "default" sort order that the results will be displayed in. +The search form also gives the option of "random" sort, which will +display the search results in random order. + +## SEARCHING + +The search form that is created by this directive contains the following: + +* for each search field, a label, plus either a text input field, or a list of checkboxes with values next to them if the field is also a tagfield. Note that the lists of checkboxes are initially hidden; one must click on the triangle next to the label to display them. +* a "sort" toggle. One can select either "default" or "random". +* A "Search!" button, to trigger the search if needed (see below) +* A "Reset" button, which will clear all the values. + +The searching is dynamic. As soon as a value is changed, either by tabbing out of the text field, or by selecting or de-selecting a checkbox, the search +results are updated. Furthermore, for tagfields, the tagfield lists +themselves are updated to reflect the current search results. diff --git a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn new file mode 100644 index 000000000..91d8a4edf --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn @@ -0,0 +1,11 @@ +The `trailinline` directive is provided by the +[[!iki plugins/contrib/trail desc=trail]] +plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and +[[ikiwiki/directive/inline]] directives with the same options. + +A typical use is to navigate through all posts in a blog: + + \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes + feedshow=10 quick=yes]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn new file mode 100644 index 000000000..73b1985a5 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn @@ -0,0 +1,9 @@ +The `trailitem` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It is used like this: + + \[[!trailitem some_other_page]] + +to add `some_other_page` to the trail represented by this page, without +generating a visible hyperlink. + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn new file mode 100644 index 000000000..4106ed33b --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn @@ -0,0 +1,24 @@ +The `trailitems` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It adds pages +to the trail represented by the current page, without producing any output +on that page. + + \[[!trailitems pages="posts/*" sort="age"]] + + \[[!trailitems pagenames="a b c"]] + +Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]: + +* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail + (cannot be used with `pagenames`) + +* `pagenames`: adds a space-separated list of pages to the trail, + with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]] + (cannot be used with `pages`) + +* `sort`: add the pages matched by `pages` to the trail in this + [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`) + +* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`) + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn new file mode 100644 index 000000000..0e40e2411 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn @@ -0,0 +1,16 @@ +The `traillink` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] +plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the +linked page to the trail represented by the page containing the directive. + +In its simplest form, the first parameter is like the content of a WikiLink: + + \[[!traillink some_other_page]] + +The displayed text can also be overridden, either with a `|` symbol or with +a `text` parameter: + + \[[!traillink Click_here_to_start_the_trail|some_other_page]] + \[[!traillink some_other_page text="Click here to start the trail"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn new file mode 100644 index 000000000..e1603f11b --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn @@ -0,0 +1,18 @@ +The `trailoptions` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the +trail represented by this page. + + \[[!trailoptions sort="meta(title)" circular="no"]] + +Options available: + +* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail, + overriding the order in which they were added + +* `reverse`: reverses the order of the trail + +* `circular`: if set to `yes` or `1`, the trail is made into a loop by + making the last page's "next" link point to the first page, and the first + page's "previous" link point to the last page + +[[!meta robots="noindex, follow"]] |