Using web resources in your gadget

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'.

You can use these \#-directives to specify web resources needed by your gadget.

`#requireResource` and `#includeResources` Directives

The #requireResource and #includeResources directives work with the WebResourceManager as used in JIRA (see JIRA web resources), Confluence (see Confluence web resources) and other Atlassian applications. In turn, the WebResourceManager uses the Web Resource Plugin Module type defined in the Atlassian Plugin Framework.

The #-directives correspond directly to the requireResource and includeResources methods in WebResourceManager.

You can include multiple #requireResource directives.

The gadget processor proceeds as follows:

When the gadget processor finds a #requireResource directive, it adds the specified resource to a list.
When the gadget processor finds a #includeResources directive, it processes the list of web resources:
- First it resolves dependencies transitively (since web resources can depend on other web resource modules, potentially in another plugin, which can themselves depend on other web resource modules, etc).
- Then it eliminates any duplicates from the fully resolved list.

For example, if my gadget has both #requireResource("com.atlassian.gadgets:common-resources") and #requireResource("com.atlassian.gadgets.mygadget:mygadget-resources"), and both of those have a dependency on com.atlassian.auiplugin:ajs, the gadget processor will only include AJS once.

Parent Element:
<Content>

Format of #requireResource:
#requireResource("plugin.key:module-key") Each #requireResource directive names the complete module key (plugin.key:module-key) for a web-resource plugin module.

Format of #includeResources:
#includeResources()

Example:
Here is a snippet of gadget XML using the #requireResource directive to include the Atlassian Gadgets JavaScript framework, as used in JIRA 4.0 (see Using the Atlassian Gadgets JavaScript Framework for details, including how to use it if you are not writing a gadget for JIRA 4.0):

1
2
<Content type="html">
<![CDATA[
  #requireResource("com.atlassian.jira.gadgets:common")
  #includeResources()

  <div id="intro-content">
    Hello, world
  </div>
]]>
</Content>

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

1
2
<Content type="html">
<![CDATA[
  <link type="text/css" rel="stylesheet"
    href="http://myhost.com:port/myapp/s/448/1/1.1.7/_/download/batch/com.atlassian.auiplugin:ajs/com.atlassian.auiplugin:ajs.css"
    media="all">
  <script type="text/javascript"
    src="http://myhost.com:port/myapp/s/448/1/1.1.7/_/download/batch/com.atlassian.auiplugin:ajs/com.atlassian.auiplugin:ajs.js" ></script>
  <script type="text/javascript"
    src="http://myhost.com:port/myapp/s/448/1/4.0.0/_/download/batch/com.atlassian.jira.gadgets:common/com.atlassian.jira.gadgets:common.js" ></script>
  <link type="text/css" rel="stylesheet"
    href="http://myhost.com:port/myapp/s/448/1/4.0.0/_/download/batch/com.atlassian.jira.gadgets:common/com.atlassian.jira.gadgets:common.css"
    media="all"/>

  <div id="intro-content">
    Hello, world
  </div>
]]>
</Content>

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