Merge branch 'master' of ssh://git.ikiwiki.info/srv/git/ikiwiki.info

2 files changed, 255 insertions, 0 deletions

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":
+
+    # <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
new file mode 100644
index 000000000..8f8e6b4e8
--- /dev/null
+++ b/doc/ikiwiki/directive/report.mdwn
@@ -0,0 +1,149 @@
+[[!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.