Building a dashboard item

This guide will help you build a dashboard item for a Jira P2 add-on. You need to be familiar with building Jira P2 add-ons to use this guide.

If you build a dashboard item for a Jira Connect app, see this guide instead: Building a dashboard item for Jira Connect add-on.

A dashboard item is similar to a gadget since it provides discrete dynamic content that user can use to customize their dashboard. However, dashboard items use modern rendering technologies like AMD, Soy, LESS, and so on. Dashboard items are also able to share web-resources, which greatly improves page load performance by reducing the number of requests and the overall size of data to be transferred on a dashboard load.

Dashboard items will eventually replace gadgets in Jira. They are easy to build and are faster. Gadgets are rendered in iframes and cannot share web-resources, which makes them slow to load. Gadgets are also based on the OpenSocial specification that is no longer championed by Google.

Before you begin

If you replace a gadget with a dashboard item for your app, do not modify the existing OpenSocial gadget code. This provides you with a fallback, in case something goes wrong with your dashboard item. You can turn off the app module for the dashboard item and the old OpenSocial gadget will render instead.
Unlike gadgets, dashboard items do not support remoting, for example, embedding an OpenSocial gadget from Jira on a Confluence page. We don't have plans to support remoting for dashboard items at this point in time.

Defining the dashboard item

The Dashboard item page shows how you should define a dashboard item in your app descriptor.

General development guidelines

We recommend that you read all of the guidelines below before developing a dashboard item. These are high level guidelines, as this guide is intended for experienced app developers.

Setting the correct context

Unlike OpenSocial gadgets, dashboard items are not sandboxed in iframes. Hence, you need to set the correct context for the CSS/LESS and JavaScript of your dashboard item to ensure that it doesn't interfere with other dashboard items.

Ensure the CSS/LESS is properly namespaced. This ensures that the styling of your dashboard item does not interfere with other dashboard items on the dashboard.
Ensure all JavaScript operates in the context of the passed <div />. All JavaScript must operate within the context of the passed <div /> when the dashboard item is initialized. This ensures that event handlers, for example, only get bound within the current dashboard item and don't affect other dashboard items.

Performance

Only use server-side rendering for mostly static information. Anything that might be expensive (for example, running a JQL query, generating data for a chart, and so on) should not be done server-side, otherwise it will delay the rendering of the entire dashboard. Instead, the data should be requested via an AJAX request and then rendered client-side.

Using shared AMD modules and soy templates. You can introduce shared AMD modules and soy templates where this makes sense for common configuration form elements (for example, filter pickers)

Testing your dashboard item

Unit testing: we recommend testing all new code with a JavaScript unit testing framework, like QUnit.
Testing "replacement" dashboard items: we recommend that you test your "replacement" dashboard item by creating an instance of the old gadget and then enabling your new dashboard item. You can then check whether your dashboard item is compatible with the preferences of the old gadget.

Design guidelines

There are no design guidelines specific to dashboard items. We recommend that you consult the Atlassian design guidelines, as you should do when developing for any Atlassian product.

The following topics may be relevant to your dashboard item:

Tables
Forms