Adding help tips to custom fields

Users who are new to JIRA often find it confusing when it comes to filling in fields, especially custom fields. So it is useful for you as the administrator to provide useful tips and descriptions to explain what some of the fields are for.

In this recipe, we will be adding a help icon for the Team custom field.

How to do it…

Proceed with the following steps to add help tips to a custom field:

1. Log in to JIRA as a JIRA administrator.
2. Navigate to Administration | Issues | Custom Fields.
3. Click on the Edit link for the custom field.
4. Enter the following HTML snippets into the Description text box, and click on Update. You might want to substitute the href value to a real page containing help text.

   Need help to work out Team assignment? Try this:

   <a class="help-lnk" href="/secure/ShowConstantsHelp.jspa?decorator=popup#Teams" title="Get help about Team" data-helplink="local" target="_blank">
       <span class="aui-icon aui-icon-small aui-iconfont-help"></span>
   </a>

   The following screenshot shows our new help icon:

   

How it works…

JIRA allows us to use any valid HTML for custom field description, so we added a simple text and an anchor tag that links to an HTML page containing our help information. We also added a span tag with the proper style class to have the nice question mark icon used by Issue Type and Priority fields.

The data-helplink="local" attribute for the anchor tag ensures when the user clicks on the help icon; the help page is opened in a separate page rather than redirecting the current page.

Tip

Since the custom field description is rendered as it is, make sure you validate your HTML, for example, close all your HTML tags.

There's more…

Normally, we put descriptions directly into the custom field's description textbox as demonstrated. You can also put your descriptions into the field configuration settings, such as hiding a field. Doing so offers the following advantages:

• You can have different help texts for different project/issue type contexts
• You can set help texts for fields that are not custom fields, such as Summary and Description

Proceed with the following steps to set field descriptions in field configuration:

1. Navigate to Administration | Issues | Field Configurations.
2. Click on the Configure link for the field configuration used by the project and issue type.
3. Click on the Edit link for the field.
4. Enter the HTML snippets into the Description field and click on Update.

See also

Refer to the Using JavaScript with custom fields recipe on other tricks you can do with custom field descriptions.