"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 queries the ReleaseNotes XClasses by name, so it runs from any page of the wiki; those classes are described in Release Note Structure.
Every parameter but contextVariable, limit and offset 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. Release Notes Application 2.6+ A value starting with = matches exactly, so that a value holding a % or a _ of its own is not read as a pattern. Release Notes Application 2.4+ The >= and <= prefixes include the boundary value. The results come back ordered by importance, most important first, Release Notes Application 2.6+ then by page reference, so that the same query asked twice brings back the same changes in the same order.
Release Notes Application 2.6+ At most limit changes are collected, starting at offset, so that a filter matching thousands of changes cannot turn one page view into thousands of document loads. Whether the query had more changes to return is published beside them, in the variable named after contextVariable with HasMore appended.
Usage
{{getChanges contextVariable="changeDocs" products="XWiki" versions="12.%" audience="user" categories="%" importance="High,Medium" containsScreenshots="true" limit="20" offset="0"/}}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. Release Notes Application 2.6+ A comparison prefix keeps a range, whose bound is compared in version order: >=9.0 also matches 10.0 |
| 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 |
| limit | No | A number | 100 | Release Notes Application 2.6+ How many changes to collect at most; a value below 1 falls back to the default |
| offset | No | A number | 0 | Release Notes Application 2.6+ How many matching changes to skip before collecting, which is how the changes past the ones already displayed are reached; a value below 0 falls back to the default |
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 from a version on, for every product
{{getChanges products="%" versions=">=14.10" importance="High" contextVariable="changeDocs"/}}Example 4: One page of changes at a time
{{getChanges products="XWiki" limit="20" offset="20" contextVariable="changeDocs"/}}
{{velocity}}
#if ($changeDocsHasMore)
There are more changes to display.
#end
{{/velocity}}FAQ
Why does my query come back empty?
products defaults to XWiki, not to every product; pass products="%" to match them all.
Why does my query stop at one hundred changes?
Release Notes Application 2.6+ That is the default limit; raise it, or reach the changes past it with offset and the HasMore variable.
