doc/plugins/contrib/report.mdwn

   1 [[!template id=plugin name=report author="[[rubykat]]"]]
   2 [[!tag type/meta type/format]]
   3 [[!toc]]
   4 ## NAME
   5
   6 IkiWiki::Plugin::report - Produce templated reports from page field data.
   7
   8 ## SYNOPSIS
   9
  10     # activate the plugin
  11     add_plugins => [qw{goodstuff report ....}],
  12
  13     \[[!report template="blog_summary"
  14     pages="blog/*"
  15     sort="mtime"]]
  16
  17 ## DESCRIPTION
  18
  19 This plugin provides the **report** directive.  This enables one to report on
  20 the structured data ("field" values) of multiple pages; the output is formatted
  21 via a template.  This depends on the [[plugins/contrib/field]] plugin.
  22
  23 The pages to report on are selected by a PageSpec given by the "pages"
  24 parameter.  The template is given by the "template" parameter.
  25 The template expects the data from a single page; it is applied
  26 to each matching page separately, one after the other.
  27
  28 Additional parameters can be used to fill out the template, in
  29 addition to the "field" values.  Passed-in values override the
  30 "field" values.
  31
  32 There are two places where template files can live.  One, as with the
  33 [[plugins/template]] plugin, is in the /templates directory on the wiki.  These
  34 templates are wiki pages, and can be edited from the web like other wiki
  35 pages.
  36
  37 The second place where template files can live is in the global
  38 templates directory (the same place where the page.tmpl template lives).
  39 This is a useful place to put template files if you want to prevent
  40 them being edited from the web, and you don't want to have to make
  41 them work as wiki pages.
  42
  43 ## OPTIONS
  44
  45 **template**: The template to use for the report.
  46
  47 **pages**: A PageSpec to determine the pages to report on.
  48
  49 **sort**: How the matching pages should be sorted.  Sorting criteria are separated by spaces.
  50
  51 The possible values for sorting are:
  52
  53 * **page**: Sort by the full page ID.
  54 * **pagename**: Sort by the base page name.
  55 * **pagename_natural**: Sort by the base page name, using Sort::Naturally if it is installed.
  56 * **mtime**: Sort by the page modification time.
  57 * **age**: Sort by the page creation time, newest first.
  58
  59 Any other value is taken to be a field name to sort by.
  60 If a sort value begins with a minus (-) then the order for that field is reversed.
  61
  62 ### Headers
  63
  64 An additional option is the "headers" option.  This is a space-separated
  65 list of field names which are to be used as headers in the report.  This
  66 is a way of getting around one of the limitations of HTML::Template, that
  67 is, not being able to do tests such as
  68 "if this-header is not equal to previous-header".
  69
  70 Instead, that logic is performed inside the plugin.  The template is
  71 given parameters "HEADER1", "HEADER2" and so on, for each header.
  72 If the value of a header field is the same as the previous value,
  73 then HEADER**N** is set to be empty, but if the value of the header
  74 field is new, then HEADER**N** is given that value.
  75
  76 #### Example
  77
  78 Suppose you're writing a blog in which you record "moods", and you
  79 want to display your blog posts by mood.
  80
  81     \[[!report template="mood_summary"
  82     pages="blog/*"
  83     sort="Mood Date title"
  84     headers="Mood"]]
  85
  86 The "mood_summary" template might be like this:
  87
  88     <TMPL_IF NAME="HEADER1">
  89     ## <TMPL_VAR NAME="HEADER1">
  90     </TMPL_IF>
  91     ### <TMPL_VAR NAME="TITLE">
  92     (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]]
  93     <TMPL_VAR NAME="DESCRIPTION">
  94
  95 ### Advanced Options
  96
  97 The following options are used to improve efficiency when dealing
  98 with large numbers of pages; most people probably won't need them.
  99
 100 **trail**:
 101
 102 A page or pages to use as a "trail" page.  When a trail page is used,
 103 the matching pages are limited to (a subset of) the pages which that
 104 page links to; the "pages" pagespec in this case, rather than selecting
 105 pages from the entire wiki, will select pages from within the set of pages
 106 given by the trail page.
 107
 108 **doscan**:
 109
 110 Whether this report should be called in "scan" mode; if it is, then
 111 the pages which match the pagespec are added to the list of links from
 112 this page.  This can be used by *another* report by setting this
 113 page to be a "trail" page in *that* report.
 114 It is not possible to use "trail" and "doscan" at the same time.
 115 By default, "doscan" is false.
 116
 117 ## TEMPLATE PARAMETERS
 118
 119 The templates are in HTML::Template format, just as [[plugins/template]] and
 120 [[ftemplate]] are.  The parameters passed in to the template are as follows:
 121
 122 ***fields***:
 123
 124 The structured data from the current matching page.  This includes
 125 "title" and "description" if they are defined.
 126
 127 ***common values***:
 128
 129 Values known for all pages: "page", "destpage".  Also "basename" (the base name of the page).
 130
 131 ***passed-in values***:
 132
 133 Any additional parameters to the report directive are passed to the
 134 template; a parameter will override the matching "field" value.
 135 For example, if you have a "Mood" field, and you pass Mood="bad" to
 136 the report, then that will be the Mood which is given for the whole
 137 report.
 138
 139 Generally this is useful if one wishes to make a more generic
 140 template and hide or show portions of it depending on what
 141 values are passed in the report directive call.
 142
 143 For example, one could have a "hide_mood" parameter which would hide
 144 the "Mood" section of your template when it is true, which one could
 145 use when the Mood is one of the headers.
 146
 147 ***headers***:
 148
 149 See the section on Headers.
 150
 151 ***first and last***:
 152
 153 If this is the first page-record in the report, then "first" is true.
 154 If this is the last page-record in the report, then "last" is true.
 155
 156 ## PREREQUISITES
 157
 158     IkiWiki
 159     IkiWiki::Plugin::field
 160     HTML::Template
 161     Encode
 162
 163 ## DOWNLOAD
 164
 165 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/report.pm>
 166 * git repo at git://github.com/rubykat/ikiplugins.git