Gadgets and Dashboards 2.0 : Creating your Gadget XML Specification
This page last changed on Sep 14, 2009 by tmoore.
This is the reference guide for the XML file you will write to define your Atlassian gadget. On this page:
OverviewA gadget is essentially an XML file containing the gadget specification. You will use recognised XML elements to define the following:
Atlassian Gadgets and Google GadgetsWhen 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:
Example of an Atlassian Gadget XML SpecificationBelow is a truncated example of a gadget specification. You can also take a look at a longer example of a real gadget. <?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 ElementThis element indicates that the XML file contains a gadget. The element contains the entire gadget definition. ModulePrefs ElementThe <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: <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:
Require ElementThe <Require> element instructs the container that the gadget needs a specific feature to be provided by the container. Parent Element: Module/ModulePrefs Example: <Require feature="minimessage" /> <Require feature="dynamic-height" /> Attributes:
Optional ElementThe <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: <Optional feature="dynamic-height" /> Attributes:
Param ElementThe <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: <Optional feature="gadget-directory"> <Param name="categories"> JIRA Charts </Param> </Optional> Attributes:
Preload ElementThe <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
The <Icon> element specifies a 16x16 pixel image that containers can associate with a particular gadget. Parent Element: Module/ModulePrefs Locale ElementThe <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
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 ChildrenThe <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 ElementThe <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 Example: <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:
Enum ElementThe <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 ElementThe <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: <Content type="html"> <![CDATA[ <strong>Hello, world!</strong> ]]> </Content> Attributes:
RELATED TOPICSWriting an Atlassian Gadget |
![]() |
Document generated by Confluence on Nov 22, 2009 17:46 |