Configuring Renderers

Overview

JIRA renderers affect how a JIRA field's content is either displayed to the user (for text fields) or how a user enters field data (for multi-select fields), thereby enabling you to choose a style which best suits your organisation and your users.

JIRA currently ships with the following renderers:

  • For text fields:
    • The Default Text Renderer, which displays plain text; and
    • The Wiki Style Renderer (utilising the Confluence wiki engine), which displays rich text (HTML).
      (info) To see how a 'Wiki Style Renderer' field will look when it is displayed to a user, please see Editing Rich-Text Fields.
  • For multi-select fields:
    • The Autocomplete Renderer, which allows the user to start typing text which is then 'autocompleted', or to select from a dropdown list of options; and
    • The Select List Renderer, which simply provides a dropdown list of options.
      (info) For custom fields of type Multi Select, only the Select List Renderer is available. Furthermore, when modifying a field configuration, you will not be able to configure a Multi Select custom field's renderer.

Renderers are configured on a per field basis. To configure a renderer for a particular field, see Specifying Field Behavior. Note that you can configure the same field differently for different projects and issue types — see Associating Field Behavior with Issue Types.

Renderers are implemented as JIRA plugins, meaning that any renderer can be easily added to or removed from use within JIRA. This includes any custom renderers that may be developed. For details see configuring.

Please read Implications for JIRA operations below before configuring renderers.

Renderers affect the rendering (view) of a field's value. This means that you can migrate to a different renderer without affecting your issue data; only the view will be changed. It also means that if you do not like the way your issues look using the new renderer, you can simply switch back with no impact on your issue data.

On this page:

Renderable Fields

Potentially any field within JIRA can be a renderable field, but this only really makes sense in the case of text-based fields (for the Default Text Renderer and the Wiki Style Renderer) and multi-select fields (for the Autocomplete Renderer and the Select List Rendered). The following table shows the JIRA fields that are renderable out-of-the-box:

Field

Available Renderers

Description

Wiki Style Renderer (default), Default Text Renderer.

Comment

Wiki Style Renderer (default), Default Text Renderer.

Environment

Wiki Style Renderer (default), Default Text Renderer.

Component

Autocomplete Renderer (default), Select List Renderer.

Affects Version

Autocomplete Renderer (default), Select List Renderer.

Fix Version

Autocomplete Renderer (default), Select List Renderer.

Custom field of type "Free Text Field (unlimited text)"

Wiki Style Renderer, Default Text Renderer.

Custom field of type "Text Field"

Wiki Style Renderer, Default Text Renderer.

Custom field of type "Multi Select"

Select List Renderer.

Custom field of type "Version Picker"

Autocomplete Renderer (default), Select List Renderer.

Renderer Types

JIRA ships with the following renderers:

Default Text Renderer

The Default Text Renderer renders a field's content as plain text, with the following additional auto-linking feature: if the text contains text that resolves to a JIRA issue key then an HTML link will be generated that points to that issue. Below is a sample of how some description text looks when rendered through the Default Text Renderer.

It is not possible to disable the Default Text Renderer plugin as it is required for the system to function properly. If a text field is setup to use a renderer that is later disabled, the field will revert to using the Default Text Renderer.

Wiki Style Renderer

The Wiki Style Renderer allows a user to enter wiki markup to produce html content, as described in 'Editing Rich-Text Fields' in the JIRA User's Guide.

This renderer uses the Confluence wiki renderer engine and therefore uses the Confluence wiki notation. The Confluence notation is easy to learn and allows for:

  • Italic, bold and underlined text.
  • Multiple levels of headings to organize your document.
  • Bullets, numbering, tables and quotations.
  • Images, screenshots, and emoticons.
  • Powerful mini-applications using macros.
    A full notation guide can be found here.

The Wiki Style Renderer can only be used with JDK 1.4 and up. The renderer will not run on JDK 1.3.

Please note that some fields may require further field behavior configurations to be enabled — see Choosing a Renderer.

Wiki Style Renderer Macro Support

The Wiki Style Renderer supports pluggable macros in the same way that Confluence does. Macros provide an easy and powerful extension point to the wiki markup language. JIRA ships with a number of macros as described in the JIRA User's Guide.

JIRA and Confluence can share macros, but keep in mind that many Confluence macros are very specific to the Confluence application and will therefore not run within JIRA. For example, the Children macro in Confluence shows links to all of a Page's child pages. JIRA has no concept of 'page' and therefore this macro will not function in JIRA.

Autocomplete and Select List Renderers

The Autocomplete and Select List Renderers let you start typing text, which is then autocompleted, or to select from a dropdown list of options.

Implications for JIRA operations

The fact that JIRA allows you to configure different renderers across different projects/issue types for the same field has implications for bulk operations. Also, since the Wiki Style Renderer inherently creates HTML as its end product, there are implications as to how this will behave when issue data is viewed outside JIRA's web front-end.

Bulk Move

When performing a bulk move operation you can either move issues to an environment (project/issue type) where the renderer types for the fields are the same or where they will be different.

If the renderer types are the same

If the renderer types for where you are moving to are the same then you will not notice any changes to the way the issues data is displayed once the move has occurred and the move operation will not prompt you with any warnings.

If the renderer types are different

When bulk moving issues to an environment (project/issue type) that has a different renderer type defined for one of the fields being affected by the move, if any of the issues have a non empty value associated with the field, the move operation will present you with a warning so that you are aware of the change. The warning does not affect the move operation in any way but it is there to alert you to the fact that the moved issues' affected fields may look different in their new project/issue type.

Bulk Edit

When performing a bulk edit operation the only renderable fields you may be able to bulk edit are instances of the Text Field, and Free Text Field (unlimited text) custom fields. The bulk edit operation does not allow you to bulk edit the description, environment, or comment fields.

