Using the Atlassian Gadgets JavaScript framework

Available:

Atlassian Gadgets 2.0 and later.
(The Atlassian Gadgets JavaScript Framework was not part of Atlassian Gadgets 1.0.x. It was available only within JIRA 4.0.x, as part of the JIRA project.)

This document assumes that you are familiar with (or have the documentation available for) writing gadgets and you have read Writing an Atlassian Gadget.

Using the Atlassian Gadgets JavaScript Framework is the preferred and recommended way of developing gadgets for Atlassian applications.

Introduction

During development of our own gadgets, we realised there were a lot of common requirements and functionality between gadgets. This led to the development of the Atlassian Gadgets JavaScript Framework. This framework is the basis of most of the gadgets developed at Atlassian.

Terminology: On this page and its child pages,

when we refer to the 'framework', we mean the Atlassian Gadgets JavaScript Framework.
when we refer to a 'gadget', we mean a gadget JavaScript object.

Feature overview:

Authentication
- Brokers a Trusted Applications connection if available and required
- Brokers an OAuth connection if available and required
View Helpers
- Automatic reloading of a gadget based on a time interval
- Automatic reloading of a gadget on browser window resize
- Automatic gadget resizing on browser window resize
- Parallel Ajax resource loading for the view
Configuration
- Permission-based gadget configuration
- Configuration screen display on initial gadget load
- Complex configuration form building
- Validation of configuration
- Inline error display
- Saving of parameters
- Parallel Ajax resource loading for configuration form
jQuery-style remoting
- A wrapper over gadgets.io.makeRequest supplying a cleaner and more common interface for Ajax calls
Cookie storage
- Cookie storage and retrieval on a gadget by gadget basis
Performance
- Conversion of proxied remote calls into direct calls if possible
Common styling
- Loading of screens, standard icons, common CSS

Using the Framework

These examples assume that you are familiar with the gadget XML format and Atlassian's customisations to it.

Here is a basic gadget specification using the Atlassian Gadgets JavaScript Framework:

1
2
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="__MSG_gadget.title__" directory_title="__MSG_gadget.title__" description="__MSG_gadget.description__">
    <Require feature="dynamic-height" />
    <Optional feature="auth-refresh"/> 
    <Require feature="oauthpopup" />
    <Require feature="setprefs" />
    <Require feature="settitle" />
    <Require feature="views" />
    <Optional feature="atlassian.util" />
    <Optional feature="gadget-directory">
      <Param name="categories">Other</Param>
    </Optional>
    #oauth
    #supportedLocales("gadget.common,your.gadget.resource.prefix")
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    /* (1) This resource is required for using the gadget framework */
    #requireResource("com.atlassian.gadgets.publisher:ajs-gadgets")
    #includeResources()

    <script type="text/javascript">
      (function () {
        /* (2) Construct and initialise the gadget */
        var gadget = AJS.Gadget({
          baseUrl: "__ATLASSIAN_BASE_URL__", /* (3) Used to make base url available to gadget */
          view: {...view-options...} /* (4) Defines the view logic */
        });
      })();
    </script>
  ]]>
  </Content>
</Module>

The lines of interest are:

This includes all required JavaScript and CSS resources needed to use the framework. See Using Web Resources in your Gadget. The path to the Atlassian Gadgets JavaScript Framework is as follows:
- In Atlassian Gadgets 1.0.x, the JavaScript framework is available in JIRA only and is not part of the Atlassian Gadgets framework. The path in JIRA 4.0.x is: #requireResource("com.atlassian.jira.gadgets:common").
- In Atlassian Gadgets 2.0 and later, the JavaScript framework has been extracted from JIRA and made part of the Gadgets framework. The path is: #requireResource("com.atlassian.gadgets.publisher:ajs-gadgets")
This constructs the gadget object and initialises it with the passed in options.
The framework needs access to the base URL, so we pass it in. See Using Substitution Variables and Directives in your Gadget.
This initialises the view.

Example Gadgets

See the sample OAuth gadget (requires login) for a simple example of how to use the JavaScript framework.

Including Features into your Gadget
Using Web Resources in your Gadget
Writing an Atlassian Gadget
Gadget Developer Documentation