{local-reporter}
Plugin: Reporting Plugin, from version 1.2
Allows reporting on the current page or reported item.
Description
This reporter will display the contents of any sub-item of either the current item or that specified by the 'source' parameter, identified using the "prefix:key" value. If it is used in a top-level report on a page, the current page will be the default source.
Usage
Parameters
| Name |
Required |
Default |
Description |
| [default]/key | | | The key chain value to report on. |
| source | | | The location to report on. A standard Confluence content link. E.g. "My Page", "^attachment.ext", etc. |
| matchAll | | true | If set to 'false', content matching any of the criteria will be returned. Otherwise, the content must match all criteria. |
Notes
This macro was formerly known as the {current-item-reporter}, but was expanded in Reporting 1.2.
Recipes
See Also
is there an example of how this is used?
does it go in another reporter?
does it go in a report-block?
does it go in a report-body?
Precisely the question I was about to ask...
Generally, it would be a Real Good Idea to have the overall structure of the Reporting plugin as a BNF on the plugin's main page. I realize that this runs counter to the De-Geeking philosophy of Confluence, but if you don't do something like this you're going to waste gazillions of hours of people's time looking for the answers.
If it's necessary to de-geek this a bit more, perhaps making a wizard or other structural thing in the WYSIWYG editor would be a good idea...
To attempt to answer your question, however: One of the recipes shows it inside the {report-body}. I have yet to get it to work, however...
Brian, take a look at the examples in the comments on the Space Supplier page. Shows how to use this macro.
Thanks. It had been such a long time, I quite forgot I had commented on this macro, but this is good to know.
Hey Brian,
Took a while to get back to it (I think I got sidetracked), but I have added a basic report structure to the Macros tab in the Reporting Plugin page. If you get a chance, have a look and let me know if any improvements can be made.
Thanks, sorry for the delay.
David
Well, I've taken even longer to reply to you, so there.
The report structure is very informative; thanks. I'd like to see {report-generator} replaced with {report-xxx} in keeping with your convention for the filters, sorters, and reporters, to make it much more plain what can be substituted there.
It still doesn't make it plain where {local-reporter} fits, though I have finally worked that out. From this side of that revelation, it doesn't seem impossible to figure it out from what you say, but I was certainly never able to do that before seeing the example you gave. The key (so to speak) is something that I never quite managed to understand, which is that it's possible to nest one report inside another. It makes perfect sense to set that context for a report with a narrower scope.
In short, {local-reporter} must be used within a report that appears in the {report-body} of a {report-list} or {report-block} macro, or in a {report-column} of a {report-table} macro, to scope the inner report to one row of the enclosing report.
Also, the structure doesn't make it obvious that {report-body} cannot appear in a {report-table} since those are structured by columns rather than rows.
I suggest that you change the line
{report-body}Content for each item goes here{report-body}{report-body}Content for each report item, typically using {report-info} to get the data fields, or even another report (not of the same type, since Confluence can't nest macros of the same type) using a {local-reporter}, goes here{report-body}Finally, this page has an error in the Description section, where it says
There is no 'location' parameter, but the 'source' parameter fits that description.Thanks for the suggestions Brian. I've updated the documentation along the lines you suggested. With regards to {local-reporter}, it's actually quite possible to use it in the top level report. I do it all the time, especially if I want to list the children of the current page, since doing this:
{local-reporter:content:children}is massively more efficient than this
{content-reporter:scope=@self > children}It's not a complete replacement - it works best for getting stuff directly related to the current page, not getting data based on labels, or across spaces - but it's quite useful. I've updated the description to reflect that if used at the top level, the current page/blog/whatever will be the default 'source'.
Hi David,
I am attempting to create a report that will display the 5 most recently updated pages or blogposts that are also labelled with the same labels as the current page. Currently, I have the basic '5 most recently modified' elements:
{report-block:maxResults=5} {content-reporter:space=-@all,-@self|types=page,news} {date-sort:content:modification date|order=descending} {content-reporter} {report-body}{main_item_right}by {report-info:content:creator|link=true} ({report-info:content:modification date|format=dd MMM}){div_end}{main_item_left}{report-image:content:icon|link=true}{report-info:content:title|link=true}{div_end}{report-body} {report-empty}No news items are available.{report-empty} {report-block}but I am unsure as to how to pass the 'labels of current page' to the report. Is this possible through the local-reporter?
Also - many thanks for an extremely powerful plugin!
Keith
Hi Keith,
I can't think of any way to do what you need currently - all the filters expect labels to be hard-coded, not pulled from another source. You may be able to hack something together by combining it with the Replace and Render plugin, but I can't think of a specific way to get what you're after there either...
The best thing is probably to create a feature request, and we'll see what happens in a future version. Mostly, I'm unsure on how the syntax would work to tell the filter where to get the labels to compare it to. It could be a matter of writing a custom filter specific to the task. Eg.
{content-reporter:...} {match-filter:source=@self|key=content:labels} {content-reporter}Which would match the 'content:labels' property between the current item being reported on and the '@self' source.
Hi David,
Many thanks for such a prompt response and your advice. I will play around with the plugin a little more - failing that, I will expand on some existing macros.
Keep up the good work!
Keith
I've looked around and unfortunately haven't found the information that will help me understand how to take a very inefficient content-reporter and turn it into a fast-loading local-reporter. I have the following report that just crawls:
{report-table} {content-reporter:space=@self|types=page|scope=Task List Page Name > descendents} {text-sort:data:sc_iteration|order=ascending} {text-sort:data:sc_release|order=ascending} {text-sort:data:sc_status|order=ascending} {text-sort:data:sc_tasks|order=ascending} {content-filter:label=-wiki_structure} {content-filter:label=-review} {content-reporter} {report-column:title=Status}{report-info:data:sc_status}{report-column} {report-column:title=Name}{report-link}{report-info:content:title}{report-link}{report-column} {report-column:title=Iteration}{report-info:data:sc_iteration}{report-column} {report-column:title=Release}{report-info:data:sc_release}{report-column} {report-column:title=Requirement(s)}{report-info:data:sc_tasks|render=wiki}{report-column} {report-column:title=Reviewer}{report-info:data:sc_reviewer}{report-column} {report-empty}No tasks that match the filters were found.{report-empty} {report-table}This page is not necessarily the parent page of the content that gets reported on. I have a tasks area, and the top-level page may include instructions or some organizational information and link to different reports on active tasks, inactive, lists sorted by user, etc.; this report above would be just one of those. I guess the reports would be children of the parent page of the area within a space I want to limit my report to.
How can I change the reporter type to get it to run more quickly?
Thanks!
As a general rule, if you can use the local-reporter instead of the content-reporter your plugin will run faster. In this case, you can rewrite your reporter section like this:
{local-reporter:content:descendents|source=Task List Page Name} {text-sort:data:sc_iteration|order=ascending} {text-sort:data:sc_release|order=ascending} {text-sort:data:sc_status|order=ascending} {text-sort:data:sc_tasks|order=ascending} {content-filter:label=-wiki_structure, -review} {local-reporter}The reason this is faster is that local-reporter will simply start at the source and then work through it's descendents, whereas content-reporter will basically have to check every page in the current space. Essentially, I only use content-reporter when there is no other option, usually where I'm reporting on pages with a specific label.
Hope that helps.
I'm trying to get a report which will write out the breadcrumb trail. So far I have the code below, which is doing nothing
Where am I going wrong?
{report-list} {local-reporter:content:ancestors}{local-reporter} {report-body}{report-info:content:title|link=true}, {report-body} {report-list}The report you list should work, but will only list any parent pages. It will not automatically list the Dashboard or Space name. Also, note that it will have a trailing ', ' after the last parent page. Something like this would give you a more complete breadcrumb:
{link-to:dashboard}Dashboard{link-to} > {report-info:content:space|link=true} > {report-on:content:ancestors|separator=" > "}{report-info:content:title|link=true}{report-on} > {report-info:content:title|link=true}Aha!
Thank you, David, for shedding more light on the {report-on} macro.
As with {local-reporter} itself – which had been something of a mystery to me until lately, hence the watch that notified me of your comment here – I'd been pretty sure there was something that fulfilled this purpose, and I knew about {report-on}, but didn't put them together.
And once again, the often nebulous but very real value of the serendipitous aspects of wikis asserts itself, and once again I am painfully reminded of how difficult it is for those who understand a really neat technology best to get the message across to those who need and want it most. This is, of course, a major step in the right direction, because (QED via this note) it worked, but it highlights our still-too-primitive understanding of how to search for a fact or a concept that is encoded in natural language for which there are only the barest of standards (which, such as they are, are all but impossible to enforce), and none at all covering a canonical mapping of concepts to semantic values.
Since we won't solve that problem this morning, it would be very instructive to include a description of this example, and perhaps others, in the {report-on} macro page. My cognitive failure in finding what I wanted on that page was in not understanding that any object addressable by a keychain could become the context of a subreport, and that that object could also be a Collection.
While it does state that fairly explicitly, the cognitive link to its real use and value to me was blocked by my then-current lack of understanding of the exact nature of a keychain, so the fault is not yours, but the problem belongs to both of us.
The Meyers-Briggs Type Inventory classification that you and I probably share says that people like us have a constitutional aversion to explaining what they consider obvious, and it violates some of our most cherished principles of data design, but including stuff like that can be very helpful.
Hi Brian,
Thanks for the comments. I agree - the documentation about reporting in particular is rather dispersed and relatively scant, considering its complexity. The main reasons for this are a) time and b) figuring out a good way to pull it all together. The plugin pages themselves are overdue for an overhaul to make them more informative, but in the meantime if you feel motivated, feel free to add comments in formal documentation language that explains some useful discoveries you've made and I'll integrate them into the documentation. In many ways, you know what you need to know much better than I do. Which is admittedly somewhat of a cop-out, but still, I am afraid, true.
And for the record I am usually an INTP.
Updated by Brian M. Thomas
Mar 19, 2008 05:27
I very nearly guessed that...
I (like Sherlock Holmes and a TV character he inspired, Dr. Gregory House) am INTJ (read the entry and you'll see why I didn't emulate your smiley
).
I'd say the MBTI tracks pretty truly here, making both of us better suited to our respective jobs.
Backing up one comment: Though you might want to beware of adopting this attitude, let me say that from my perspective, your approach to the documentation is much less a cop-out than you or many others may think, considering the business model and its associated social – if not legal – contract with your customers:
Your products are priced dramatically lower than competitive commercial offerings, and you offer support whose effectiveness rivals theirs, in my experience, at least. TANSTAAFL aside, letting the customer share ownership of, and responsibility for, filling the knowledge gap between the developers and end users is not only not something to lament but tremendously effective, as you and many others are beginning to demonstrate. As you say, I'm in a much better position to know my needs than you are, though I don't always know what they are either, so it's clear that both the product per se and the documentation (which is properly part of the product as well) are best developed collaboratively by the builders and the users – both of whose roles you and I both fulfill with respect to the same product but in relation to different partners.
And I'll take a stab at fulfilling your request.
Thanks David.
Does the 'source' parameter of the local-reporter macro actually work. I've specified the source to be the name of a child page, whose children I want to report on (thus, I want to report on the grandchildren of the page containing the macro).
However, it claims that this page cannot be found:
The same page works if I use it as the 'scope' parameter of the content-reporter
macro, but of course I want to avoid the associated performance hit...
Ah..the problem was that I had enclosed the page name in quotes. Though this appears in the content-reporter documentation, it doesn't seem to work for the local-reporter.
Yeah, content-reporter and local-reporter use two totally different systems for specifying what pages match. The content-reporter's 'scope' parameter is more like a filter, specifying which pages will match, and you can specify multiple options. The local-reporter's 'source' (and source is used on several macros in the same way) is a specific, single value which is the starting point for the rest of the macro's functionality.
Hi,
is it possible to hide the source error message, when you have specified a "SOURCE" which is not avaible ?
Not currently. Create a feature request and we'll see if we can add an optional parameter (eg 'sourceOptional=true' or something).
Hi,
thx for reply.
Will there be a component 'local-reporter' ? Otherwise i would create a request under "unknown component".
Just go with unknown. There are too many components to bother keeping track with these days...