Creating your gadget XML specification

This is the reference guide for the XML file you will write to define your Atlassian gadget.

Overview

A gadget is essentially an XML file containing the gadget specification. You will use recognised XML elements to define the following:

1. Gadget characteristics, such as the author's name (your name), the gadget title and description, preferred sizing, etc.
2. A screenshot and/or thumbnail image that containers can display to show users what your gadget looks like.
3. Required features that containers must provide for your gadget.
4. User preferences, where your gadget can allow its users to customise certain aspects of the gadget display.
5. The content section, where you can define the content that your gadget will display. This is where you add the HTML and JavaScript functions that produce your gadget's output.

Atlassian Gadgets and Google Gadgets

When writing an Atlassian gadget you may use additional XML elements, attributes and features that extend the Google gadgets XML specification.

On the page below, we give an overview of elements in the standard Google gadget specification that are supported by Atlassian gadgets. In cases where the Atlassian gadget specification differs from Google, we have added a comment like this:

(Comment about the difference in Atlassian gadgets.)

Example of an Atlassian Gadget XML Specification

Below is a truncated example of a gadget specification. You can also take a look at a longer example of a real gadget.

1
2
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="JIRA Issues" author_email="adent@example.com" directory_title="JIRA Issues"
      screenshot="http://labs.atlassian.com/svn/GADGETS/trunk/jira-issues/basic/jira-issues-screenshot.png" 
      thumbnail="http://labs.atlassian.com/svn/GADGETS/trunk/jira-issues/basic/jira-issues-thumbnail.png">
    <Require feature="minimessage" />
    <Optional feature="dynamic-height" />
  </ModulePrefs>
  <UserPref name="show_date" display_name="Show Dates?" datatype="bool" default_value="true"/>

  <UserPref name="show_summ" display_name="Show Summaries?" datatype="bool" default_value="true"/>
  <UserPref name="num_entries" display_name="Number of Entries:" default_value="5"/>
  <Content type="html">
     <![CDATA[ 
       Hello, world!
     ]]>
   </Content> 
</Module>

Module

This element indicates that the XML file contains a gadget. The element contains the entire gadget definition.

ModulePrefs

The <ModulePrefs> section specifies the gadget's characteristics, such as title, author, preferred sizing, and so on. Users who are viewing the gadget cannot change the values in this section.

You can use substitution variables, like __UP_myuserpref__, in the attributes in the <ModulePrefs> and <UserPref> sections, where myuserpref matches the name attribute of a user preference. See the Google documentation on user preference substitution variables.

Parent Element: Module

Example:

1
2
<ModulePrefs title="JIRA Issues" author_email="adent@example.com" directory_title="JIRA Issues"
    screenshot="http://labs.atlassian.com/svn/GADGETS/trunk/jira-issues/basic/jira-issues-screenshot.png" 
    thumbnail="http://labs.atlassian.com/svn/GADGETS/trunk/jira-issues/basic/jira-issues-thumbnail.png">
  <Require feature="minimessage" />
  <Optional feature="dynamic-height" />
</ModulePrefs>

Attributes:

*All the attributes above are optional.

Require

The <Require> element instructs the container that the gadget needs a specific feature to be provided by the container.

Parent Element: Module/ModulePrefs

Example:

1
2
<Require feature="minimessage" />
<Require feature="dynamic-height" />

Attributes:

• feature- The name of the feature that the gadget requires. See our guide to including features into your gadget. Required.

Optional

The <Optional> element instructs the container that the gadget can make use of a specific feature, if the container is able to provide it.

Parent Element: Module/ModulePrefs

Example:

1
2
<Optional feature="dynamic-height" />

Attributes:

• feature - The name of the feature that the gadget will use if provided by the container. See our guide to including features into your gadget. Required. 

Param Element

The <Param> element allows you to supply parameters for features requested via the <Require> or <Optional> elements.

Parent Element: Module/ModulePrefs/Optional and Module/ModulePrefs/Require

Example:

