Dashboard item

Available:

Jira 6.4 and later.

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

Name

Description

i18n-name-key

The localization key for the human-readable name of the plugin module.

key

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your app, such as from the app Java code or JavaScript resources.
<dashboard-item key="new-dashboard-item"> ... </dashboard-item>

name

The human-readable name of the plugin module.

Used only in the app's administrative user interface.

configurable

Allows users to configure dashboard item.

*key attribute is required.

Elements

Name

Description

definitionThis information is used to populate the dashboard item's entry in the gadget directory. The gadget directory is where users select gadgets to add to the dashboard. This element is required if you don't specify replace-gadget-spec-uri.
replace-gadget-spec-uri

The gadget that is being replaced by this dashboard item still needs to be defined in your app.
Specify the definition of the gadget in this element. This element is required if you don't specify definition.

amd-module

The amd-module parameter is optional. You can use this to specify a JavaScript AMD (that is, Asynchronous Module Definition) module for your dashboard item. When the dashboard renders, it will call this module and provide it with the dashboard item's surrounding as context.

condition

Defines a condition that must be satisfied for the dashboard-item to be displayed.

If you want to "invert" a condition, add an attribute invert="true" to it.

The web item will then be displayed if the condition returns false (not true).

conditions

 

Defines the logical operator type to evaluate its condition elements. By default AND will be used.

context-provider

Passes variables to the Soy template.

description

The description of the plugin module. The key attribute can be specified to declare a localization key for the value instead of text in the element body.

That is, the description of the dashboard item.

resource type="view"

 

A resource element is used to provide a dashboard item with content. You can use this to render a dashboard item entirely server-side, by using an optional <context-provider/> to provide the data for rendering.

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

Definition elements

Name

Description

titleThe name of your dashboard item that will be displayed in the gadget directory. You can use key to reference i18n property or assign value to the body of element.
categoriesSpecify categories for your dashboard item using one or multiple category elements. Valid categories: Jira, Chart, Wallboard, Other, and Admin.
Default: Other.

author

Specify author using name element.
<author><name>Atlassian</name></author>

thumbnail

Point its location attribute to a picture that will be displayed in gadget directory.

*title and author elements are required.

Creating a new "standalone" dashboard item

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<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
3
4
5
6
<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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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.

MethodDescription
isEditable

Checks if a dashboard item is configurable and if the current user has permission to edit this dashboard item's configuration.
Returns {boolean} true if the current user can edit the gadget.

getRefreshFieldValue

Helper to extract the correct value to be persisted for a refresh field rendered with .refreshInterval.
Returns {string} value that should be persisted.

Parameters:

  • fieldName (string) — refresh field name, defaults to "refresh".
savePreferences

Tries to save the passed preferences on the server for this dashboard item.

If the user doesn't have permission to edit this dashboard item, no action is performed.

Parameters:

  • preferences (object) — the new preferences object to save for this dashboard item.
setTitle

Sets the title for the dashboard item.

Parameters:

  • title (string) — the new title for the dashboard item.
initRefreshTriggers a refresh of the dashboard item.
showLoadingBarShows the loading bar for the dashboard item.
hideLoadingBarHides the loading bar for the dashboard item.
getContextReturns the context for the dashboard item.
closeEditCloses the edit dialog of the dashboard item.
getGadgetIdReturns the ID for the dashboard item.
resize

When you add some content dynamically to your dashboard item and it causes the height to increase, a scroll appears.

Call this method to resize the content automatically and make the scroll go away.