diff options
Diffstat (limited to 'doc/plugins/contrib/report')
| -rw-r--r-- | doc/plugins/contrib/report/discussion.mdwn | 75 | ||||
| -rw-r--r-- | doc/plugins/contrib/report/ikiwiki/directive/report.mdwn | 149 |
2 files changed, 224 insertions, 0 deletions
diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn new file mode 100644 index 000000000..e23a4ced4 --- /dev/null +++ b/doc/plugins/contrib/report/discussion.mdwn @@ -0,0 +1,75 @@ +Wow, this plugin does a lot... it seems to be `inline` (but without the feeds +or the ability to not have `archive="yes"`), plus part of +[[plugins/contrib/trail]], plus some sorting, plus an ingenious workaround +for template evaluation being relatively stateless. + +A large part of this plugin would just fall off if one of the versions of +"[[todo/allow_plugins_to_add_sorting_methods]]" was merged, which was a +large part of the idea of that feature request :-) To make use of that +you'd have to use `pagespec_match_list` in the trail case too, but that's +easy enough - just add `list => [@the_trail_pages]` to the arguments. + +Another large part would fall off if this plugin required, and internally +invoked, `inline` (like my `comments` plugin does) - `inline` runs +`pagetemplate` hooks, and in particular, it'll run the `field` hook. +Alternatively, this plugin could invoke `pagetemplate` hooks itself, +removing the special case for `field`. + +Perhaps the `headers` thing could migrate into inline somehow? That might +lead to making inline too big, though. + +> I think inline is *already* too big, honestly. --[[KathrynAndersen]] + +>> A fair point; perhaps my complaint should be that *inline* does +>> too many orthogonal things. I suppose the headers feature wouldn't +>> really make sense in an inline that didn't have `archive="yes"`, +>> so it'd make sense to recommend this plugin as a replacement +>> for inlining with archive=yes (for which I now realise "inline" +>> is the wrong verb anyway :-) ) --s + +>>> I think *inline* would be a bit less unwieldy if there was some way of factoring out the feed stuff into a separate plugin, but I don't know if that's possible. --K.A. + +Is the intention that the `trail` part is a performance hack, or a way +to select pages? How does it relate to [[todo/wikitrails]] or +[[plugins/contrib/trail]]? --[[smcv]] + +> The `trail` part is *both* a performance hack, and a way to select pages. I have over 5000 pages on my site, I need all the performance hacks I can get. +> For the performance hack, it is a way of reducing the need to iterate through every single page in the wiki in order to find matching pages. +> For the way-to-select-pages, yes, it is intended to be similar to [[todo/wikitrails]] and [[plugins/contrib/trail]] (and will be more similar with the new release which will be happening soon; it will add prev_* and next_* variables). +> The idea is that, rather than having to add special "trail" links on PageA to indicate that a page is part of the trail, +> it takes advantage of the `%links` hash, which already contains, for each page, an array of the links from that page to other pages. No need for special markup, just use what's there; a trail is defined as "all the pages linked to from page X", and since it's an array, it has an order already. +> But to avoid that being too limiting, one can use a `pages=...` pagespec to filter that list to a subset; only the pages one is interested in. +> And one can also sort it, if one so desires. +> --[[KathrynAndersen]] + +>> That's an interesting approach to trails; I'd missed the fact that +>> links are already ordered. +>> +>> This does have the same problems as tags, though: see +>> [[bugs/tagged()_matching_wikilinks]] and +>> [[todo/matching_different_kinds_of_links]]. I suppose the question +>> now is whether new code should be consistent with `tag` (and +>> potentially be fixed at the same time as tag itself), or try to +>> avoid those problems? +>> +>> The combination of `trail` with another pagespec in this plugin +>> does provide a neat way for it to work around having unwanted +>> pages in the report, by limiting by a suitable tag or subdirectory +>> or something. --s + +>>> Either that, or somehow combine tagging with fields, such that one could declare a tag, and it would create both a link and a field with a given value. (I've been working on something like that, but it still has bugs). +>>> That way, the test for whether something is tagged would be something like "link(tag/foo) and field(tag foo)". +>>> --K.A. + +>>>> I can see that this'd work well for 1:1 relationships like next +>>>> and previous, but I don't think that'd work for pages with more than +>>>> one tag - as far as I can see, `field`'s data model is that each +>>>> page has no more than one value for each field? +>>>> [[todo/Matching_different_kinds_of_links]] has some thoughts about +>>>> how it could be implemented, though. --s + +>>>>> You have a point there. I'm not sure what would be better: to add the concept of arrays/sets to `field`, or to think of tags as a special case. Problem is, I find tags as they currently exist to be too limiting. I prefer something that can be used for Faceted Tagging <http://en.wikipedia.org/wiki/Faceted_classification>; that is, things like Author:Fred Nurk, Genre:Historical, Rating:Good, and so on. Of course, that doesn't mean that each tag is limited to only one value, either; just to take the above examples, something might have more than one author, or have multiple genres (such as Historical + Romance). + +>>>>> It might be that adding arrays to the `field` plugin is a good way to go: after all, even though field=value is the most common, with the flexibility of things like YAML, one could define all sorts of things. What I'm not so sure about is how to return the values when queried, since some things would be expecting scalars all the time. Ah, perhaps I could use wantarray? +>>>>> Is there a way of checking a HTML::Template template to see if it expecting an array for a particular value? +>>>>> --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn new file mode 100644 index 000000000..8f8e6b4e8 --- /dev/null +++ b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn @@ -0,0 +1,149 @@ +[[!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. + +**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. + +**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"> + +### Advanced Options + +The following options are used to improve efficiency when dealing +with large numbers of pages; most people probably won't need them. + +**doscan**: + +Whether this report should be called in "scan" mode; if it is, then +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 "doscan" at the same time. +By default, "doscan" 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", "destpage". Also "basename" (the +base name of the page). + +### 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. + +### Prev_ And Next_ Items + +Any of the above variables can be prefixed with "prev_" or "next_" +and that will give the previous or next value of that variable; that is, +the value from the previous or next page that this report is reporting on. +This is mainly useful for a "here_only" report. + +### 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. |