1
2
<Optional feature="gadget-directory">
  <Param name="categories">
    JIRA
    Charts
  </Param>
</Optional>

Attributes:

• name- A name-value pair giving the parameter and its value. You can read more about the <Param> element in the Google Gadgets XML Reference. Required.

Preload Element

The <Preload> element instructs the container to fetch data from a remote source during the gadget rendering process.

Parent Element: Module/ModulePrefs

The Atlassian usage of this element is identical to the usage described in the Google Gadgets XML Reference.

Icon Element

This attribute is not referenced by Atlassian Gadgets. 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.

The <Icon> element specifies a 16x16 pixel image that containers can associate with a particular gadget.

Parent Element: Module/ModulePrefs

Locale Element

The <Locale> element specifies the locales supported by your gadget. For more information, please refer to the page on internationalising your gadget.

Parent Element: Module/ModulePrefs

Link Element

This attribute is not referenced by Atlassian Gadgets. 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.

The <Link> element specifies a container-specific link. For example, a container may link to your gadget to provide online help.

Parent Element: Module/ModulePrefs

OAuth Element and its Children

The <OAuth> element specifies your gadget's use of the OAuth protocol for authentication. For more information on this element and its child elements, please refer to the page on user authentication for gadgets.

Parent Element: Module/ModulePrefs

Child Elements: Service, Request, Access and Authorization -- Please refer to the page on user authentication for gadgets.

UserPref Element

The <UserPref> section allows your gadget to give users a way of supplying their preferences and other user-specific information, called 'user preferences'. These user input fields are turned into user interface controls when the gadget runs. When the gadget is displayed on iGoogle, the user preferences are accessible from the 'Edit settings' dropdown menu. In Atlassian gadgets, the menu option is 'Edit'.

As a gadget developer, you are entirely free to choose the user preference name.

The container handles generation of the configuration UI, saves the settings and provides an API to access the settings in JavaScript.

For example, a gadget that displays a list of JIRA issues may allow the user to choose whether to display the issue summaries and to specify how many issues should be displayed.

You can use substitution variables, like __UP_myuserpref__, in the attributes in the <ModulePrefs> and <UserPref> sections, where myuserpref matches the name attribute of a user preference. See the Google documentation on user preference substitution variables.

**Parent Element:** [Module](#module)

Example:

1
2
<UserPref name="show_summ" display_name="Show Summaries?" datatype="bool" default_value="true"/>
<UserPref name="num_entries" display_name="Number of Entries:" default_value="5"/>

Attributes:

*name attribute is required. Other are optional.

Enum Element

The <Enum> element allows you to specify enumerated values for your user preference, when you have given a datatype of enum.

Parent Element: Module/UserPref

The Atlassian usage of this element is identical to the usage described in the Google Gadgets XML Reference.

Content Element

The <Content> section is where it all happens!

In this section, you will define the type of content, and either include the content itself or provide a URL to pull in the content from an external source. You will combine the attributes and user preferences with programming logic and formatting information to make the gadget do what you want it to do.

There are two main types of gadget content, distinguished by the type attribute of the <Content> element.

Type url gadgets include content from a remote site, but do not have full access to features of the container. This type of gadget is supported for compatibility with existing legacy iGoogle gadgets, but is considered deprecated and should generally be avoided when creating new gadgets.

Type html gadgets include the content directly inside the <Content> element. This includes all of the HTML, CSS, and JavaScript code that the container will render in the gadget's iframe. This content must be enclosed in a CDATA section to avoid having the gadget specification parser interpret the embedded HTML markup as XML. For a guide to the JavaScript functionality available, please refer to our JavaScript API reference guide and the Gadgets API Reference.

Parent Element: Module

Example:

1
2
<Content type="html">
  <![CDATA[ 
    <strong>Hello, world!</strong>
  ]]>
</Content> 

Attributes:

*href attribute is required for type = "url", and not allowed for other content types. Other are optional.

RELATED TOPICS

Writing an Atlassian Gadget

Gadget Developer Documentation