Reference

Five Component roles make up the extensible surface of the JIRA Macros. Registering an implementation under the right hint is all that is needed for a page author to reach it through a Macro parameter.

The first three roles live in the org.xwiki.contrib.jira.macro package of the JIRA Macro module, the last two in org.xwiki.contrib.jira.macro and org.xwiki.contrib.jira.config respectively. Issues are handled as JDOM Element instances, because the jira Macro reads JIRA's XML search view rather than a typed model.

Adding a Source

@Role
public interface JIRADataSource
{
    Collection<Element> getData(String macroContent, JIRAMacroParameters parameters)
        throws MacroExecutionException, JIRABadRequestException;
}

Throw JIRABadRequestException when JIRA itself rejected the request, so that the Macro can report JIRA's own messages instead of a generic failure, and MacroExecutionException for anything else.

Adding a Style

@Role
public interface JIRADisplayer
{
    List<Block> display(Collection<Element> issues, JIRAMacroParameters parameters);

    @Unstable
    default List<Block> display(Collection<Element> issues, JIRAMacroParameters parameters,
        MacroTransformationContext context)
    {
        return display(issues, parameters);
    }
}

Implement the three-argument method when the rendering depends on the context, for instance to render differently inline; its default implementation delegates to the two-argument one.

Adding a Field Renderer

@Role
public interface JIRAFieldDisplayer
{
    List<Block> displayField(JIRAField field, Element issue, JIRAMacroParameters parameters);
}

Register the Component under the id of the field to render one particular field, or under type/<field type> to render every field declaring that type. Overriding a field that already has a renderer of its own, such as status, means registering a Component override under that field id.

Transforming the Result of a Macro

Transformations apply to the jira, jiraCount and chart Macros alike. Components are looked up by the parameter type P, so a transformation applies to the Macros whose parameter class it names.

@Role
public interface JIRAMacroTransformation<P>
{
    default List<Block> transform(List<Block> blocks, P parameters,
        MacroTransformationContext context, JIRAServer jiraServer, String macroName)
    {
        return blocks;
    }
}

A transformation that fails is logged and skipped, and the Macro renders its untransformed blocks.

Passing Configuration to a Component

The parameters Macro parameter carries a comma-separated list of name=value pairs, which every source, displayer and field renderer receives through its JIRAMacroParameters argument. Prefix the names so that they cannot collide:

FAQ

Can these Components be written in a wiki page?

Yes, as Wiki Components, which is the usual route for a field renderer; see Add a JIRA Field Displayer as a Wiki Component.

May my Component depend on XWiki Platform?

Not if it is packaged with the JIRA Macro modules, which must stay usable by plain XWiki Rendering users. Put anything needing platform APIs in a separate module.

How do I make a new style available to page authors?

Register the JIRADisplayer under the hint you want; that hint is immediately accepted as a value of the style Macro parameter.

Why is my transformation never called?

Because it is parameterized by a different type than the Macro's own parameter class; the lookup matches on that type.

Related

• JIRA Issue Fields
• "jira" Macro
• Writing Components