Using substitution variables and directives in your gadget

The Atlassian Gadgets framework allows you to specify substitution variables and #-directives in your gadget specification XML file that will be replaced by generated content at run time.

Substitution Variables

The Atlassian Gadgets framework supports the standard substitution variables as defined in the Google documentation on user preference substitution variables. These are variables like __UP_myuserpref__, in the attributes in the <ModulePrefs> and <UserPref> sections, where myuserpref matches the name attribute of a user preference.

In addition, the following Atlassian-specific substitution variables are available.

Atlassian Base URL Variable

At run time, this variable will be replaced with the base URL of the host application (e.g. JIRA) that is serving the URL.

Note that this only works with plugin gadgets, since the translation is done by the gadget publisher, not the renderer. (The renderer does the standard user pref and msg substitutions.)

**Format:**

1
2
__ATLASSIAN_BASE_URL__

Note: There is a double underscore at the beginning and at the end of the variable.

Example 1: Here is an HTML snippet from the <Content> section of your gadget XML specification using the __ATLASSIAN_BASE_URL__ variable:

1
2
<img src="__ATLASSIAN_BASE_URL__/download/resources/com.atlassian.jira.gadgets/loading.gif" height="35" width="35"/>

At run time, the above section of the gadget XML will be replaced with the following:

1
2
<img src="http://myhost.com:port/myapp/download/resources/com.atlassian.jira.gadgets/loading.gif" height="35" width="35"/>

Example 2: Here is a script snippet from the <Content> section of your gadget XML specification:

1
2
gadgets.io.makeRequest("__ATLASSIAN_BASE_URL__/rest/gadget/1.0/intro", response, params);

At run time, the above section of the gadget XML will be replaced with the following:

1
2
gadgets.io.makeRequest("http://myhost.com:port/myapp/rest/gadget/1.0/intro", response, params);

Directives

Our software (JIRA, FishEye etc) is packaged software that can be installed on customers' servers. We want our gadget developers to be able to write gadgets that can retrieve information from any server, rather than from a specific web service or URL. So we have developed a templating layer that sits on top of the gadget specification.

The Atlassian Gadgets framework allows you to specify #-directives in your gadget specification XML file that will be replaced by generated content at run time. These #-directives are provided by the Atlassian Gadget Publisher plugin. They work for any gadget that is provided as a plugin in an Atlassian application. The #-directives do not work for gadgets that are served from an external web server.

#-directives are sometimes also called 'macros' or 'pseudo-macros'.

Specific uses of \#-directives:

Internationalising your Gadget - #supportedLocales
Using Web Resources in your Gadget - #requireResource, #includeResources
Using the Atlassian Gadgets JavaScript Framework - #oauth, #supportedLocales, #requireResource, #includeResources

Creating your Gadget XML Specification
Writing an Atlassian Gadget
Gadget Developer Documentation