Last updated Dec 8, 2017

Including Features into your Gadget

Changed:

The auth-refresh feature is available in Atlassian Gadgets 1.1.3.

Changed:

The auth-refresh feature is automatically included in every gadget in Atlassian Gadgets 1.1.4 and 2.0.4.

A 'feature' is a JavaScript library that provides specific functionality for inclusion into your gadget. This page gives an overview of how you can use a feature in your gadget and a list of available features.

Using a Feature in your Gadget

To create a gadget that uses a particular feature, such as dynamic height adjustment, you will do the following:

  1. Include the feature library via a <Require> element or an <Optional> element in your gadget XML specification. The format is:

    1
    2
    <ModulePrefs 
      title="My Gadget">
      <Require feature="my-feature-name"/>
    </ModulePrefs>
    

    Here is a simple example:

    1
    2
    <ModulePrefs 
      title="My Height-Adjusting Gadget">
      <Require feature="dynamic-height"/>
    </ModulePrefs>
    
  2. Write some JavaScript code to use the feature. The JavaScript code goes in the <Content> element of your gadget XML specification. The JavaScript APIs are described in the OpenSocial JavaScript API and in our JavaScript API reference guide.

List of Features

An unadorned list of features is available from our code repository. Below we provide more detail about the features.

Supported in
Atlassian Gadgets?

Description

Fully supported

This 'authentication refresh' feature is available in Atlassian Gadgets 1.1.3 and later versions of 1.1.x, and in 2.0.4 and all later versions.

This feature is automatically included in every gadget

In Atlassian Gadgets 1.1.4 and later versions of 1.1.x, and in 2.0.4 and later, this feature is automatically included in every gadget that is hosted in an Atlassian Gadgets container. You do not need to add the auth-refresh feature yourself. There is also no way to exclude the feature from your gadget. It is inserted into every gadget by the Atlassian OpenSocial Plugin.

The authentication refresh feature causes the dashboard to verify and refresh the authentication of every gadget on a regular basis. Every twelve minutes the dashboard will request a new security token for each gadget on the dashboard. It will then make an RPC call to each gadget so that gadgets.io.makeRequest will use the new token when making requests. The auth-refresh feature also sets up an RPC handler to receive the new security token. This feature fixes AG-661 for any gadgets that are displayed on a dashboard. The fix does not apply to standalone gadgets.

Feature name: auth-refresh

Specified by: Shindig

Fully supported

Allows a gadget to retrieve the base URL for the renderer server. Example:

1
2
<Module>
  <ModulePrefs title="My Gadget">
    <Optional feature="atlassian.util"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <div id="main">
      <script language="javascript">
        function showRendererBaseUrl() {
          document.getElementById("main").innerHTML =
              atlassian.util.getRendererBaseUrl();
        };
        gadgets.util
          .registerOnLoadHandler(showRendererBaseUrl);
      </script>
    </div>
  ]]>
  </Content>
</Module>

Because this feature is specific to Atlassian Gadgets, we recommend that you use <Optional> rather than <Required> when specifying this feature in your gadget. Otherwise the gadget will not work in other containers.

Feature name: atlassian.util

Specified by: Atlassian Gadgets

Not supported

Google Analytics

Feature name: analytics

Specified by: OpenSocial

Not supported

Support for Caja, a Google project aiming to allow web applications to provide active content safely, simply, and flexibly. The basis of the project is that a subset of Javascript provides an object-capability language.

Feature name: caja

Specified by: OpenSocial

Not referenced

The content-rewrite feature defines a set of rewriting operations that a container can perform on rendered and proxied content. It also defines rules to allow developers to control which content the rewriter can operate on.
Tip: During development, you may find this feature useful to disable the automatic caching provided by Shindig, so that your gadget resources will be re-loaded when you re-load the page. Otherwise you will have to restart the container in order to see the updated values in your gadget. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Optional feature="content-rewrite">
     <Param name="expires">86400</Param>
     <Param name="include-url"></Param>
     <Param name="exclude-url">excluded</Param>
     <Param name="exclude-url">moreexcluded</Param>
     <Param name="minify-css">true</Param>
     <Param name="minify-js">true</Param>
     <Param name="minify-html">true</Param>
 </Optional>
</ModulePrefs>

See the OpenSocial Gadgets API Specification.

Feature name: content-rewrite

Specified by: OpenSocial

Fully supported

Provides remote content retrieval functions. See the OpenSocial gadgets.io API reference.

Note that you do not need to explicitly request this feature with a <Required> or <Optional> element. This feature is provided automatically to all gadgets.

Feature name: core.io

Specified by: OpenSocial

Fully supported

Provides core gadget support, including JavaScript APIs for manipulating JSON data, escaping and unescaping strings, and accessing user preferences. See the OpenSocial gadgets.json API reference, the OpenSocial gadgets.Prefs API reference, and the OpenSocial gadgets.util API reference.

Note that you do not need to explicitly request this feature with a <Required> or <Optional> element. This feature is provided automatically to all gadgets.

Feature name: core

Specified by: OpenSocial

Fully supported

Gives a gadget the ability to resize itself. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="dynamic-height"/>
</ModulePrefs>

You will call the JavaScript function gadgets.window.adjustHeight() whenever there is a change in content, or another event occurs that requires the gadget to resize itself. See the OpenSocial gadgets.window API reference. You may also find useful information in the Google documentation on creating a user interface.

Feature name: dynamic-height

Specified by: OpenSocial

Fully supported

Allows you to embed a Flash movie into your gadget. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="flash"/>
</ModulePrefs>

You will call the JavaScript function gadgets.flash.embedFlash() to embed a .swf file in your gadget and display it in a designated location. Note that to use this feature, all resources must be bundled in a .swf file. See the OpenSocial gadgets.flash API reference. You may also find useful information in the Google documentation on creating a user interface.

