doc/plugins/contrib/report/ikiwiki/directive/report.mdwn

   1 [[!toc]]
   2 The `report` directive is supplied by the [[!iki plugins/contrib/report desc=report]] plugin.
   3
   4 This enables one to report on the structured data ("field" values) of
   5 multiple pages; the output is formatted via a template.  This depends
   6 on the [[plugins/contrib/field]] plugin.
   7
   8 The pages to report on are selected by a PageSpec given by the "pages"
   9 parameter.  The template is given by the "template" parameter.
  10 The template expects the data from a single page; it is applied
  11 to each matching page separately, one after the other.
  12
  13 Additional parameters can be used to fill out the template, in
  14 addition to the "field" values.  Passed-in values override the
  15 "field" values.
  16
  17 There are two places where template files can live.  One is in the
  18 /templates directory on the wiki.  These templates are wiki pages, and
  19 can be edited from the web like other wiki pages.
  20
  21 The second place where template files can live is in the global
  22 templates directory (the same place where the page.tmpl template lives).
  23 This is a useful place to put template files if you want to prevent
  24 them being edited from the web, and you don't want to have to make
  25 them work as wiki pages.
  26
  27 ## OPTIONS
  28
  29 **template**: The template to use for the report.
  30
  31 **pages**: A PageSpec to determine the pages to report on.
  32
  33 **pagenames**: If given instead of pages, this is interpreted as a
  34 space-separated list of links to pages, and they are shown in exactly the order
  35 given: the sort and pages parameters cannot be used in conjunction with this
  36 one.  If they are used, they will be ignored.
  37
  38 **trail**: A page or pages to use as a "trail" page.
  39
  40 When a trail page is used, the matching pages are limited to (a subset
  41 of) the pages which that page links to; the "pages" pagespec in this
  42 case, rather than selecting pages from the entire wiki, will select
  43 pages from within the set of pages given by the trail page.
  44
  45 Additional space-separated trail pages can be given in this option.
  46 For example:
  47
  48     trail="animals/cats animals/dogs"
  49
  50 This will take the links from both the "animals/cats" page and the
  51 "animals/dogs" page as the set of pages to apply the PageSpec to.
  52
  53 **start**: Start the report at the given page-index; the index starts
  54 from zero.
  55
  56 **count**: Report only on N pages where count=N.
  57
  58 **sort**: A SortSpec to determine how the matching pages should be sorted.
  59
  60 **here_only**: Report on the current page only.
  61
  62 This is useful in combination with "prev_" and "next_" variables to
  63 make a navigation trail.
  64 If the current page doesn't match the pagespec, then no pages will
  65 be reported on.
  66
  67 ### Headers
  68
  69 An additional option is the "headers" option.  This is a space-separated
  70 list of field names which are to be used as headers in the report.  This
  71 is a way of getting around one of the limitations of HTML::Template, that
  72 is, not being able to do tests such as
  73 "if this-header is not equal to previous-header".
  74
  75 Instead, that logic is performed inside the plugin.  The template is
  76 given parameters "HEADER1", "HEADER2" and so on, for each header.
  77 If the value of a header field is the same as the previous value,
  78 then HEADER**N** is set to be empty, but if the value of the header
  79 field is new, then HEADER**N** is given that value.
  80
  81 #### Example
  82
  83 Suppose you're writing a blog in which you record "moods", and you
  84 want to display your blog posts by mood.
  85
  86     \[[!report template="mood_summary"
  87     pages="blog/*"
  88     sort="Mood Date title"
  89     headers="Mood"]]
  90
  91 The "mood_summary" template might be like this:
  92
  93     <TMPL_IF NAME="HEADER1">
  94     ## <TMPL_VAR NAME="HEADER1">
  95     </TMPL_IF>
  96     ### <TMPL_VAR NAME="TITLE">
  97     (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]]
  98     <TMPL_VAR NAME="DESCRIPTION">
  99
 100 ### Multi-page Reports
 101
 102 Reports can now be split over multiple pages, so that there aren't
 103 too many items per report-page.
 104
 105 **per_page**: how many items to show per report-page.
 106
 107 **first_page_is_index**: If true, the first page of the report is just
 108 an index which contains links to the other report pages.
 109 If false, the first page will contain report-content as well as links
 110 to the other pages.
 111
 112 ### Advanced Options
 113
 114 The following options are used to improve efficiency when dealing
 115 with large numbers of pages; most people probably won't need them.
 116
 117 **maketrail**:
 118
 119 Make a trail; if true, then this report is called in "scan" mode and the
 120 pages which match the pagespec are added to the list of links from this
 121 page.  This can be used by *another* report by setting this page to be a
 122 "trail" page in *that* report.
 123
 124 It is not possible to use "trail" and "maketrail" at the same time.
 125 By default, "maketrail" is false.
 126
 127 ## TEMPLATE PARAMETERS
 128
 129 The templates are in HTML::Template format, just as [[plugins/template]] and
 130 [[ftemplate]] are.  The parameters passed in to the template are as follows:
 131
 132 ### Fields
 133
 134 The structured data from the current matching page.  This includes
 135 "title" and "description" if they are defined.
 136
 137 ### Common values
 138
 139 Values known for all pages: "page", "destpage".  Also "basename" (the
 140 base name of the page).
 141
 142 ### Passed-in values
 143
 144 Any additional parameters to the report directive are passed to the
 145 template; a parameter will override the matching "field" value.
 146 For example, if you have a "Mood" field, and you pass Mood="bad" to
 147 the report, then that will be the Mood which is given for the whole
 148 report.
 149
 150 Generally this is useful if one wishes to make a more generic
 151 template and hide or show portions of it depending on what
 152 values are passed in the report directive call.
 153
 154 For example, one could have a "hide_mood" parameter which would hide
 155 the "Mood" section of your template when it is true, which one could
 156 use when the Mood is one of the headers.
 157
 158 ### Prev_ And Next_ Items
 159
 160 Any of the above variables can be prefixed with "prev_" or "next_"
 161 and that will give the previous or next value of that variable; that is,
 162 the value from the previous or next page that this report is reporting on.
 163 This is mainly useful for a "here_only" report.
 164
 165 ### Headers
 166
 167 See the section on Headers.
 168
 169 ### First and Last
 170
 171 If this is the first page-record in the report, then "first" is true.
 172 If this is the last page-record in the report, then "last" is true.