Dashboard item

Purpose of this module type

Dashboard items allow apps to display a summary information data on the dashboard. Each dashboard-item can be configured to display information relevant to a particular user. Dashboard items will eventually replace gadgets in Jira.

Configuration

You can define your dashboard item in the atlassian-plugin.xml file. For more details, see the Configuring the app descriptor page.

The root element for the Dashboard item plugin module is dashboard-item. It allows the following attributes and child elements for configuration.

Attributes

*key attribute is required.

Elements

*definition or replace-gadget-spec-uri element is required.

Definition elements

*title and author elements are required.

Creating a new "standalone" dashboard item

This is the definition for a "standalone" dashboard item:

1
2
<dashboard-item key="new-dashboard-item" i18n-name-key="dashboard.item.name" configurable="true">
    <definition>
        <title key="dashboard.item.title"/>
        <categories>
            <category>Jira</category>
        </categories>
        <author>
            <name>Atlassian</name>
        </author>
        <thumbnail location="/download/resources/atlassian-plugin-key:web-resource-module-key/login-thumb.png"/>
    </definition>
    <description key="dashboard.item.description"/>
    <resource name="view" type="soy" location=":web-resource-module-key/Soy.DashboardItem.Templates.TemplateName"/>
    <amd-module>jira-dashboard-items/my-amd-module</amd-module>
    <context-provider class="com.example.plugins.dashboarditem.DashboardItemContextProvider"/>
    <condition class="com.atlassian.jira.plugin.webfragment.conditions.IsAnonymousUserCondition"/>
</dashboard-item>

Replacing a gadget with a dashboard item

This is the definition for a dashboard item that replaces a gadget:

1
2
<dashboard-item key="login-dashboard-item">
     <replace-gadget-spec-uri>rest/gadgets/1.0/g/com.atlassian.jira.gadgets/gadgets/login.xml</replace-gadget-spec-uri>
     <resource name="view" type="soy" location=":login-dashboard-item-resources/JIRA.DashboardItem.Login.Templates.Login"/>
     <amd-module>jira-dashboard-item/login</amd-module>
     <context-provider class="com.atlassian.jira.dashboarditem.login.LoginContextProvider"/>
 </dashboard-item>

Example AMD module

If you want to specify a JavaScript AMD module for your dashboard item, you can use the following example as a guideline:

1
2
define("jira-dashboard-items/sample-dashboard-item", [
    'underscore'
], function (_) {
    var DashboardItem = function (API) {
        this.API = API;
    };
    /**
     * Called to render the view for a fully configured dashboard item.
     *
     * @param context The surrounding <div/> context that this items should render into.
     * @param preferences The user preferences saved for this dashboard item (e.g. filter id, number of results...)
     */
    DashboardItem.prototype.render = function (context, preferences) {
        //TODO: render the view with the preferences provided
        this.API.once("afterRender", _.bind(function () {
            this.API.showLoadingBar();
        }, this));
    };
    /**
     * Called to render the configuration form for this dashboard item if preferences.isConfigured
     * has not been set yet.
     * This method will be called only if dashboard-item is configurable and editable
     *
     * @param context The surrounding <div/> context that this items should render into.
     * @param preferences The user preferences saved for this dashboard item
     */
    DashboardItem.prototype.renderEdit = function (context, preferences) {
        //TODO: render a config form here using provided SOY templates and assign it
        //      to the 'form' variable, i.e.
        //      context.empty().html(My.Soy.Templates.Example({preferences: preferences}));
        form.on("submit", _.bind(function (e) {
            e.preventDefault();
            if (!validateFields()) {  //TODO: validateFields needs to implemented
                this.API.resize();
                return;
            }
            this.API.savePreferences({
                //provide parsed prefs from your config form here
                //to store them for this dashboard item
            });
        }, this));
        form.find("input.button.cancel").on("click", _.bind(function () {
            this.API.closeEdit();
        }, this));
    };
    return DashboardItem;
});

API interface

An API interface is passed to the AMD module in the example above. The table below describes this interface.

Related topic

• Building a dashboard item — this reference guide provides common recommendations on how to build dashboard items.
• Writing a dashboard item app