The sidebar is the main feature of the new project-centric view in JIRA. Read the Design guide - JIRA project-centric view, then the Development guide - JIRA project-centric view before you read this page.
Accessing the sidebar
The Sidebar API is a singleton exposed under the global variable
JIRA.API.Sidebar. Please, note that this global variable loads asynchronously.
If you need to know when the Sidebar is ready to be used, use
JIRA.API.getSidebar(). This method will return a promise, that will eventually be resolved when the Sidebar is ready. For example:
The Sidebar is a collection of NavigationGroup. A NavigationGroup is defined by an HTML element with the class
aui-sidebar-group. Each NavigationGroup can have an optional id, defined by the attribute
data-id (the main group has id "default"). If a group is not found, the get method will return
group.id to retrieve the ID of the group.
Each group is a collection of NavigationItems. A navigation item is defined by a list item (
<LI> inside a
<UL>) that contains an
<A> tag. The navigation item can contain an optional id, defined by the attribute
data-link.id. If there are two items with the same id, the Sidebar will log a warning in the console. If the user calls
getItem()/getItemAt() directly in the Sidebar, it will search for the item in the default group. Similar to
getGroupAt(), if the item does not exist, it will return
undefined. When an item is selected, you can use
item.id to retrieve the ID of the item.
A Navigation subgroup is a nested group inside a NavigationSubgroup. It is defined by a nested
<UL>/<LI> list inside a Navigation Item. In order to select it, the user can use
getItem()/getItemAt(). A NavigationSubgroup behaves like a NavigationGroup, the user can use
getItem()/getItemAt() to select items inside the NavigationSubgroup. As usual, if the NavigationSubgroup does not exist, it will return
undefined. When an subgroup is selected, you can use
subgroup.id to retrieve the ID of the subgroup.
Reacting to user actions
Clicking a link
When a user clicks a NavigationItem, the sidebar will throw events to programmatically react to the click action. By default, it will follow the link specified in the
href attribute. These three events are triggered in order:
Note, these events are not triggered for links that open in a new tab (i.e. with
target="_blank" or clicked with
This event means that the Sidebar is about to mark an element as selected. This event can be prevented, meaning that the Sidebar will not highlight the element, and will not navigate to the link. Also, if there is an already selected item, it will not be deselected.
This is similar to the
before:select event, however it means that the Sidebar has marked an element as selected (i.e. it happens after
before:select). This event is not preventable.
This event means that the Sidebar (more specifically: the browser) is about to navigate to the URL specified in the item. This event is preventable. If it is not prevented, the browser will load a different page. Use this event if you want to avoid a page loading, but you still want the item to be marked as selected.
Deselecting a link
When the user clicks a link, the Sidebar deselects the currently selected link (if any). This action also triggers two events:
These events are similar to the
select events. For example, the user can prevent
before:deselect to stop the item from being deselected (and the new item from being selected), and ask the user for confirmation before leaving.
Example workflow — changing selection
This section shows how the events described above would be triggered in a typical user workflow. In this case, the scenario is changing a selection.
Say there are two items: item A and item B, where item A is selected and item B is not selected initially. If a user selects item B, the flow of the actions would look like this:
before:selecton B. If prevented, stop now
before:deselecton A. If prevented, stop now.
- Deselect item A.
- Select item B
before:navigateon B. If prevented, stop now.
- Go to B link.
Simulating user actions
The API provides two methods for simulating the user's actions,
This method will highlight the selected item, but it will not perform any navigation. It will trigger the
select events. This should be used when the plugin has changed the page and you want to inform the user about the new page.
You may want to use this method in the following scenarios:
- Initial load of the plugin
- Changing the plugin page using keyboard shortcuts
- Changing the page using internal links in the plugin
This method will follow the link specified in the
HREF. It will trigger the preventable event
before:navigate. Plugins can use this method to restart themselves, as a call to
navigate() will trigger a new page load. For example:
Listening to multiple items
Listening for events in each individual item is useful, but it can be cumbersome in some use cases. For example, if you have a NavigationSubgroup that shows all of the releases for a project, you probably want to handle a click in any of the individual releases in the same way. Adding an event to each release would be too verbose.
To help with this case, all the events (
before:deselect and deselect) will "bubble up" from the Item all the way up to the Sidebar component, including any group or subgroup. The user can listen for the events in any of the groups, and use
event.emitter to access to the actual item that triggered the event.
Try the following resources:
- Post your question on our forums: Atlassian Answers. This is probably the fastest way to get help, as many of our customers and staff are active on Atlassian Answers.
- Contact the developer relations team: https://developer.atlassian.com/help#contact-us. Note, you will need to create a developer.atlassian.com account if you don't already have one.