Using the Atlassian Gadgets JavaScript Framework

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.

JavaScript Framework is currently in JIRA only

The Atlassian Gadgets JavaScript Framework is currently part of the JIRA project. It will eventually be moved into Atlassian Gadgets. See AG-622. Until that merge is completed, you will only be able to use the framework if you are developing gadgets for JIRA.

On this page:

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 stub for using the framework:

<?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" />
    <Require feature="oauthpopup" />
    <Require feature="setprefs" />
    <Require feature="settitle" />
    <Require feature="views" />
    <Optional feature="atlassian.util" />
    #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.jira.gadgets:common")
    #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.
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.

The requireResource #-directive will change once the framework is extracted from JIRA.

All Versions

Gadgets 1.0 Documentation

Child pages

Introduction

Using the Framework

RELATED TOPICS