You will only be allowed to bulk edit a renderable field if all the issues selected for edit use the same renderer type. If the renderer type differs for any of the selected issues you will be presented with an error message.

This is best illustrated with an example. Let's say you have two global custom fields, 'Custom text area' and 'Custom text field', whose types are as their names imply. Let's say you have project 'A' which is configured to use the Wiki Style Renderer for both of the fields. Let's say you also have a project 'B' which is configured to use the Default Text Renderer for the 'Custom text area' field and the Wiki Style Renderer for the 'Custom text field'. Let's also say that you have one issue in each project. If you were to perform a bulk edit operation on the two issues in these projects you will be presented with the screenshot below:

Email Notifications

JIRA allows for extensive configuration in relation to email notifications. JIRA can send out two types of emails, HTML and text (see Email Formatting).

HTML Emails

When using the Atlassian Wiki Renderer, the rendered content (i.e. exactly what you see on the 'View Issue' page) will be sent out in the emails. This will create emails which are as rich as the content makes it. If using the Wiki Style Renderer, this is the preferred type of email since it is a real representation of the wiki markup.

Text Emails

When using the Atlassian Wiki Renderer, the actual wiki markup (unrendered) will be displayed in text emails for fields that use the Wiki Style Renderer. This is obviously less readable than the rendered version of the markup, but because the markup's syntax is quite simple the text does remain easy to read.

Excel View

JIRA allows the Issue Navigator view to be exported to an Excel spreadsheet. If any of the fields being exported to Excel are using the Wiki Style Renderer, the value exported to the cell in Excel will be the original wiki markup. Attempting to display complex HTML within a cell in Excel adds rows and columns that make using the data for formulas very difficult.

The unrendered wiki markup will be shown in Excel cells for fields that use the Wiki Style Renderer.

RSS/XML View

JIRA allows the Issue Navigator view to be exported to RSS/XML. If a field is using the Default Text Renderer its values will be exported in a CDATA section within the generated XML. If a field is using the Wiki Style Renderer, its rendered value will be XML escaped and included in the generated XML. If the XML view is being used as an RSS feed, most RSS readers will render the generated HTML so you will see the rich content within your RSS reader.

If you would like to have this view feed out the raw values (unrendered) then you can send an additional request parameter 'rssMode=raw'. If the original link looks like this:

Then the URL to have the raw values placed inside a CDATA should look like this:

Editing a Renderable Custom Field's Default Value

When editing a renderable custom field's default value, even if it is only ever configured to use the Wiki Style Renderer you will not be presented with the Edit and Preview options. Unfortunately, in this context it is not possible to tell which renderer should be used for editing. However, if you enter a default value using wiki markup, then this will render correctly in environments (project/issue type) where the field has been configured to use the Wiki Style Renderer.

Configuring Renderers

Applying a Renderer to a Field

To enable a renderer for a particular field, edit the Field Configuration and choose the appropriate renderer for the field. For details, see Specifying Field Behavior.

Enabling a Renderer Plugin

Renderers within JIRA are implemented as JIRA plugins. The macros that the Wiki Style Renderer uses are also implemented as JIRA plugins. For general information on plugins please see the JIRA Plugin Guide.

Note that plugins are configured at a site-wide level — it is not possible to configure plugins at a project/issue type level.

Configuring a Renderer Plugin

Renderers and their dependant components, except for the Default Text Renderer, can be enabled/disabled as follows.

  1. Choose > Add-ons. The 'Find add-ons' screen shows add-ons available via the Atlassian Marketplace. Choose Manage Add-ons to view the plugins currently installed on your JIRA site.
  2. Select Manage Add-ons and then search for 'renderer', filtering for System Add-ons, as shown here:

This screen displays all the configured renderers within JIRA.

  • Click the Disable button to deactivate the renderer for the entire instance of JIRA.

Any fields still set up to use a disabled renderer will fall back to the default text renderer. When you attempt to edit the field, a warning message alerts you to the fact that you are configured to use a renderer that is not available.

When a renderer is disabled it will not be available for selection when changing a field's renderer. To enable the renderer, click the Enable button. Enabling or disabling a renderer has no effect on the renderer settings in the field configurations, so it is possible to disable and then re-enable a renderer without affecting any data.

Configuring Macro Plugins for the Wiki Style Renderer

The macros used by the Wiki Style Renderer can be enabled/disabled as follows.

  1. Choose > Add-ons. The 'Find add-ons' screen shows add-ons available via the Atlassian Marketplace. Choose Manage Add-ons to view the plugins currently installed on your JIRA site.
  2. Select Manage Add-ons and then search for 'renderer', filtering for System Add-ons.
  3. Expand the Wiki Renderer Macros Plugin to display the following screen.

From this screen you will see all the configured macros within JIRA. If a macro is disabled then it will not be available to the wiki renderer. If you deploy any additional macros that you wish to use, they must be enabled here to be available to the wiki renderer. For more information on writing plugins please see the documentation on Writing Macros.

Was this helpful?

Thanks for your feedback!

2 Archived comments

  1. User avatar

    Sandro Lehmann

    Why is the Autocomplete Renderer not available for custom multi select fields?

    10 Jul 2014
  2. User avatar

    William Crighton [CCC]

    For any who, like me, happened across this while looking for what the &%^$(**& renderer type options are - here they are along with the code I used to obtain them:

     

    • atlassian-wiki-renderer // admin.renderer.plugin.wiki.renderer.desc
    • jira-text-renderer // admin.renderer.plugin.text.renderer.desc


     

    05 Aug 2014
Powered by Confluence and Scroll Viewport