 | See Also: Macro Parameters Index |
 | Purpose of this page Let's restrict this to just discussion about searching for pages, rather than display or sorting - it kinda get's out of hand otherwise and lets us focus on the main problem. See also Better page lists for proposals for displaying results. Guy Fraser I'd like to include sorting in the API otherwise you can end up with each macro having to implement it's own sort routines |
It seems there are a number of macros that want to achieve in part similar goals - find a set of pages and then do something with that set of pages. Currently a number of macros have partial support for certain things, and various bugs are open 'make this macro work like that macro', or 'add AND support for lists of labels', which are all really neat but need to be implemented 1-by-1, and if they are done differently make them hard to use.
So the question is - what should we have? I've been adding to the metadata plugin to have AND support for labels, but the list goes on. Please use this page to get to a good consensus on what options should exist, and the drivers behind them:
| Field | Possible Values | Default | Description |
|---|---|---|---|
| label(s) | ~Europe~USA+customer a,b,c |
(all content) | Decide which content to include and exclude. Content must have ALL labels prefixed by a +, ANY content prefixed by a ~ or without a prefix, and NONE of the labels prefixed by -. |
| scope | children, ancestors, descendants | children, but only if page is given | Limit the pages to children, ancestors or descendants. This can work in conjunction with labels to produce pages that are both children and have particular labels. The - prefix can be used to exclude certain content - for example page=MyPage|scope=-children would exclude the children of MyPage. |
| page(s) | Page, @self, @parent, @home, @personal, @favourite, @all | @self, but only if scope is given | A particular page to limit to. Works in conjunction with the pages option to produce a set of pages, but there's no reason why you can't use it on its own. Defaults to this page. This can be a list of pages. Pages prefixed with '-' will be excluded from the results. |
| type | page, blog, comments?, news | page | Specify the type of page to search over. |
| space(s) | SPACE Space1,Space2 @personal, @global, @all, @favourite, @self |
@self | Specifies a list of space keys that content must be within to be returned. |
| sort | title/bitwise/natural/creation/modified Any piece of Metadata |
natural | Choose how items are sorted. This should also include metadata fields - even when used in other plugins. I don't think there's any reason why you couldn't ask the children macro to sort by a piece of metadata. This also should be a list of multiple levels? Maybe ASC and DESC for each sort field? |
| max(Results) | integer | 15 | Specifies a limit to the number of results. Processed after sorting. |
| reverse | true, false | false | reverse the sort order |
I'm happy to write this code in a generic way to make it more widely available, but will target the metadata one first as I have my own pressures 
but I would like to get some consistency first so I implement the right thing!
Scenarios
| Scenario | Description | Parameter Syntax - Metadata Plugin | Parameter Syntax - ContentByLabel proposal | Google Style |
|---|---|---|---|---|
| 1 | All children with a given label | scope=children|labels=release | scope=children|labels=release | |
| 2 | All pages with a given label | labels=article | labels=article | |
| 3 | All pages with a given label without another label | labels=article|excludeLabels=draft | labels=+article-draft | labels=+article -draft |
| 4 | All pages in a given space that have ALL labels | labels=article+published|space=Public | labels=article+published|space=Public | labels=article +published |
| 5 | All children of given page without a given label | page=MyPage|scope=children|excludeLabels=private | page=MyPage|scope=children|labels=-private | labels=-private |
| 6 | All pages with a given label and one of two labels without another | labels=fruit+(banana,orange)|excludeLabels=vegetable | labels=+fruit~banana~orange-vegetable | labels=banana orange +fruit -vegetable |
Scenario 1 - All children with a given label
Example. We use confluence to record upcoming releases of our software. Each release has a page and is summarized in a table on the parent page. Each release page is tagged with the label 'release', but we only want the children because we want to see only releases of this product
Scenario 2 - All pages with a given label
Example. All pages relating to a particular topic, such as some aspect of development. Can be used for an 'index'.
Scenario 3 - All pages with a given label without another label
Example. If you have a number of articles you are publishing in a knowledge base, it may be useful to label content both 'article' and have a label 'draft' indicating it wasn't ready for publishing. You would want to exclude anything with draft in it from your report.
Scenario 4 - All pages in a given space that have ALL labels
Example. For a 'product release schedule' that runs across multiple products, we may wish to make a separation between major and minor releases. So each page has a label of 'release' and either 'major' or 'minor'. A list of all major releases needs to have both 'release' and 'major'. However we may wish to restrict this to a given space if we have many departments producing many products, hence the space limitation
Scenario 5 - All children of given page without a given label
Example. Perhaps you have a knowledge base and you wish to have a review process prior to publishing. New pages will have no labels, and so this report could form a work queue of content that needs to be reviewed.
Weaknesses and strengths of the metadata plugin parameters:
| Weakness | Strengths |
|---|---|
|
|
Configuration Matrix
This table outlines on the LEFT all the combinations of possible parameters for root, pages, and labels. On the right, this is how they are interpreted. For example, case 1 says 'what happens if nothing is specified?' answer - default to the children of the current page. Case 4 says no specified root, but labels and pages have been specified. Assume that the root page is self, and filter using both labels and the pages - only pages that match on BOTH are used.
Note that the 'identity' pages feature allows you to specify a root page, and optionally filter by label so you can specify a fixed set of pages, or simply this page to report over.
| Case | Root | Pages | Labels | Root | Pages | Labels | Use for filtering | |
|---|---|---|---|---|---|---|---|---|
| 1 | null | null | null | @self | @children | null | Root&Pages | |
| 2 | null | null | X | null | null | X | Labels Only | |
| 3 | null | X | null | @self | X | null | Root&Pages | |
| 4 | null | X | Y | --------------> | @self | X | Y | All |
| 5 | X | null | null | X | @identity | null | Root&Pages | |
| 6 | X | null | Y | X | @identity | Y | All | |
| 7 | X | Y | null | X | Y | null | Root&Pages | |
| 8 | X | Y | Z | X | Y | Z | All |
Discuss.
Comments (66)
May 28, 2006
Mark Michaelis says:
Hello, one first start of the discussion: I think we have to rethink the type a...Hello,
one first start of the discussion: I think we have to rethink the type- and key-argument in conjunction with the introduction of private spaces in Confluence 2.2. So I don't think we require a profile-type anymore but rather that the key supports either a special profile, i. e. private space like: ~jdoe. To match to all private spaces we could introduce a syntax like either @profiles or ~* where the second one might raise problems as users might assume that the asterisk is a matching-char and thus CONF* will match the space CONF and CONF20. Don't know if this is a wanted behavior. If it is the second option should be preferred.
Kind Regards,
May 29, 2006
Kelsey Grant says:
Hmmm, good point. I haven't used the private spaces, but I guess they are privat...Hmmm, good point. I haven't used the private spaces, but I guess they are private - so it's hard to do a report over private spaces when you can't see the content? Maybe you need something like @myspace (ugh, please, not that but you get the idea).
In 2.2, do the profile pages exist as part of a private space or are they still off in special magic-profile land?
May 29, 2006
David Soul [Atlassian] says:
Personal spaces dont have to be private, by default they dont appear on dashboar...Personal spaces dont have to be private, by default they dont appear on dashboard or in search results. Profiles still exist in magic profile land for users without personal spaces, but fortunately profiles get turned into personal spaces automatically when a user creates one, and you can then access them then.
May 29, 2006
Mark Michaelis says:
Subject: Exclude Self I think another thing worth to discuss is what to do if a...Subject: Exclude Self
I think another thing worth to discuss is what to do if a page using the macro appears in the result-list itself. This refers to CONF-5245. One solution would be to agree upon the general rule that a page will never list itself in the results. Another, which I prefer in respect of backward-compatibility and because I generally like to hand most decisions to the user instead of forcing the user to apply to certain rules is to have another argument like includeSelf=true which should default to true for backward-compatibility.
May 29, 2006
Kelsey Grant says:
That's an interesting one. It could just be an optional add on parameter, pretty...That's an interesting one. It could just be an optional add on parameter, pretty simple.
May 29, 2006
Mark Michaelis says:
Subject: Configuration Matrix Question to @identity Perhaps its just me but I d...Subject: Configuration Matrix - Question to @identity
Perhaps its just me but I don't understand the value @identity, e. g. the following line:
I would rather expect the following:
I. e. if I specify the root I would expect that the childrens of this page are searched through.
Perhaps you could clarify this. Thanks!
May 29, 2006
Kelsey Grant says:
Mark, It's a bit funny and not intended to be exposed to the end user. The issue...Mark,
It's a bit funny and not intended to be exposed to the end user. The issue was backward compatibility in the metadata macro - if we specified nothing then it was the children of the current page. However if we simply specified an alternate page, it didn't make sense to use the children, just do the report over that page itself. So it's really just an internal way of disambiguating two cases where that parameter is null. It has no value to the end user.
There might be a better way of dealing with it, but I couldn't think of one.
Kelsey
May 29, 2006
Mark Michaelis says:
Hello Kelsey, well, I think to discuss standards we should make this default to...Hello Kelsey,
well, I think to discuss standards we should make this default to @children as pages. Btw: This was also the way in which I (and others) intuitionally used the macro which lead to unexpected results. Therefore I think it might be a good idea to have another solution for the metadata-plugin although I currently don't see a solution which wouldn't break backwards-compatibility.
Mark
May 29, 2006
Kelsey Grant says:
Hi, You're probably right about it not being the most intuitive. The reasoning a...Hi,
You're probably right about it not being the most intuitive. The reasoning at the time was:
It looks to me like going through with this is going to break compatibility so we might just have to suck it up and do it.
May 29, 2006
Mike Cannon-Brookes says:
What a fantastic movement! I love it! :) A few pieces of advice: Personally, ...What a fantastic movement! I love it!
A few pieces of advice:
May 29, 2006
David Peterson says:
Good suggestions. spaces I agree totally, as well as checking for space as an ...Good suggestions.
Anyway, good discussion.
May 29, 2006
Mark Michaelis says:
I like your suggestions, Mike. Especially changing root to page and use scope in...I like your suggestions, Mike. Especially changing root to page and use scope instead of pages. Especially we may then skip the '@' as David suggested.
Concerning display options it also came into my mind that it may be nice to display results as tree if using the scope descendants. Only problem: The following structure:
will break the structure unless we define: If using display-type tree parent pages which do not match the search criteria will not be rendered as links (and perhaps also printed in italics using <em>-notation.).
Or we will require another argument for this to specify if to include non-matching parent-pages or not. This way you could toggle the result above between:
and
What do you think?
May 29, 2006
Mike Cannon-Brookes says:
One display I think that's more clearly what you should display than how you sho...One display I think that's more clearly what you should display than how you should display it.
Perhaps style could cover it? With options like list, table, delimited?
I'm not 100% happy with the idea that space/s in a way is scoped (@all) and specific (FOO,BAR) where page/s is purely specific and scope is scoped. That said, I suppose you can say page=@home or @self or @parent which are algorithmic too. Forget it
May 29, 2006
David Peterson says:
With regards to display, for my \ I used mode (list, flat) for the layout. I use...With regards to display, for my {incoming-links} I used mode (list, flat) for the layout. I used style for the bullet style, if the mode was 'list' (corresponding to the CSS 'list-style' parameter). But whatever...
As for page/s and scope, the difference I see is that @home, @self and @parent all point to a single page resource, whereas the scope options actually open it up to multiple related pages. So I think having space/s map to @self tracks. @all is a bit dodgy I guess, but you can specify multiple spaces, so it's really a shortcut...hmm. Not sure where else you'd put it though - having a space scope seems a bit excessive... Tricky.
May 29, 2006
Kelsey Grant says:
I'm pretty sure that the different macros want to do a number of different thing...I'm pretty sure that the different macros want to do a number of different things on the display end - I know that the metadata one has to pull out the different pieces of metadata, so I think focusing on which pages are retreived and then leaving it to each macro to decide how to deal with the display is the best option?
May 29, 2006
Guy Fraser says:
Yup. As long as there is a consistent and flexible API, any number of macros can...Yup. As long as there is a consistent and flexible API, any number of macros can be developed to use it and those macros can deal with the different ways of displaying info.
That being said, it would be useful if all those macros remained highly consistent in their parameters to make them easier to learn. Associated resource: Macro Parameters Index
May 29, 2006
Kelsey Grant says:
I guess there could be two parts to the API a PageLocator() and a PageRenderer()...I guess there could be two parts to the API - a PageLocator() and a PageRenderer().
May 29, 2006
Mark Michaelis says:
As this thread already extends Confluence's default display limits (and thus it ...As this thread already extends Confluence's default display limits (and thus it is complicated to read this thread) I would suggest to add an introduction to this page which tells that things like sorting and display should be part of another discussion. It perhaps helps to refocus on the main problem which I also have e. g. for the Include Random macro (that's why I joined this discussion as I wanted to add label-support, too).
What do you think?
May 29, 2006
Mark Michaelis says:
Thanks for pointing to this page (and creating it). It's exactly what I have bee...Thanks for pointing to this page (and creating it). It's exactly what I have been searching for since I started working on plugins. Most of the time I tried to stick to arguments provided by Atlassian itself for the macros.
May 29, 2006
Guy Fraser says:
With regards to display format, yes, it would be awesome to have different outpu...With regards to display format, yes, it would be awesome to have different output methods.
An example is shown with the page-info macro (example 5): http://www.adaptavist.com/display/USERGUIDE/page-info+macro
And I know lots of David's plugins offer similar.
The main modes I forsee are:
This seems to give maximum flexibility (and the UL mode allows information to appear in menus in the Builder theme hehe).
May 29, 2006
Guy Fraser says:
It would be useful if we could include the natural sort method added to the \ pl...It would be useful if we could include the natural sort method added to the {pagetree} plugin by Alain Moran - that way, when pages or other items contain numbers, they will be sorted 1,2,...,10 rather than 1,10,2...
It would also be useful to have a reverse option
May 29, 2006
Kelsey Grant says:
Hmmm.... Initially I left the sorting out of the generic code because the metada...Hmmm....
Initially I left the sorting out of the generic code because the metadata plugin sorts on metadata stuff - so it wouldn't transfer to other plugins. But maybe we should put in a default sorting method which can be overriden if you have extra information you want to use.
Max results can only be included if sorting is included - it doesn't make sense to filter by number and then sort after that.
May 29, 2006
Kelsey Grant says:
Hmm, we never got to the original impetus how to exclude content by label? What...Hmm, we never got to the original impetus - how to exclude content by label?
What do you think about the excludeLabels parameter?
What do you think about Mark's proposal: (snip)
In this case the labels are comma separated values which might be prefixed with either "", "+" or "-". If no prefix is given "" is assumed, where:
This way the old syntax of contentbylabel still works, too. I must admit I prefer the second way, as you suggested it, Guy. What do you (and the others) think?
May 29, 2006
Guy Fraser says:
Why restrict it to just labels the same sort of syntax could also be applied to ...Why restrict it to just labels - the same sort of syntax could also be applied to spaces, etc
May 29, 2006
Kelsey Grant says:
Maybe that works quite well then if you wanted to exclude a page you would say s...Maybe that works quite well then - if you wanted to exclude a page you would say something like pages=-NotThisSecretPage
You could do the same for spaces, and probably the scope as well, so if some some weird reason you wanted all pages but not the children of a particular page you could put in 'scope=-children'.
May 30, 2006
Dan Hardiker says:
For a secret page, you would be better to do that through page permissions. How...For a secret page, you would be better to do that through page permissions.
However, if you had a Table of Contents or Appendix that you wanted to leave off the list, then pages=-TableOfContents would be fine, I think
May 29, 2006
Kelsey Grant says:
I think I get this syntax a bit more it's just lists of ANY, ALL, NONE. It's gro...I think I get this syntax a bit more it's just lists of ANY, ALL, NONE. It's growing on me now, especially if you think about applying it a bit more widely to spaces and pages and whatever else.
May 30, 2006
Charles Miller says:
I don't really like the tilde. {{labels=a,b,c,d}} could happily mean (a OR b) AN...I don't really like the tilde. labels=a,b,+c,-d could happily mean (a OR b) AND c AND NOT d. This would be a little more internally consistent, since undecorated, comma-separated space keys are similarly an OR-ing.
May 30, 2006
Kelsey Grant says:
It all depends I think on whether you think in boolean expressions or not. All u...It all depends I think on whether you think in boolean expressions or not. All us developer types can and that's great. However, not everyone is a developer. Syntax aside, Mark's suggestion basically boiled down to saying that a page must have
ALL tags a,b,c ANY of the tags d,e,f and NONE of tags g,h,i.
I do think that's a more natural way of expressing a complex inclusion/exclusion set - note that UIs such as Apple and MS tend not to allow boolean logic builders at all, they tend to make collections of expressions that are either ANDed or ORed together.
Whether or not the ~,+,- syntax is correct is certainly up for debate. I would be keen to see seomthing that includes the words ALL, ANY, NONE because that's a little clearer, but I can't think how to do that just at the moment.
May 29, 2006
Guy Fraser says:
Should the default for the spaces param be @self instead of all spaces? Imagine ...Should the default for the spaces param be @self instead of all spaces? Imagine a huge Confluence installation with hundreds of spaces - most people will only want the scope to initially be the space they use macros in, otherwise they could end up with lots and lots of other info in there that isn't related to their space. I think the defaults should be quite "local" in nature for two main reasons:
May 29, 2006
Kelsey Grant says:
Yeah I'm inclined to agree. Our confluence is pretty big now and the spaces tend...Yeah I'm inclined to agree. Our confluence is pretty big now and the spaces tend to be quite separate so the default should be within the space.
May 29, 2006
Mark Michaelis says:
You'll get my vote, too. Especially about what users expect a macro to do. A mac...You'll get my vote, too. Especially about what users expect a macro to do. A macro collecting information from several spaces is very rare from my experience.
May 29, 2006
Kelsey Grant says:
On the max to be returned,...