]> sipb.mit.edu Git - ikiwiki.git/blob - doc/ikiwiki/directive/report.mdwn
8f8e6b4e8fed0e0b5ec5ee44c94214675963ef48
[ikiwiki.git] / doc / 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 **trail**: A page or pages to use as a "trail" page.
34
35 When a trail page is used, the matching pages are limited to (a subset
36 of) the pages which that page links to; the "pages" pagespec in this
37 case, rather than selecting pages from the entire wiki, will select
38 pages from within the set of pages given by the trail page.
39
40 Additional space-separated trail pages can be given in this option.
41 For example:
42
43     trail="animals/cats animals/dogs"
44
45 This will take the links from both the "animals/cats" page and the
46 "animals/dogs" page as the set of pages to apply the PageSpec to.
47
48 **sort**: A SortSpec to determine how the matching pages should be sorted.
49
50 **here_only**: Report on the current page only.
51
52 This is useful in combination with "prev_" and "next_" variables to
53 make a navigation trail.
54 If the current page doesn't match the pagespec, then no pages will
55 be reported on.
56
57 ### Headers
58
59 An additional option is the "headers" option.  This is a space-separated
60 list of field names which are to be used as headers in the report.  This
61 is a way of getting around one of the limitations of HTML::Template, that
62 is, not being able to do tests such as
63 "if this-header is not equal to previous-header".
64
65 Instead, that logic is performed inside the plugin.  The template is
66 given parameters "HEADER1", "HEADER2" and so on, for each header.
67 If the value of a header field is the same as the previous value,
68 then HEADER**N** is set to be empty, but if the value of the header
69 field is new, then HEADER**N** is given that value.
70
71 #### Example
72
73 Suppose you're writing a blog in which you record "moods", and you
74 want to display your blog posts by mood.
75
76     \[[!report template="mood_summary"
77     pages="blog/*"
78     sort="Mood Date title"
79     headers="Mood"]]
80
81 The "mood_summary" template might be like this:
82
83     <TMPL_IF NAME="HEADER1">
84     ## <TMPL_VAR NAME="HEADER1">
85     </TMPL_IF>
86     ### <TMPL_VAR NAME="TITLE">
87     (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]]
88     <TMPL_VAR NAME="DESCRIPTION">
89     
90 ### Advanced Options
91
92 The following options are used to improve efficiency when dealing
93 with large numbers of pages; most people probably won't need them.
94
95 **doscan**:
96
97 Whether this report should be called in "scan" mode; if it is, then
98 the pages which match the pagespec are added to the list of links from
99 this page.  This can be used by *another* report by setting this
100 page to be a "trail" page in *that* report.
101 It is not possible to use "trail" and "doscan" at the same time.
102 By default, "doscan" is false.
103
104 ## TEMPLATE PARAMETERS
105
106 The templates are in HTML::Template format, just as [[plugins/template]] and
107 [[ftemplate]] are.  The parameters passed in to the template are as follows:
108
109 ### Fields
110
111 The structured data from the current matching page.  This includes
112 "title" and "description" if they are defined.
113
114 ### Common values
115
116 Values known for all pages: "page", "destpage".  Also "basename" (the
117 base name of the page).
118
119 ### Passed-in values
120
121 Any additional parameters to the report directive are passed to the
122 template; a parameter will override the matching "field" value.
123 For example, if you have a "Mood" field, and you pass Mood="bad" to
124 the report, then that will be the Mood which is given for the whole
125 report.
126
127 Generally this is useful if one wishes to make a more generic
128 template and hide or show portions of it depending on what
129 values are passed in the report directive call.
130
131 For example, one could have a "hide_mood" parameter which would hide
132 the "Mood" section of your template when it is true, which one could
133 use when the Mood is one of the headers.
134
135 ### Prev_ And Next_ Items
136
137 Any of the above variables can be prefixed with "prev_" or "next_"
138 and that will give the previous or next value of that variable; that is,
139 the value from the previous or next page that this report is reporting on.
140 This is mainly useful for a "here_only" report.
141
142 ### Headers
143
144 See the section on Headers.
145
146 ### First and Last
147
148 If this is the first page-record in the report, then "first" is true.
149 If this is the last page-record in the report, then "last" is true.