From 824a1a1599035d45e5428e1203bb02373a8ac3b3 Mon Sep 17 00:00:00 2001 From: "http://kerravonsen.dreamwidth.org/" Date: Wed, 19 May 2010 11:22:13 +0000 Subject: put ftemplate directive info under directives; new version of ftemplate, with LOOPS! --- doc/ikiwiki/directive/ftemplate.mdwn | 106 +++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc/ikiwiki/directive/ftemplate.mdwn (limited to 'doc/ikiwiki/directive') diff --git a/doc/ikiwiki/directive/ftemplate.mdwn b/doc/ikiwiki/directive/ftemplate.mdwn new file mode 100644 index 000000000..3009fc830 --- /dev/null +++ b/doc/ikiwiki/directive/ftemplate.mdwn @@ -0,0 +1,106 @@ +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": + + # + by + + **Summary:** + +This will give: + +

I Am Page A

+

by Fred Nurk

+

Summary: 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: + +

Bananananananas

+

by Fred Nurk

+

Summary: 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": + + # + by + + ( + + , + + ) + +This will give: + +

Black Sheep

+

by Georgette Heyer

+ +

(Historical, Romance)

+ +

I like this book.

+ +### 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. -- cgit v1.2.3 From 136499da62f453f8eede16d564fae1e4788c63bf Mon Sep 17 00:00:00 2001 From: "http://kerravonsen.dreamwidth.org/" Date: Wed, 19 May 2010 11:27:19 +0000 Subject: new version; prev_, next_, here_only, and loops --- doc/ikiwiki/directive/report.mdwn | 148 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 doc/ikiwiki/directive/report.mdwn (limited to 'doc/ikiwiki/directive') diff --git a/doc/ikiwiki/directive/report.mdwn b/doc/ikiwiki/directive/report.mdwn new file mode 100644 index 000000000..c6e70e960 --- /dev/null +++ b/doc/ikiwiki/directive/report.mdwn @@ -0,0 +1,148 @@ +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: + + + ## + + ### + () \[[]] + + +### 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. -- cgit v1.2.3 From 3f5fce1091794521ea57f8ff7469441e4afb4a86 Mon Sep 17 00:00:00 2001 From: "http://kerravonsen.dreamwidth.org/" Date: Wed, 19 May 2010 11:28:10 +0000 Subject: added toc --- doc/ikiwiki/directive/report.mdwn | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/ikiwiki/directive') diff --git a/doc/ikiwiki/directive/report.mdwn b/doc/ikiwiki/directive/report.mdwn index c6e70e960..8f8e6b4e8 100644 --- a/doc/ikiwiki/directive/report.mdwn +++ b/doc/ikiwiki/directive/report.mdwn @@ -1,3 +1,4 @@ +[[!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 -- cgit v1.2.3