We’re making changes to our server and Data Center products, including the end of sale for new server licenses on February 2, 2021 and the end of support for server on February 2, 2024. Learn what this means for you.
Last updatedAug 13, 2019
Rate this page:
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.
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
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.
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.
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
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.
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: