Configuring Rich-Text Renderers

JIRA renderers affect the display of a field's content. Renderers were introduced in JIRA 3.4 to allow a greater range of expression within text-based fields such as the Description and Comment fields — see 'Renderable Fields' (below) for a full list.

JIRA currently ships with two renderers: the Default Text Renderer, which displays plain text; and the Atlassian Wiki Renderer (utilising the Confluence wiki engine), which displays rich text (HTML). See 'Renderer Types' (below) for a full list.

Renderers are configured on a per field level, allowing a flexible combination of plain text and rich text fields. To configure a renderer for a particular field, see 'Configuring field behaviour'. Note that JIRA Enterprise Edition also gives you the flexibility to configure fields differently per project and per issue type.

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 Renderers' (below).

Please read 'Implications for JIRA operations' (below) before configuring renderers

Potentially any field within JIRA can be a renderable field, but this only really makes sense in the case of text-based fields (since a date field would look nonsensical in wiki-markup). The following table shows the JIRA fields that are renderable out-of-the-box:

JIRA version 3.4 and later ships with two renderers, the Atlassian Wiki Renderer and the Default Text Renderer.

Default Text Renderer

The Default Text Renderer, as the name implies, is the default renderer for JIRA. Out of the box, JIRA is configured to use the text renderer for all renderable fields. The 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.

Atlassian Wiki Renderer

The Atlassian Wiki 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 organise your document.
• Bullets, numbering, tables and quotations.
• Images, screenshots, and emoticons.
• Powerful mini-applications using macros.

A full notation guide can be found here.

Atlassian Wiki Renderer Macro Support

The Atlassian Wiki 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.

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 Atlassian Wiki 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 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 the user with any warnings.

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 the user with a warning so that you can be 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.

This is best illustrated with an example. Let's say you have project 'A' which is configured to use the Atlassian Wiki Renderer for the Description field. Let's say you also have a project 'B' which is configured to use the Default Text Renderer for the Description field. You have three issues that exist in project 'A' and you want to perform a bulk move of the three issues to project 'B'. If none of the issues in project 'A' have a value set for the Description field they will be moved and you will not notice any changes since there is no value to render. If one of the issues has the following value in its Description:

                    {color:green}green text{color}

                    *this is a test issue*
                

You would be presented with this screen in the bulk move to alert you that you are changing renderers as a result of the move:

The move operation does nothing to affect the data itself so after the move the wiki markup will display through the Default Text Renderer. In our example the before and after look like this:

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 Atlassian Wiki Renderer for both of the fields. Lets say you also have a project 'B' which is configured to use the Default Text Renderer for the 'Custom text area' field and the Atlassian Wiki 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:

You will notice that for the 'Custom text area' field you are presented with an warning that the field has inconsistent renderer types and that it is not available to be selected for bulk edit. This is because the fields do not share the same renderer in the two issues. You will also notice that for the 'Custom text field' field you are presented with an editable input that allows for wiki preview. This is because the field shares the same renderer in the two issues.

Email Notifications

JIRA allows for extensive configuration in relation to email notifications. JIRA can be 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 Atlassian Wiki 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 Atlassian Wiki 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 Atlassian Wiki 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.

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 Atlassian Wiki 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:

                        http://localhost:8080/browse/AAA-1?decorator=none&view=rss
                    

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

                        http://localhost:8080/browse/AAA-1?decorator=none&view=rss&rssMode=raw
                    

Other

This section describes other issues to be aware of in relation to the renderers.

• When editing a renderable custom field's default value, even if it is only ever configured to use the Atlassian Wiki Renderer you will not be presented with the 'Edit' and 'Preview' tabs. Unfortunately it is not possible, in that context, to tell which renderer should be used for editing. This said, 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 Atlassian Wiki Renderer.

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 'Configuring field behaviour.

Enabling a Renderer Plugin

Renderers within JIRA are implemented as JIRA plugins. The macros that the Atlassian wiki renderer uses are also implemented as JIRA plugins. For general information on plugins please see this guide.

Renderer Plugins Configuration

Renderers and their dependant components, except for the default text renderer, can be enabled/disabled via the plugin administration menus. If you navigate, as an administrator, to 'Administration' > 'Plugins' and then click on the option 'Renderer Plugin' you will see the following screen.

From this screen you will see all the configured Renderers within JIRA. At the moment only two renderers exist but if more are created you will see there configuration here. If you click on the 'Disable Module' link for the 'Wiki Style Renderer' this will deactivate the renderer for the entire instance of JIRA.

Any fields that are still setup to use the disabled renderer will fall back to the default text renderer and when you attempt to edit the field a warning message will alert 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 fields renderer. To enable the renderer just click the 'Enable Module' link. Enabling/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 effecting any data.

Macro Plugins Configuration — Atlassian Wiki Renderer

The macros used by the Atlassian wiki renderer can be enabled/disabled via the plugin administration menus. If you navigate, as an administrator, to 'Administration' > 'Plugins' and then click on the option 'Wiki Renderer Macros Plugin' you will see 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, likewise a macro must be enabled for it to 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 this guide.