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.
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
project-scope-filter-context-provider plugin module. This is useful if web-items in the sidebar require additional context about which agile board has been selected for example.
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
selectedBoardId param in the URL as follows:
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
ProjectSidebarRenderer component and its
render(projectKey, selectedItemId) method.
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:
- The web-panel is simpler to implement, especially if you have a simple (static) add-on.
- The sidebar is rendered for you. In addition, the context for your web-panel is populated with the same project parameters and scopefilter parameters as for web-items.
If you choose to implement full control of rendering, your add-on will need to render the sidebar.
- The sidebar client-side web-resources are already included.
If you choose to implement full control of rendering, your add-on must include the sidebar client-side web-resources in the
ProjectPageServletin the jira-projects plugin selects the correct item in the sidebar based on the
If you choose to implement full control of rendering, your add-on's code will have to handle selecting the correct item.
To implement full control of rendering for your add-on's page content:
- Render the entire page, including the sitemesh decorator using an existing plugin mechanism (most likely a servlet or webwork action).
- In this servlet or webwork action, get the
ProjectSidebarRenderercomponent injected and render the sidebar HTML using an appropriate AUI page structure. The jira-projects plugin provides a
JIRA.Projects.Templates.pagesoy template to make this easier
- Require all web-resources in the jira.project.sidebar web-resource context.
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
subnavigator on the client side:
As you can see, there is a dependency declared on the
reports.page web resource, so that whenever the page is loaded, the subnavigator resources are also downloaded.
The most detailed and up to date documentation around this component can be found in the source code on
jira-projects-page-objects also provides a
Subnavigator.java that you can use as a PageObject for the component on your web driver tests.
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.