diff options
Diffstat (limited to 'doc/ikiwiki/directive')
| -rw-r--r-- | doc/ikiwiki/directive/ftemplate.mdwn | 106 | ||||
| -rw-r--r-- | doc/ikiwiki/directive/report.mdwn | 149 |
2 files changed, 0 insertions, 255 deletions
diff --git a/doc/ikiwiki/directive/ftemplate.mdwn b/doc/ikiwiki/directive/ftemplate.mdwn deleted file mode 100644 index 3009fc830..000000000 --- a/doc/ikiwiki/directive/ftemplate.mdwn +++ /dev/null @@ -1,106 +0,0 @@ -The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin. - -This is like the [[ikiwiki/directive/template]] directive, with the addition -that one does not have to provide all the values in the call to the template, -because ftemplate can query structured data ("fields") using the -[[plugins/contrib/field]] plugin. - -Templates are files that can be filled out and inserted into pages in -the wiki, by using the ftemplate directive. The directive has an id -parameter that identifies the template to use. - -Additional parameters can be used to fill out the template, in -addition to the "field" values. Passed-in values override the -"field" values. - -There are two places where template files can live. One is in the /templates -directory on the wiki. These templates are wiki pages, and can be edited from -the web like other wiki pages. - -The second place where template files can live is in the global -templates directory (the same place where the page.tmpl template lives). -This is a useful place to put template files if you want to prevent -them being edited from the web, and you don't want to have to make -them work as wiki pages. - -### EXAMPLES - -#### Example 1 - -PageA: - - \[[!meta title="I Am Page A"]] - \[[!meta description="A is for Apple."]] - \[[!meta author="Fred Nurk"]] - \[[!ftemplate id="mytemplate"]] - -Template "mytemplate": - - # <TMPL_VAR NAME="TITLE"> - by <TMPL_VAR NAME="AUTHOR"> - - **Summary:** <TMPL_VAR NAME="DESCRIPTION"> - -This will give: - - <h1>I Am Page A</h1> - <p>by Fred Nurk</p> - <p><strong>Summary:</strong> A is for Apple. - -#### Example 2: Overriding values - -PageB: - - \[[!meta title="I Am Page B"]] - \[[!meta description="B is for Banana."]] - \[[!meta author="Fred Nurk"]] - \[[!ftemplate id="mytemplate" title="Bananananananas"]] - -This will give: - - <h1>Bananananananas</h1> - <p>by Fred Nurk</p> - <p><strong>Summary:</strong> B is for Banana. - -#### Example 3: Loops - -(this example uses the [[plugins/contrib/ymlfront]] plugin) - -Page C: - - --- - BookAuthor: Georgette Heyer - BookTitle: Black Sheep - BookGenre: - - Historical - - Romance - --- - \[[ftemplate id="footemplate"]] - - I like this book. - -Template "footemplate": - - # <TMPL_VAR BOOKTITLE> - by <TMPL_VAR BOOKAUTHOR> - - <TMPL_IF BOOKGENRE>( - <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE> - <TMPL_UNLESS __last__>, </TMPL_UNLESS> - </TMPL_LOOP> - )</TMPL_IF> - -This will give: - - <h1>Black Sheep</h1> - <p>by Georgette Heyer</p> - - <p>(Historical, Romance)</p> - - <p>I like this book.</p> - -### LIMITATIONS - -One cannot query the values of fields on pages other than the current -page. If you want to do that, check out the [[plugins/contrib/report]] -plugin. diff --git a/doc/ikiwiki/directive/report.mdwn b/doc/ikiwiki/directive/report.mdwn deleted file mode 100644 index 8f8e6b4e8..000000000 --- a/doc/ikiwiki/directive/report.mdwn +++ /dev/null @@ -1,149 +0,0 @@ -[[!toc]] -The `report` directive is supplied by the [[!iki plugins/contrib/report desc=report]] plugin. - -This enables one to report on the structured data ("field" values) of -multiple pages; the output is formatted via a template. This depends -on the [[plugins/contrib/field]] plugin. - -The pages to report on are selected by a PageSpec given by the "pages" -parameter. The template is given by the "template" parameter. -The template expects the data from a single page; it is applied -to each matching page separately, one after the other. - -Additional parameters can be used to fill out the template, in -addition to the "field" values. Passed-in values override the -"field" values. - -There are two places where template files can live. One is in the -/templates directory on the wiki. These templates are wiki pages, and -can be edited from the web like other wiki pages. - -The second place where template files can live is in the global -templates directory (the same place where the page.tmpl template lives). -This is a useful place to put template files if you want to prevent -them being edited from the web, and you don't want to have to make -them work as wiki pages. - -## OPTIONS - -**template**: The template to use for the report. - -**pages**: A PageSpec to determine the pages to report on. - -**trail**: A page or pages to use as a "trail" page. - -When a trail page is used, the matching pages are limited to (a subset -of) the pages which that page links to; the "pages" pagespec in this -case, rather than selecting pages from the entire wiki, will select -pages from within the set of pages given by the trail page. - -Additional space-separated trail pages can be given in this option. -For example: - - trail="animals/cats animals/dogs" - -This will take the links from both the "animals/cats" page and the -"animals/dogs" page as the set of pages to apply the PageSpec to. - -**sort**: A SortSpec to determine how the matching pages should be sorted. - -**here_only**: Report on the current page only. - -This is useful in combination with "prev_" and "next_" variables to -make a navigation trail. -If the current page doesn't match the pagespec, then no pages will -be reported on. - -### Headers - -An additional option is the "headers" option. This is a space-separated -list of field names which are to be used as headers in the report. This -is a way of getting around one of the limitations of HTML::Template, that -is, not being able to do tests such as -"if this-header is not equal to previous-header". - -Instead, that logic is performed inside the plugin. The template is -given parameters "HEADER1", "HEADER2" and so on, for each header. -If the value of a header field is the same as the previous value, -then HEADER**N** is set to be empty, but if the value of the header -field is new, then HEADER**N** is given that value. - -#### Example - -Suppose you're writing a blog in which you record "moods", and you -want to display your blog posts by mood. - - \[[!report template="mood_summary" - pages="blog/*" - sort="Mood Date title" - headers="Mood"]] - -The "mood_summary" template might be like this: - - <TMPL_IF NAME="HEADER1"> - ## <TMPL_VAR NAME="HEADER1"> - </TMPL_IF> - ### <TMPL_VAR NAME="TITLE"> - (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]] - <TMPL_VAR NAME="DESCRIPTION"> - -### Advanced Options - -The following options are used to improve efficiency when dealing -with large numbers of pages; most people probably won't need them. - -**doscan**: - -Whether this report should be called in "scan" mode; if it is, then -the pages which match the pagespec are added to the list of links from -this page. This can be used by *another* report by setting this -page to be a "trail" page in *that* report. -It is not possible to use "trail" and "doscan" at the same time. -By default, "doscan" is false. - -## TEMPLATE PARAMETERS - -The templates are in HTML::Template format, just as [[plugins/template]] and -[[ftemplate]] are. The parameters passed in to the template are as follows: - -### Fields - -The structured data from the current matching page. This includes -"title" and "description" if they are defined. - -### Common values - -Values known for all pages: "page", "destpage". Also "basename" (the -base name of the page). - -### Passed-in values - -Any additional parameters to the report directive are passed to the -template; a parameter will override the matching "field" value. -For example, if you have a "Mood" field, and you pass Mood="bad" to -the report, then that will be the Mood which is given for the whole -report. - -Generally this is useful if one wishes to make a more generic -template and hide or show portions of it depending on what -values are passed in the report directive call. - -For example, one could have a "hide_mood" parameter which would hide -the "Mood" section of your template when it is true, which one could -use when the Mood is one of the headers. - -### Prev_ And Next_ Items - -Any of the above variables can be prefixed with "prev_" or "next_" -and that will give the previous or next value of that variable; that is, -the value from the previous or next page that this report is reporting on. -This is mainly useful for a "here_only" report. - -### Headers - -See the section on Headers. - -### First and Last - -If this is the first page-record in the report, then "first" is true. -If this is the last page-record in the report, then "last" is true. |