Gadget Object API

This page describes the methods available in each type of gadget object. This page is part of the documentation on the Atlassian Gadget Library.

On this page:

Overview

Please refer to Creating a Gadget JavaScript Object for details on constructing a gadget object. The methods provided on this page can be called not only on the constructed object, but also from any method provided in the construction configs. All methods passed in as config parameters (e.g. the view template, the config descriptor, ...) are run in the scope of the gadget itself. Therefore, this refers to the gadget and any of the following methods can be called on this.

Under the hood, the constructor method AJS.Gadget(...) is a factory method that constructs a specific type of gadget depending on the config parameters passed in. The three kinds of gadgets are:

• Standard
• Configured (inherits all of the methods from Standard Gadget)
• Configurable (inherits all of the methods from Configured Gadget)

Each type is described below.

Standard Gadget

A Standard Gadget is constructed when a view parameter is passed in but no config parameter. This is useful when no configuration is needed for the gadget. An example is the Quick Issue Create gadget in JIRA.

All other gadget types extend the Standard Gadget type.

return {
    showMessage: function (type, msg, dismissible){}, /* Displays a message in dialogue box. */
    savePref: function (name, value){},               /* Saves user preferences locally and to the database. */
    setViewMode: function (){},                       /* Toggles class of gadget to the specified view. */
    getViewMode: function (){},                       /* Returns the current view mode as a string. For example "Canvas". */
    getBaseUrl: function (){},                        /* Helper function to get the context path for jira. */
    getPrefs: function (){},                          /* Gets user preference object. */
    getPref: function (name){},                       /* Some sugar for getting a preference by name */
    getPrefArray: function (name){},                  /* Retrieves a user pref array */
    getMsg: function (key){},                         /* Gets the i18n String */
    getGadget: function (){},                         /* Gets the gadget object, wrapper div for all gadget html (jQuery Object) */
    resize: function (){},                            /* Resizes iframe to fit content */
    showLoading: function (){},                       /* Shows loading indicator */
    hideLoading: function (){},                       /* Hides loading indicator */
    createCookie: function (name, value, days){},     /* Stores a value into a cookie, unique to this gadget. */
    readCookie: function (name){},                    /* Retrieves a previously stored cookie value */
    eraseCookie: function (name){}                    /* Removes a cookie value */
};

showMessage

Displays a message in a dialogue box.

showMessage: function (type, msg, dismissible) {}

Where:

• type — (String.) Style of message. Options include "error, info".
• msg — (String, Object.) An HTML string or jQuery object containing message.
• dismissible — (Boolean.) If set to false, no cancel button will be available.

savePref

Saves user preferences locally and to the database. In order to persist these values and have them available when gadget is reloaded, the setprefs feature must be declared as required in the gadget XML specification.

savePref: function (name, value) {}

Where:

• name — (String.) Name of preference to save.
• value - (String, Array.) Value (or values) to save to the database.

setViewMode

Toggles the class of the gadget to the specified view. This class is used to style the view accordingly.

setViewMode: function (mode) {}

Where:

• mode — The class to toggle on the gadget.

getViewMode

Returns the current view mode as a string. For example "Canvas".

getViewMode: function () {}

getBaseUrl

Helper function to get the context path for JIRA. Necessary for remote requests.

getBaseUrl: function () {}

getPrefs

Gets user preference object.

getPrefs: function () {}

getPref

Gets a preference by name.

getPref: function (name) {}

Where:

• name — The name of the preference to retrieve.

getPrefArray

Retrieves a user preference array.

 getPrefArray: function (name){}

Where:

• name — The name of the preference array to retrieve.

getMsg

Gets the i18n string from the included language bundles. Returns the key if it does not exist.

getMsg: function (key){}

Where:

• key — The key of the message to retrieve.

getGadget

Gets the gadget object, wrapper div for all gadget HTML (jQuery object).

getGadget: function (){}

resize

Resizes the iframe to fit the content.

resize: function (){}

showLoading

Shows an indicator that the gadget is loading.

showLoading: function (){}

hideLoading

Hides the loading indicator.

hideLoading: function (){}

createCookie

Stores a value in a cookie, unique to this gadget.

Use cookies with caution, so that the browser does not create too many cookies. They are necessary if you need to store a value for the current user rather than for the gadget. Where possible, use UserPrefs instead. UserPrefs will store values for the gadget, not the user.

createCookie: function (name, value, days){}

Where:

• name — The name (key) of the cookie to store.
• value — The value to store in the cookie.
• days — The number of days to keep the cookie active.

readCookie

Retrieve a previously stored cookie value.

readCookie: function (name){}

Where:

• name — The name of the cookie value to retrieve.

eraseCookie

Removes a cookie value.

eraseCookie: function (name){}

Where:

• name — The name of the cookie value to erase.

Configured Gadget

A Configured Gadget is constructed when view and config parameters are passed in but the current user does not have permission to edit the gadget's preferences. The gadget contains a view and footer.

This gadget has all of the same methods as a Standard Gadget plus the following:

return AJS.$.extend(getStandardInterface(), {
    getView: function(){},            /* Gets the view object, wrapper div for all view html (jQuery Object)  */
    showView: function(refresh){},    /* Display the view */
    getFooter: function(){}           /* Gets the footer object, wrapper div for all footer html (jQuery Object) */
});

getView

Gets the view object, wrapper div for all view HTML (jQuery object). This object is a div with the class of "view" and is contained within the object returned from getGadget().

getView: function(){}

showView

Displays the view. When refreshing content, the view template is called. If not refreshing content, this method simply displays the currently rendered view.

showView: function(refresh){}

Where:

• refresh — Specifies whether or not to refresh the view content.

getFooter

Gets the footer object, wrapper div for all footer HTML (jQuery Object). This object is a JQuery wrapped div with the class of "footer". It is contained within the object returned from getGadget() and is displayed underneath the view.

getFooter: function(){}

Configurable Gadget

A Configurable Gadget is constructed when view and config parameters are passed in and the current user has permission to edit the gadget's preferences. The gadget contains a view, a footer and a configuration screen.

This gadget inherits all of the methods from Configured Gadget plus the following:

return AJS.$.extend(getConfiguredInterface(), {
    showConfig: function(){},   /* Displays the configuration screen */
    getConfig: function(){}     /* Gets the config object, wrapper div for all config html (jQuery Object) */
});

showConfig

Displays the configuration screen with all fields defined during construction.

showConfig: function(){}

getConfig

Gets the config form object, wrapper div for all config HTML (jQuery Object). It is contained within the object returned from getGadget().

getConfig: function(){}

RELATED TOPICS

Using the Atlassian Gadgets JavaScript Framework
Writing an Atlassian Gadget
Gadgets and Dashboards Development Hub