"getChanges" Macro
Reference
Description
Runs a query over the release notes of the wiki and puts the change pages it matches into a Velocity variable. It renders nothing itself, which is what lets a caller filter the list before handing it to the displayChanges macro.
It resolves the XClasses it queries from the top-level space of the page it runs on, so it only works on a page inside the space the application is installed in; those classes are described in Release Note Structure.
Every parameter but contextVariable takes a comma-separated list, and the values of that list are combined with a logical OR. Inside a value, % matches any sequence of characters and _ any single one. A value may also start with > or <, which compares instead of matching and is how a version range is expressed. The results come back ordered by importance, most important first.
Usage
{{getChanges contextVariable="changeDocs" products="XWiki" versions="12.%" audience="user" categories="%" importance="High,Medium" containsScreenshots="true"/}}Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| contextVariable | Yes | A Velocity variable name | N/A | The variable that will hold the list of matching change page references |
| products | No | Product names | XWiki | Products to keep. The default is the single product XWiki, not every product: pass % to match them all |
| versions | No | Versions | % | Versions to keep |
| audience | No | user, administrator, developer | the three of them | Audiences to keep; the case does not matter |
| categories | No | Category names | % | Categories to keep |
| importance | No | High, Medium, Low, or the stored 2, 1, 0 | 0,1,2 | Importance levels to keep; the case does not matter |
| containsScreenshots | No | true, false or empty | (empty) | true keeps only the changes that have a screenshot, false only those that have none, and an empty value keeps both |
Examples
Example 1: List the matching changes yourself
{{getChanges products="XWiki" versions="12.%" audience="user" contextVariable="changeDocs"/}}
{{velocity}}
#foreach ($changeDoc in $changeDocs)
* $changeDoc
#end
{{/velocity}}Example 2: Query, then render with a displayer
{{getChanges products="XWiki" versions="12.%" containsScreenshots="true" contextVariable="changeDocs"/}}
{{displayChanges displayer="grid" contextVariable="changeDocs"/}}Example 3: Everything released after a version, for every product
{{getChanges products="%" versions=">14.10" importance="High" contextVariable="changeDocs"/}}FAQ
Why does my query come back empty?
products defaults to XWiki, not to every product; pass products="%" to match them all.
Why does the macro find nothing outside the application?
It resolves its XClasses from the top-level space of the page it runs on, so it has to run on a page inside the space the application is installed in.
