Including Features into your Gadget

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:

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

Here is a simple example:

<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?	Feature Name	説明	Specified by OpenSocial or Atlassian Gadgets?
Fully supported	atlassian.util	Allows a gadget to retrieve the base URL for the renderer server. Example: <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.	Atlassian Gadgets
サポート対象外	analytics	Google Analytics	OpenSocial
サポート対象外	caja	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.	OpenSocial
Not referenced	content-rewrite	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: <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.	OpenSocial
Fully supported	core.io	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.	OpenSocial
Fully supported	core	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.	OpenSocial
Fully supported	dynamic-height	Gives a gadget the ability to resize itself. Format: <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.	OpenSocial
Fully supported	flash	Allows you to embed a Flash movie into your gadget. Format: <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.	OpenSocial
Fully supported	gadget-directory	Allows a gadget to specify details for its directory listing, such as the category in which the gadget should be listed. Format: <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.	Atlassian Gadgets
サポート対象外	locked-domain		OpenSocial
Fully supported	minimessage	A MiniMessage is a temporary message displayed to users from within a gadget. Format: <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.	OpenSocial
Fully supported	oauthpopup	Manages popup windows for OAuth. See our detailed instructions on OAuth and the OpenSocial `gadgets.oauth.Popup` API reference.	OpenSocial
サポート対象外	opensocial-0.6		OpenSocial
サポート対象外	opensocial-0.7		OpenSocial
サポート対象外	opensocial-current		OpenSocial
サポート対象外	opensocial-reference		OpenSocial
サポート対象外	opensocial-templates		OpenSocial
Fully supported	rpc	Provides operations for making remote procedure calls for gadget-to-container, container-to-gadget, and gadget-to-gadget communication. Format: <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.	OpenSocial
Fully supported	setprefs	Allows you to set the values for user preferences programmatically, without the user's direct participation. Format: <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.	OpenSocial
Fully supported	settitle	Allows you to set your gadget's title programmatically. Format: <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.	OpenSocial
Not referenced	skins	Allows you to manage the skin of your gadget programmatically. Format: <ModulePrefs title="My Gadget"> <Require feature="skins"/> </ModulePrefs> See the OpenSocial `gadgets.skins` API reference.	OpenSocial
Fully supported	タブ	Allows you to add a tabbed user interface to your gadget. Format: <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.	OpenSocial
Partially supported	views	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: <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. 部分的にサポート 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.	OpenSocial
サポート対象外	pubsub	Allows your gadget to publish and subscrib to message channels. See the OpenSocial `gadgets.pubsub` API reference.	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.

すべてのバージョン

Gadgets 1.0 Documentation

Child pages

Using a Feature in your Gadget

List of Features

関連トピック