I've been working on making some of my existing code more generic. I've used similar suggestions to those listed at the Unified Page Searching Tags page, with a few modifications.
This has been implemented in the Confluence Filtering Library.
Filtering
General Syntax
Below is a rough grammar for the general parameter syntax. It allows for optional, required, excluded and grouped values.
criteria := criterion ((',' | ';') criterion)*
criterion := group | ('+' | '-')? value
group := '(' criteria ')'
value := quotedvalue? [^,;"+-] value?
quotedvalue := '"' [^"]* '"'
Here are some examples of the syntax, not associated with any particular real-life property:
| Example | Description |
|---|---|
| one, two | Matches either 'one' or 'two'. |
| one, +two, -three | Requires 'two', excludes 'three' and ignores 'one'. |
| (one, two) +three | Requries either 'one' or 'two' as well as requiring 'three'. |
| foo-bar | Requires 'foo' and excludes 'bar'. |
| "foo-bar" | Requires 'foo-bar'. |
| -"foo-bar" | Excludes 'foo-bar'. |
Specific Parameters
| Parameter | Values | Example | Default | Description |
|---|---|---|---|---|
| label(s) | any label | my:label, -test | all content | Filters based on whether the specified labels is present on the content. |
| scope | SPACEKEY:Page>scope | A Page, KEY:My Page>descendents, Another Page>ancestors | all content | Filters based on what pages and their scope is specified. |
| space(s) | SPACEKEY, @all, @global, @personal, @favorite | @favorite, -AKEY | @self | Filters based on the specified space key. |
| type | page, news, comment, spacedescription, ? | page, -news | all types | The type of content to display. |
Sorting
 | TODO Add documentation about sorting. |
Labels
(None)