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.

On this page:

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

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

<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">
  <!--[if IE]>
  <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?ieonly=true"
    media="all">
  <![endif]-->
  <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>

RELATED TOPICS

Creating your Gadget XML Specification
Writing an Atlassian Gadget
Gadgets and Dashboards Development Hub