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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?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
3
4
5
6
<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:

title

The title of the gadget. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

Refer also to the directory_title attribute below.

title_url

If you specify this value, the gadget title will link to this URL. This is a standard Google gadget attribute.

See the Google Gadgets XML Reference.

description

A description of the gadget. This is a standard Google gadget attribute.

See the Google Gadgets XML Reference.

author

Your name, as creator of the gadget. This is a standard Google gadget attribute.

See the Google Gadgets XML Reference.

author_email

Your email address, as creator of the gadget. This is a standard Google gadget attribute.

See the Google Gadgets XML Reference.

screenshot

The address of an image that a container or directory can use to illustrate the gadget.

This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

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.

 

thumbnail

The address of a thumbmail image (120×60 pixels) that a container or directory can use to illustrate the gadget.

This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

directory_title

The name of the gadget as it should appear in the gadget directory.

If the value of your title attribute contains user preference substitution variables (like __UP_userpref__),

then you will supply a plain text value in the directory_title attribute.

See the Google documentation on user preference substitution variables.

*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:

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
<Optional feature="dynamic-height" />

Attributes:

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
3
4
5
6
<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 16×16 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

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

The name of the user preference. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

display_name

The text displayed next to the preference input field. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

urlparam

The string to pass as the parameter name for content type=”url”. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

datatype

The data type of this attribute. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

required

Boolean argument (true or false) indicating whether this user preference is required. The default is false. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

default_value

A default value for the user preference. This is a standard Google gadget attribute. See the Google Gadgets XML Reference.

*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
3
4
5
<Content type="html">
  <![CDATA[ 
    <strong>Hello, world!</strong>
  ]]>
</Content> 

Attributes:

type

The type of content. The possible values are html and url. The default is html.

href

String that provides a destination URL.

view

The container view in which this content should be displayed. Gadgets can define multiple content sections, each with a different view. The views supported by Atlassian containers are default for the standard view of a gadget on a page alongside other gadgets and content, and canvas for the maximised view of a single gadget on a page by itself. Other containers may support additional view types. If the same content section should be displayed in more than one view, you can specify multiple views, separated by commas.

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

Writing an Atlassian Gadget

Gadget Developer Documentation

Source Article