JIRA
Explanation
The JIRA integration is assembled out of Components, and every step of the jira Macro's pipeline is one of them. The source parameter selects the Component that turns the Macro content into a set of issues, the style parameter selects the one that turns those issues into rendered blocks, and each field is rendered by the Component registered for its id or, failing that, for its type. Extending the Macro therefore means contributing a Component, never editing a switch: registering one under a new hint is enough to make a new source, a new style or a new field renderer available to page authors.
Two further extension points sit outside that pipeline. A transformation Component runs after any of the JIRA Macros has produced its blocks and may rewrite them, which is the way to post-process a rendering without reimplementing the Macro. An authenticator Component defines how requests to a JIRA instance are signed, which is the way to support a scheme other than the Basic authentication shipped with the extension. All five roles, with the hints they are looked up under, are listed in JIRA Macro Extension Points.
Components can be written in Java and packaged as a JAR, or written in a wiki page as a Wiki Component, which is the quickest route for a field renderer and needs no build; Add a JIRA Field Displayer as a Wiki Component builds one step by step. An authenticator is the exception and needs a JAR, as Extend JIRA Authentication shows.
When the goal is not to change how issues are displayed but to reach JIRA from your own code, the JIRA Scripting API hands you Atlassian's own Java client instead, already pointed at a configured instance.
FAQ
Do I need to build a JAR to extend the JIRA Macro?
Not for a field renderer or another displayer: a Wiki Component in a wiki page is enough. An authenticator is a Java Component, because its interfaces are not exposed to scripts.
Will my Component work with the JIRA Macro outside XWiki?
Yes, as long as it depends on the JIRA Macro modules only. The jira Macro is deliberately usable by plain XWiki Rendering users, so anything needing platform APIs belongs in a separate module.
What happens if my transformation throws?
The failure is logged and the Macro renders its untransformed blocks, so a broken transformation degrades the output instead of breaking the page.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
