176 lines
6.1 KiB
Markdown
176 lines
6.1 KiB
Markdown
[[!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.
|