<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>report</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="../../../../../style.css" type="text/css" />
<link rel="stylesheet" href="../../../../../local.css" type="text/css" />
</head>
<body>
<div class="page">
<div class="pageheader">
<div class="header">
<span>
<span class="parentlinks">
<a href="../../../../../index.html">ikiwiki</a>/
<a href="../../../../../plugins.html">plugins</a>/
<a href="../../../../contrib.html">contrib</a>/
<a href="../../../report.html">report</a>/
<a href="../../../../../index.html">ikiwiki</a>/
<a href="../../../../../index.html">directive</a>/
</span>
<span class="title">
report
</span>
</span>
</div>
</div>
<div id="pagebody">
<div id="content" role="main">
<div class="toc">
<ol>
<li class="L2"><a href="#index1h2">OPTIONS</a>
</li>
<li class="L2"><a href="#index2h2">TEMPLATE PARAMETERS</a>
</li>
</ol>
</div>
<p>The <code>report</code> directive is supplied by the <a href="http://ikiwiki.info/plugins/contrib/report/">report</a> plugin.</p>
<p>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 <a href="../../../field.html">field</a> plugin.</p>
<p>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.</p>
<p>Additional parameters can be used to fill out the template, in
addition to the "field" values. Passed-in values override the
"field" values.</p>
<p>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.</p>
<p>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.</p>
<h2><a name="index1h2"></a>OPTIONS</h2>
<p><strong>template</strong>: The template to use for the report.</p>
<p><strong>pages</strong>: A PageSpec to determine the pages to report on.</p>
<p><strong>pagenames</strong>: 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.</p>
<p><strong>trail</strong>: A page or pages to use as a "trail" page.</p>
<p>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.</p>
<p>Additional space-separated trail pages can be given in this option.
For example:</p>
<pre><code>trail="animals/cats animals/dogs"
</code></pre>
<p>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.</p>
<p><strong>start</strong>: Start the report at the given page-index; the index starts
from zero.</p>
<p><strong>count</strong>: Report only on N pages where count=N.</p>
<p><strong>sort</strong>: A SortSpec to determine how the matching pages should be sorted.</p>
<p><strong>here_only</strong>: Report on the current page only.</p>
<p>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.</p>
<h3><a name="index1h3"></a>Headers</h3>
<p>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".</p>
<p>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*<em>N</em>* is set to be empty, but if the value of the header
field is new, then HEADER*<em>N</em>* is given that value.</p>
<h4><a name="index1h4"></a>Example</h4>
<p>Suppose you're writing a blog in which you record "moods", and you
want to display your blog posts by mood.</p>
<pre><code>[[!report template="mood_summary"
pages="blog/*"
sort="Mood Date title"
headers="Mood"]]
</code></pre>
<p>The "mood_summary" template might be like this:</p>
<pre><code><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">
</code></pre>
<h3><a name="index2h3"></a>Multi-page Reports</h3>
<p>Reports can now be split over multiple pages, so that there aren't
too many items per report-page.</p>
<p><strong>per_page</strong>: how many items to show per report-page.</p>
<p><strong>first_page_is_index</strong>: 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.</p>
<h3><a name="index3h3"></a>Advanced Options</h3>
<p>The following options are used to improve efficiency when dealing
with large numbers of pages; most people probably won't need them.</p>
<p><strong>maketrail</strong>:</p>
<p>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 <em>another</em> report by setting this page to be a
"trail" page in <em>that</em> report.</p>
<p>It is not possible to use "trail" and "maketrail" at the same time.
By default, "maketrail" is false.</p>
<h2><a name="index2h2"></a>TEMPLATE PARAMETERS</h2>
<p>The templates are in HTML::Template format, just as <a href="../../../../template.html">template</a> and
<a href="../../../ftemplate.html">ftemplate</a> are. The parameters passed in to the template are as follows:</p>
<h3><a name="index4h3"></a>Fields</h3>
<p>The structured data from the current matching page. This includes
"title" and "description" if they are defined.</p>
<h3><a name="index5h3"></a>Common values</h3>
<p>Values known for all pages:</p>
<ul>
<li>page (the current page)</li>
<li>destpage (the destination page)</li>
<li>basename (the base name of the page)</li>
<li>recno (N if the page is the Nth page in the report)</li>
</ul>
<h3><a name="index6h3"></a>Prev_Page And Next_Page</h3>
<p>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.</p>
<h3><a name="index7h3"></a>Passed-in values</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h3><a name="index8h3"></a>Headers</h3>
<p>See the section on Headers.</p>
<h3><a name="index9h3"></a>First and Last</h3>
<p>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.</p>
</div>
</div>
<div id="footer" class="pagefooter" role="contentinfo">
<div id="pageinfo">
<div id="backlinks">
Links:
<a href="../../../report.html">report</a>
</div>
<div class="pagedate">
Last edited <span class="date">Tue Feb 26 23:01:54 2019</span>
<!-- Created <span class="date">Tue Feb 26 23:01:54 2019</span> -->
</div>
</div>
<!-- from ikiwiki -->
</div>
</div>
</body>
</html>
