Installing JEditor is as simple as installing any Jira add-on/app. To install JEditor do the following:
- Go to Jira administration > Find new add-ons
- Search the marketplace for JEditor
- Click the Free Trial button to get an evaluation license and install the add-on.
Sometimes you may be asked by our support to install a JEditor build manually. To do so navigate to Jira administration > Manage add-ons and click the Upload add-on link.
JEditor can be enabled on a per-field basis for any multi-line text field (like description or comment) including custom fields. After installing JEditor you won't see any immediate changes in your Jira fields.
Do the following to enable JEditor for a particular field:
- Navigate to Jira administration > Issues
- Select Fields > Field Configurations to view all your field configurations
- Locate the field configuration of interest and click the Configure link to open the View Field Configuration page, which lists all system and custom fields in your Jira installation for that field configuration
- Click the Renderers link for the field you want to change. This will take you to a page where you will have the option to select a renderer from all configured and available renderers
- This page will warn you if there are issues that will be affected by the change. If no issues will be affected then the warning does not show. From this page, choose the JEditor Renderer and click Update
Existing fields that contain wiki markup (created using wiki renderer or Jira RTE) are properly rendered by JEditor.
You can evaluate JEditor in your testing environment or in your production Jira.
If you want to evaluate JEditor in your production Jira - it's safe to do so. Create a test project with a separate field configuration and enable JEditor only for the fields in that field configuration.
JEditor comes pre-configured with some default Templates, Styles, ready Toolbar configuration. To change the configuration navigate to Jira administration > JEditor Configuration. Below is the short review of the sections in JEditor Configuration:
- Settings. On this tab, you will find settings related to JEditor's UI/UX, renderer settings, upload parameters.
If you just installed JEditor you may want to enable the Attach Uploads param, switch the Image Links param to Native Links and enable the Require Auth param.
You can also configure the default height of the editor or enable the Autogrow mode.
- Toolbar. On this tab, you can change the toolbar configuration: enable or disable the toolbar buttons, change the number of rows on the toolbar and change the order of the buttons. For more information about this tab see Toolbar and bottom bar.
- Templates. On this tab, you can manage HTML templates that users can insert using the Template button on the toolbar. For more information see Templates and prepopulation.
- Prepopulation. On this tab, you can configure field prepopulation schemes. JEditor can automatically populate any multi-line field on the Create Issue screen with a pre-defined template. For more information see Templates and prepopulation.
- Prepopulation for SD. On this tab, you can configure templates that will pre-populate the Description field on customer portals.
- Custom Styles. On this tab, you can add custom CSS code to Jira pages as well as configure the Styles dropdown list. For more information see Custom Styles/CSS.
- Replace. On this tab, you can configure JEditor Renderer's replace rule. These rules are executed during rendering of field data (during page load) and allow to replace any text (it's possible to use regular expressions) in any JEditor-rendered field. For more information see Replace With.
- Syntax Highlight. On this tab, you can configure some options for JEditor's code highlighter. It's possible to collapse all code snippets by default and hide/show line numbers.
If you are currently evaluating JEditor you probably want to know if JEditor is better than Jira's RTE (default built-in editor) and why. That's a tricky question. The answer is yes and no.
Yes, JEditor is much more capable compared to the Jira's RTE. JEditor has more features and it allows advanced formatting. Only using JEditor users can copy-paste from documents/emails/corporate portals preserving the styles and formatting.
However, JEditor is based on HTML formatting and it has its drawbacks. HTML formatting is more verbose compared to wiki markup (larger volumes of data to store in the DB). It also requires higher security (JEditor XSS filter is what makes JEditor Renderer about 15% slower compared to Wiki Renderer).
The true answer is JEditor should co-exist with Jira's RTE, not completely replace it. Every Jira needs JEditor to help users when they need to do something RTE is not capable of.
Here's a showcase. Consider copy-pasting the following table from Excel/Word to Jira:
This is what you get when you paste into JEditor:
And this is what you get when you paste into RTE:
In this example, JEditor is obviously better suited for the task.
However, enabling JEditor for all possible fields in Jira is probably overkill. Jira RTE works great for regular comments and most descriptions, especially in R&D projects. Such projects may benefit from using JEditor in a custom field on a when-needed basis.
At the same time projects, where users work with documents a lot (for example projects that serve as hubs for administrative tasks), may need JEditor as the default editor in the Description field.
Another big reason to use JEditor is customer portals. If you use Jira Service Desk heavily you need JEditor. It converts this:
It's important to know that when JEditor is enabled for comments on a customer portal, Service Desk agents may keep using Jira's RTE to benefit from features such as KB and canned responses.
JEditor uses HTML formatting of data instead of wiki markup. This helps JEditor to support a wide range of formatting options and allows end-users to copy data from various sources such as documents, emails, web pages. However, certain Jira notification templates are designed specifically for wiki markup/plain text and you will need to update those velocity templates adding HTML support.
If your Jira notification emails start coming with HTML tags see Jira notification email contain HTML tags.
JEditor for Jira Service Desk (Customer Portal)
If you use Atlassian Service Desk you may want to enable JEditor for the Description and/or the Comment field on customer portals.
JEditor for SD supports rich text formatting including such elements as tables, lists, links, inline images, text color, headings.
Most important your customer portal users will be able to paste data from a document or an email.
To enable JEditor for SD, do the following:
- Navigate to Jira administration > Add-ons
- Select Manage add-ons
- Locate JEditor in the list of user-installed add-ons
- Expand JEditor's list of modules
- Enable these modules:
- JEditor for CP users
- JEditor SD Comment (if you want JEditor to render the Comment field on the customer portal)
- JEditor SD Description (if you want JEditor to render the Description field on the customer portal)
- JEditor SD Agent Comment (if you want JEditor to render the Comment field on agent's view)
- Navigate to JEditor Configuration > Settings
- Enable the Attach Uploads parameter
- Change the value of the Image Links parameter to Native Links
JEditor can import your HTML formatted emails and create new Jira issues or comments. To enable the mail handler, do the following:
- Navigate to Jira administration > System > Incoming Mail
- Click the Add incoming mail handler button
- Select the JEditor Rich Text Mail Handler (create or comment)
- Follow the dialog to configure the mail handler
Please note that JEditor mail handler is very basic. It does a great job importing HTML-formatted emails. However, if you need more features you may want to try add-ons that specialize in importing emails: