Guide - Inline edit for JIRA plugins
JIRA 5.1 and later.
On this page:
Overview and purpose
The page provides information for JIRA plugin developers who wish to interact with JIRA's inline edit features that were introduced in JIRA 5.1.
The information on this page is typically most useful to JIRA plugin developers who wish to expose anything (such as custom fields or web panels) on JIRA's 'view issue' page.
Working with the
With inline edit enabled, document content changes frequently and there are several situations where plugins may need to reconfigure elements (e.g. bind event handlers, create elements). This should be performed in response to the
JIRA.Events.NEW_CONTENT_ADDED event (introduced in JIRA 5.0), which is triggered whenever new HTML is inserted into the document. The event handler is passed three arguments:
e— the event object,
context— the context in which the content was added (may be null or undefined) and
reason— the reason the event was triggered (new in JIRA 5.1 for inline edit).
The following table indicates the available
reason arguments and their associated contexts:
The user started inline editing a field — its 'view' HTML has been replaced with its 'edit' HTML.
The view issue page finished loading.
A panel on the view issue page (e.g. details, description) was refreshed after an inline edit — new HTML has been inserted into the document.
||(List View only) The table of results has been updated by a direct action from the user (i.e. click on the Refresh icon), because the user requested a new search/filter or because the user switched to a different results page. The
||(List View only) A row from the results table has been updated with new information about the issue. The context is the updated table row.|
||The user opened a dropdown menu from a criteria in the Basic Search. The context is the content of the dropdown menu.|
||The Filters panel has been opened. The context is the container of the Filters panel.|
||The Layout switcher has been rendered in the page. The context is the container of the button.|
||(List View only) The user has returned to the search from an issue. The context is the Search header.|
||The Share dialog is opened. The context is the dialog.|
||In the Search Filters section, the results table has been refreshed. The context is the whole section.|
||When the user clicks on a tab in pages with vertical tabs navigation. The context is the new section.|
||When any dialog is ready to be rendered. The context is the content of the dialog.|
||On the Components Administration page, the results table of current components is ready to be rendered. The context is the results table.|
||On the Workflows Administration page, a workflow is ready to be rendered. The context is the workflow container.|
||On the Workflows Administration page, the header of the page is ready to be rendered. The context is the container of the header.|
reasonargument will not be passed in JIRA 5.0.x versions.
Ensure that you scope
jQueryselectors to the provided context to avoid double binding — for example:
- It is recommended to always check the 'reason' argument.
- It is recommended to assume that
NEW_CONTENT_ADDEDcould be triggered at any moment and multiple times, depending on the actions performed by the user.
The following example demonstrates how you might configure custom fields and a web panel:
Custom fields and 'save on blur'
Save on blur is the automatic saving of inline edits made to a field when it loses focus (i.e. when the user clicks elsewhere on the page or tabs away from the field). All of JIRA's system and custom fields opt in to save on blur. However, save on blur is disabled by default for third party custom fields. Why? Custom fields generally display all of their content inside the inline edit boundaries, but sometimes add extra HTML in different areas of the DOM — e.g. inline layers or popup windows. JIRA cannot detect whether or not a piece of HTML "belongs" to a custom field editor and as such, we require custom fields provided by third party plugins to let JIRA know when they have been blurred.
To enable save on blur for a custom field, it must be registered in
JIRA.Components.IssueEditor.InlineEditUtils.BlurTriggerMapping.custom which maps custom field types to blur triggers — i.e. functions that determine when a field has lost focus and should be saved.
Opting in to the default blur trigger
If your custom field's edit HTML is entirely contained within the inline editor boundaries (i.e. it does not create inline layers, popup windows or any external DOM content), use
JIRA.Issues.InlineEdit.BlurTriggers.Default. This fires the "blur" event when focus leaves the inline editor boundaries.
The following example shows how you might register a custom field to use the default blur trigger:
Writing a custom blur trigger
The default blur trigger (used in the example above) will work well for most fields, but those that make use of popups, windows or elements located elsewhere in the DOM will require a custom blur trigger. A blur trigger is a function that determines when a field has lost focus and should be saved. The following is the simplest possible implementation of a blur trigger:
This blur trigger will announce that the field has blurred immediately after entering inline edit by triggering the
JIRA.Events.INLINE_EDIT_BLURRED event, passing the field's ID; while not very functional, this example demonstrates the basic structure of a blur trigger. The function is passed two arguments:
fieldId— the ID of the field that entered inline edit; and
$container— the element containing the inline editor—this contains your custom field's HTML as well as the save and cancel buttons provided by the inline edit framework.
Using these arguments, the blur trigger must bind to relevant events to determine when the field has lost focus. Situations that should be considered include:
- the input element (i.e. field) itself losing focus,
- elements located elsewhere in the DOM losing focus (e.g. inline dialogs), and
- the save/cancel buttons losing focus.
The following example is for a custom field that generates an external layer (in this case a warning) and attaches a custom save on blur trigger.
First let's listen to
JIRA.Events.NEW_CONTENT_ADDED and add a warning whenever a user starts editing the field.
Now, we want to trigger save-on-blur on this field, but not if the user clicks on the above warning message: