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:

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>

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:

Fully supported -- Atlassian Gadgets provides full support for this feature. It will work on an Atlassian container.
Partially supported -- Atlassian Gadgets supports some of the functionality provided by this feature. The table above tells you which aspects are supported.
Not referenced -- Atlassian Gadgets does not make use of this feature, so it will have no effect on an Atlassian container. You may include the feature in your gadget if you want it to be used in other containers.
Not supported -- Atlassian Gadgets does not support this feature and your gadget will not work on an Atlassian container if you <Require> the feature. To use the feature in containers where it is available while still remaining compatible with Atlassian Gadgets, you must use the <Optional> element to specify the feature, then test for the presence of the feature using the gadgets.util.hasFeature function.

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

Specified by OpenSocial -- Most features are described in the OpenSocial JavaScript API.
Specified by Atlassian Gadgets -- Additional features are provided specifically by the Atlassian Gadgets framework. These features will work on an Atlassian Gadgets container but probably not on another OpenSocial container.

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