Issue link renderer

Available:

JIRA 5.0 and later.

The issue link renderer plugin module allows you to add new custom renderers for issue links to JIRA.

When a Remote Issue Link is rendered, if there is no custom renderer for the application type of the link, a default renderer is used.

For background information, see the overview of Guide - JIRA Remote Issue Links. If you are interested in creating Remote Issue Links, take a look at the REST API Guide.

Example of an Issue Link Renderer Definition

Here is an example of issue-link-renderer defined in atlassian-plugin.xml:

1
2
<issue-link-renderer key="customIssueLinkRenderer" application-type="com.mycompany" class="com.atlassian.jira.plugin.viewissue.CustomIssueLinkRenderer">
    <resource name="view" type="velocity" location="viewissue/customissuelink.vm"/>
</issue-link-renderer>

Issue Link Renderer Configuration

The root element for the issue link renderer plugin module is issue-link-renderer. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The Java class of the issue link renderer plugin module. Classes must implement com.atlassian.jira.plugin.issuelink.IssueLinkRenderer. There is a com.atlassian.jira.plugin.issuelink.AbstractIssueLinkRenderer defined which issue link renderers can extend to minimise the number of methods that are required to be implemented.
key	The identifier of the plugin module. This key must be unique in the plugin where it is defined. Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the complete module key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred.I.e. the identifier of the custom field type module.
i18n-name-key	The localisation key for the human-readable name of the plugin module.
name	The human-readable name of the plugin module.
application-type	The application type that the issue link renderer will handle. You can only have one custom renderer map to a specific application-type.

*class, key and application-type attributes are required.

Elements

Name	Description
resource	Attribute: type. Type of the resource. At the moment only "velocity" is supported.
resource	Attribute: name. Name of the resource. Use either "initial-view" or "final-view" to specify a resource for the initial viewing and the async loading respectively.

resource

Attribute: type.

Type of the resource. At the moment only "velocity" is supported.

resource

Attribute: name.

Name of the resource. Use either "initial-view" or "final-view" to specify a resource for the initial viewing and the async loading respectively.

Issue Link Renderer

Custom issue link renderers may extend com.atlassian.jira.plugin.issuelink.AbstractIssueLinkRenderer to minimise the number of methods required to be implemented.

1
2
/**
 * Defines an issue link renderer to customise how issue links appear.
 *
 * @since v5.0
 */
public interface IssueLinkRenderer
{
    /**
     * Returns the context used by the template to render the initial HTML. Implementers of this method
     * should not make remote calls, use {@link #getFinalContext(RemoteIssueLink, Map)} for that purpose.
     *
     * The resulting HTML will be injected as follows:
     * {@code
     * <dl class="links-list">
     *    <dt>Relationship Text</dt>
     *    <!-- ... Other Issue Links ... -->
     *    <dd id="uniqueHtmlElementId" class="remote-link">
     *        <div class="link-content">
     *            <!-- ISSUE LINK RENDERER CONTENT HERE -->
     *        </div>
     *
     *        <div class="delete-link" id="delete_uniqueHtmlElementId">
     *            <a class="icon icon-delete" title="Delete Link" id="delete-link_uniqueHtmlElementId" href="delete_remote_issue_link_url"><span>Delete Link</span></a>
     *        </div>
     *     </dd>
     *    <!-- ... Other Issue Links ... -->
     * </dl>
     * }
     *
     * @param remoteIssueLink remote issue link
     * @param context the contextual information that can be used during
     *  rendering.
     * @return context used to render the initial HTML.
     */
    Map<String, Object> getInitialContext(RemoteIssueLink remoteIssueLink, Map<String, Object> context);

    /**
     * Returns the context used to render the final HTML. This method will only be called if
     * {@link #requiresAsyncLoading(RemoteIssueLink)} returns <tt>true</tt>.
     *
     * The resulting HTML will be injected as follows:
     * {@code
     * <dl class="links-list">
     *    <dt>Relationship Text</dt>
     *    <!-- ... Other Issue Links ... -->
     *    <dd id="uniqueHtmlElementId" class="remote-link">
     *        <div class="link-content">
     *            <!-- ISSUE LINK RENDERER CONTENT HERE -->
     *        </div>
     *
     *        <div class="delete-link" id="delete_uniqueHtmlElementId">
     *            <a class="icon icon-delete" title="Delete Link" id="delete-link_uniqueHtmlElementId" href="delete_remote_issue_link_url"><span>Delete Link</span></a>
     *        </div>
     *     </dd>
     *    <!-- ... Other Issue Links ... -->
     * </dl>
     * }
     *
     * @param remoteIssueLink remote issue link
     * @param context the contextual information that can be used during rendering.
     * @return velocity context used to render the final HTML
     */
    Map<String, Object> getFinalContext(RemoteIssueLink remoteIssueLink, Map<String, Object> context);

    /**
     * Returns <tt>true</tt> if an AJAX call is required to retrieve the final HTML. If <tt>true</tt> is returned,
     * then {@link #getFinalContext(com.atlassian.jira.issue.link.RemoteIssueLink, java.util.Map)} will be
     * called to retrieve the final HTML for the issue link.
     *
     * @param remoteIssueLink remote issue link
     * @return <tt>true</tt> if an AJAX call is required to retrieve the final HTML
     */
    boolean requiresAsyncLoading(RemoteIssueLink remoteIssueLink);

    /**
     * Returns <tt>true</tt> if the remote issue link should be displayed.
     *
     * @param remoteIssueLink remote issue link
     * @return <tt>true</tt> if the remote issue link should be displayed
     */
    boolean shouldDisplay(RemoteIssueLink remoteIssueLink);
}