Steps

A displayer is one wiki page rendering a list of changes; the four bundled ones are described in Change Displayers.

1. Create a page named ChangeDisplayer<Name> in the ReleaseNotes.Code.Change space, for example ChangeDisplayerCards.

   

2. Include the shared Velocity macros and loop over the $changeItems binding, reading each change from its ChangeClass object, escaping its title and displaying its summary through the change document.

   {{include reference="ReleaseNotes.Code.Change.ChangeDisplayerVelocityMacros"/}}
   
   {{velocity}}
   #foreach ($item in $changeItems)
   #set ($changeDoc = $xwiki.getDocument($item))
   #set ($changeObject = $changeDoc.getObject('ReleaseNotes.Code.Change.ChangeClass'))
   #set ($title = $services.rendering.escape("$!changeObject.getValue('title')", 'xwiki/2.1'))
   #generateDisplayEditLink($displayEditLink, $changeDoc)
   {{info}}
   **$title**${displayEditLinkMarkup}
   
   $changeDoc.display('summary', 'view', $changeObject)
   {{/info}}
   
   #end
   {{/velocity}}

3. Pass the lowercase name to the displayer parameter, here displayer="cards", from a report or from the displayChanges macro.
4. The changes are rendered by your displayer.

   

FAQ

Which bindings does a displayer receive?

$changeItems, the list of change page references, plus $displayEditLink and $columns as they were passed to displayChanges.

How does the displayer parameter map to the page name?

displayChanges includes ReleaseNotes.Code.Change.ChangeDisplayer followed by the displayer value with its first letter capitalised.

How do I render a change's screenshots and videos?

Call displayScreenshots from the shared Velocity macros page, passing the change object, whether to use a gallery, and whether every change must show a medium. Release Notes Application 2.5+ That last flag holds the output to a single medium: the screenshots when the change has any, otherwise its first video, otherwise a placeholder picture.

Why escape the title and display the summary through the change document?

Both fields hold text written by whoever added the change: an unescaped title lets that text close the markup around it, and a summary rendered by the displayer is evaluated with the rights of the page listing the change instead of those of the change's own page.

Related

• Change Displayers
• displayChanges macro