Tutorial

This tutorial builds a field renderer for the jira Macro entirely in a wiki page, with no JAR to compile. It contributes a new field type named lien, which displays the value JIRA returned as a link labelled "Lien", and it reuses the built-in renderer to obtain that value. Writing it needs the Wiki Component Module and programming rights on the page holding it.

1. Create a page named XWiki.LienJIRAFieldDisplayer, whose name is free, and edit its objects.
2. Add an XWiki.ComponentClass xobject, set its "Component Role Type" to org.xwiki.contrib.jira.macro.JIRAFieldDisplayer, its "Component Role Hint" to type/lien, and its "Component Scope" to "Current Wiki".

   

   The hint has the form type/<field type> because the renderer is registered for a field type rather than for one field id.

3. Add an XWiki.ComponentDependencyClass xobject, set its "Dependency Role Type" to org.xwiki.contrib.jira.macro.JIRAFieldDisplayer, its "Dependency Role Hint" to default, and its "Binding name" to defaultDisplayer.

   

   This makes the built-in renderer available to the code of the next step, which uses it to read the raw field value instead of parsing the issue itself.

4. Add an XWiki.ComponentMethodClass xobject, set its "Method name" to displayField, and put this code in its "Method body code".

   {{groovy}}
   import org.xwiki.rendering.block.*
   import org.xwiki.rendering.listener.reference.*
   
   def field = xcontext.method.input.get(0)
   def issue = xcontext.method.input.get(1)
   def parameters = xcontext.method.input.get(2)
   String text = xcontext.method.defaultDisplayer.displayField(field, issue, parameters).get(0).getProtectedString()
   
   def reference = new ResourceReference(text, ResourceType.URL)
   def labelBlocks = [new WordBlock("Lien")]
   xcontext.method.output.value = [new LinkBlock(labelBlocks, reference, true)]
   {{/groovy}}

   

   The three arguments of displayField arrive in xcontext.method.input, the dependency bound in the previous step is reached as xcontext.method.defaultDisplayer, and the blocks to render are returned through xcontext.method.output.value.

5. Save the page, which registers the Component immediately.
6. Edit any page and call the jira Macro with a field declaring the new type, as in fields="key,summary,link!lien". The renderer turns the value of the field into a URL, so pick a field holding one, such as the standard link field.
7. Display the page. The field is rendered as a link labelled "Lien".

   

FAQ

Can I override a field that already has a renderer?

Yes, but not with a field type: register the Component under the field id itself, as a Component override, since a renderer found by id wins over one found by type.

Why does the renderer apply to fields I did not expect?

Because a renderer registered under type/lien renders every field declaring that type, not one particular field.

Can I write a data source or a style this way too?

Yes. Any of the roles listed in JIRA Macro Extension Points can be implemented as a Wiki Component.

Do I need to restart the wiki?

No. Saving the page registers the Component, and saving it again re-registers it.

Related

• JIRA Macro Extension Points
• JIRA Issue Fields
• Writing Components