Development guide - JIRA project-centric view
This page provides you with development guidelines for adding your add-on to the new project-centric view in JIRA.
Read the Design guide - JIRA project-centric view before you read this page. The design guide will help you provide the best user experience for your add-on in the project-centric view.
The project-centric view will be introduced in JIRA 6.4, but can be disabled on both the user level or on the global level by an administrator.
For both JIRA Cloud and JIRA Server, individual users will be able to switch it on or off. Administrators will also be able to override this setting (i.e. enable/disable for all users). This means that from JIRA 6.4, your add-on will need to cater for instances where the project-centric view is enabled, as well as instances where it is disabled.
On this page:
The project-centric view features the following components:
- A sidebar header
- Sidebar content section, including project navigation, project links and favorite filters for the user
- Sidebar administration link (if the currently logged in user is a project administrator)
- Page content area
Screenshot: Example JIRA project-centric view
Most add-ons will just need to add links for their project-related content to the sidebar. If you want to do this, read the Basic implementation section below.
If you want a more customized implementation, e.g. you want your add-on's sidebar link to open a particular board in the project, read the Advanced implementation section below.
To add a link for your add-on to the sidebar, you will need to add the link to the sidebar as a web-item, then provide the content in the main page content area.
Step 1. Add the link to the sidebar as a web-item
- Add your link as a web-item to the
The following context parameters are available for your web-item. Specify the parameters that you need.
Parameter Description project The current project object projectKey The current project key pathEncodedProjectKey URL path encoded project key queryEncodedProjectKey URL query param encoded project key Pluggable Scope Filter Parameters See Scope filters section below
For more details, see the
ProjectContextPopulatorin the jira-projects plugin.
For example, here is the web-item definition for the 'Releases' link shown in the Example JIRA project-centric view screenshot above:
Step 2. Provide the content
- Define a web-panel for your content.
- Reference the web-panel from the sidebar link that you added as a web-item, in the previous step.
For example, here is the web-item and web-panel definitions for the 'Releases' link shown in the Example JIRA project-centric view screenshot above.
Note how the
link property in the
release-page web-item references the
location property in the
release-page-key web-panel. The
ProjectPageServlet will take care of wiring up the
selectedItem with the web-panel location and rendering the panel when the web-item URL is requested. Additional web-resources (JS, CSS) can also be included on the page by adding them to the
This mechanism is the same for atlassian-connect add-ons. For example the following atlassian connect descriptor would render a sidebar link and content when selected.
The project-centric view allows you to extend both the sidebar and page content, as described below.
Extending the sidebar
Advanced methods for extending the sidebar:
JIRA projects provide an additional scope filter, to allow users to select a project-specific Agile board. Scope filters can add additional context used to render web-items and page content via the new
In JIRA Agile's example, the following scope filter context provider provides additional params for web-items defined in JIRA Agile that plugin into the sidebar:
This simply implements the following interface provided by the
Additional context provided by this mechanism can then be used when rendering links. For example, by using an additional
|Serverside Rendering API||The sidebar is rendered by a number of re-usable Java components that can be injected. Rendering is broken down into the following components:
The main entry point to render a project centric sidebar is provided by the
Extending the page content
Full control of rendering
You should only use this option for advanced add-ons, where you need full control of the URL state. An example of this is JIRA's agile board, where the sidebar allows users to switch between Backlog, Active Sprints and Reports via sidebar links on the client side.
This approach lets you implement advanced navigation, like sub-navigation within the page. However, in many cases, it is better to implement the basic web-panel (described above) instead — here are some of the reasons why:
To implement full control of rendering for your add-on's page content:
Content sub-navigation component
In project-centric navigation model, once users arrive at certain project pages, they can filter the content on that particular page by using the subnavigation control. For example, in the screenshot in the right, once the reports page is loaded, users can select to narrow down what they see and choose to display only the information regarding the Control Chart.
The procedure for implementing this component is best explained by example: consider the reports page shown in the screenshot on the right. This is how it is bringing the resources required to use the
As you can see, there is a dependency declared on the
The most detailed and up to date documentation around this component can be found in the source code on
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.