Feature name: flash

Specified by: OpenSocial

Fully supported

Allows a gadget to specify details for its directory listing, such as the category in which the gadget should be listed. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Optional feature="gadget-directory">
      <Param name="categories">
          JIRA
          Charts
      </Param>
  </Optional>
</ModulePrefs>
The only recognized parameter is categories -- the list of directory categories that this gadget should appear in, one per line. Valid values are "JIRA", "Confluence", "FishEye", "Crucible", "Crowd", "Clover", "Bamboo", "Admin", "Charts", "External Content", and "Other". Gadgets that don't specify a directory category, or that specify only invalid categories, will be listed in "Other".

Because this feature is specific to Atlassian Gadgets, we recommend that you use <Optional> rather than <Required> when specifying this feature in your gadget. Otherwise the gadget will not work in other containers.

Feature name: gadget-directory

Specified by: Atlassian Gadgets

Not supported

Feature name: locked-domain

Specified by: OpenSocial

Fully supported

A MiniMessage is a temporary message displayed to users from within a gadget. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="minimessage"/>
</ModulePrefs>

See the OpenSocial gadgets.MiniMessage API reference. You may also find useful information in the Google documentation on creating a user interface.

Feature name: minimessage

Specified by: OpenSocial

Fully supported

Manages popup windows for OAuth. See our detailed instructions on OAuth and the OpenSocial gadgets.oauth.Popup API reference.

Feature name: oauthpopup

Specified by: OpenSocial

Not supported

Feature name: opensocial-0.6

Specified by: OpenSocial

Not supported

Feature name: opensocial-0.7

Specified by: OpenSocial

Not supported

Feature name: opensocial-current

Specified by: OpenSocial

Not supported

Feature name: opensocial-reference

Specified by: OpenSocial

Not supported

Feature name: opensocial-templates

Specified by: OpenSocial

Not supported

Allows your gadget to publish and subscribe to message channels. See the OpenSocial gadgets.pubsub API reference.

This feature is not related to the Atlassian directory publish and subscribe feature (see Atlassian Gadgets 2.0 Release Notes), despite the similar name. The OpenSocial pubsub feature is meant to allow gadgets on a page to communicate with each other. It is not actually specified by OpenSocial currently, but planned to be standardised in a future version of the specification.

Feature name: pubsub

Specified by: OpenSocial

Fully supported

Provides operations for making remote procedure calls for gadget-to-container, container-to-gadget, and gadget-to-gadget communication. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="rpc"/>
</ModulePrefs>

You need to specify "rpc" as a required feature if you are using the gadgets.rpc JavaScript API directly. If you are using only features that happen to rely upon gadgets.rpc, such as settitle, dynamic-height, then the rpc feature will be implicitly included and you do not need to include it explicitly. But you should not rely on this auto-inclusion if you are using the API directly, as this behaviour may differ in other containers. See the OpenSocial gadgets.rpc API reference.

Feature name: rpc

Specified by: OpenSocial

Fully supported

Allows you to set the values for user preferences programmatically, without the user's direct participation. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="setprefs"/>
</ModulePrefs>

See the OpenSocial gadgets.Prefs API reference. You may also find useful information in the Google documentation on saving state.

Feature name: setprefs

Specified by: OpenSocial

Fully supported

Allows you to set your gadget's title programmatically. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="settitle"/>
</ModulePrefs>

See the OpenSocial gadgets.window API reference. You may also find useful information in the Google documentation on creating a user interface.

Feature name: settitle

Specified by: OpenSocial

Not referenced

Allows you to manage the skin of your gadget programmatically. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="skins"/>
</ModulePrefs>

See the OpenSocial gadgets.skins API reference.

Feature name: skins

Specified by: OpenSocial

Fully supported

Allows you to add a tabbed user interface to your gadget. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="tabs"/>
</ModulePrefs>

See the OpenSocial gadgets.TabSet API reference. You may also find useful information in the Google documentation on creating a user interface.

Feature name: tabs

Specified by: OpenSocial

Partially supported

A view is a location in a container where a gadget is displayed. Different views have different characteristics. For example, a container might have a view that shows gadgets in a small format, and a view that shows gadgets in full page format. Atlassian Gadgets supports the following views:
default -- The standard view of a gadget, displayed in a small box on the page, possibly with other gadgets. You can also use the aliases 'DEFAULT', 'DASHBOARD', 'profile', or 'home'.
canvas -- The maximised view of a gadget when displayed by itself on the page.

You need to specify "views" as a required feature if you are using the gadgets.views JavaScript API directly. If you just need to use the canvas view, it is enough to include a content section with view="canvas" and you do not need to specify the feature. Format:

1
2
<ModulePrefs 
  title="My Gadget">
  <Require feature="views"/>
</ModulePrefs>

See the OpenSocial gadgets.views API reference. You may also find useful information in the Google documentation on creating a user interface.

Partial support

Atlassian Gadgets provides only partial support of the "views" feature. Only the getSupportedViews function is known to work. The requestNavigateTo function is known not to work. The other functions have not yet been tested, so may or may not work.

Restricting edit permissions on your gadget preferences

There is an Atlassian-specific extension to the views feature that allows you to restrict who can edit your gadget preferences. See Restricting Edit Permissions on your Gadget Preferences.

Feature name: views

Specified by: OpenSocial

In the above table we show the level of support provided in Atlassian Gadgets for each feature:

In the above table we have also categorised the features as follows:

Creating your Gadget XML Specification
Using the Atlassian Gadgets JavaScript Framework
Writing an Atlassian Gadget
Gadget Developer Documentation

Rate this page: