1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
[[!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.
**pagenames**: If given instead of pages, this is interpreted as a
space-separated list of links to pages, and they are shown in exactly the order
given: the sort and pages parameters cannot be used in conjunction with this
one. If they are used, they will be ignored.
**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.
**start**: Start the report at the given page-index; the index starts
from zero.
**count**: Report only on N pages where count=N.
**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">
### Multi-page Reports
Reports can now be split over multiple pages, so that there aren't
too many items per report-page.
**per_page**: how many items to show per report-page.
**first_page_is_index**: If true, the first page of the report is just
an index which contains links to the other report pages.
If false, the first page will contain report-content as well as links
to the other pages.
### Advanced Options
The following options are used to improve efficiency when dealing
with large numbers of pages; most people probably won't need them.
**maketrail**:
Make a trail; if true, then this report is called in "scan" mode and 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 "maketrail" at the same time.
By default, "maketrail" 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 (the current page)
* destpage (the destination page)
* basename (the base name of the page)
* recno (N if the page is the Nth page in the report)
### Prev_Page And Next_Page
The "prev_page" and "next_page" variables will give the value of the
previous page in the matching pages, or the next page in the matching pages.
This is mainly useful for a "here_only" report.
### 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.
### 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.
|