Packaging your gadget as an Atlassian plugin

This page tells you how to add your gadget to an Atlassian application (JIRA, Confluence, etc) as a plugin.

In short: Add a <gadget> module type to your atlassian-plugin.xml file.

Standalone Gadget or Plugin?

How feasible is it to create an Atlassian gadget that consists purely of HTML, CSS and Javascript? Assuming that the Confluence or JIRA (or whatever) REST API could do everything that the gadget needs, can you bypass the plugin side of things altogether?

You can choose to write a standalone gadget or a gadget embedded in a plugin.

A standalone gadget consists entirely of HTML, CSS and Javascript, all contained within the gadget XML file. To retrieve data from an application, you can use a REST API, for example.
Alternatively you can write a gadget and a plugin, and embed the gadget into the plugin XML using the gadget plugin module. The plugin needs to be installed into the Atlassian application, such as JIRA or Confluence.

Limitations if you do not embed your gadget in a plugin:

You will not be able to use #-directives. This means that, if your gadget is requesting data from an Atlassian application, the gadget can only access a single, specific instance of that application because you will need to hard-code the base URL.
It is significantly more difficult to use the Atlassian Gadget JavaScript Framework, because you will need to code everything that is normally automatically generated by the #supportedLocales and #includeResources directives.

That said, there are two main reasons why you may be interested in writing standalone gadgets:

It is a much simpler way to write very basic gadgets. This provides an easier way to learn how to write gadgets.
A non-plugin gadget may be sufficient if your gadget is for your own company's internal use with a single Atlassian application/site.
You may want to write gadgets that request data from some non-Atlassian system or web service, in order to integrate that data into an Atlassian application such as JIRA or Confluence.

Embedding your Gadget into a Plugin

The rest of this page describes the gadget module type that you will use to embed your gadget within an Atlassian plugin.

Prerequisites

Your version of the Atlassian application must support gadgets. See the gadget version compatibility matrix.
Your version of the Atlassian application must support the Atlassian Plugin Framework version 2.2 or later. See the plugin framework version compatibility matrix.
Your plugin must be an OSGi-based plugin, as supported by the Atlassian Plugin Framework.
You will need to install the REST plugin module type, if not already bundled with the application.

Purpose of the Gadget Module Type

Gadget plugin modules enable you to add your gadget to an Atlassian application (JIRA, Confluence, etc) as a plugin. Your gadget can then make use of the application's remote API to fetch data and interact with the application.

Configuration

The element for the Gadget plugin module is gadget. It allows the following attributes for configuration:

Attributes

**key **- The key attribute is a standard module key, so it is required and must be unique within the plugin across all module types. Required.
**location **- The location attribute can be either the relative path to a resource within the plugin, or the absolute URL of an externally-hosted gadget. Required.
publish-location - As of 3.4: The publish-location attribute is used to replace the default URL of published gadgets. See URL for Published Gadgets below.

Elements

enabled-conditions - As of 3.5: Contains a list of condition or conditions that must be satisfied to make the gadget available for use within the system. Conditions defined under enabled-conditions are always evaluated by the gadget system without any context.
**local-conditions ** - As of 3.5: Contains a list of condition or conditions that must be satisfied for the gadget to be displayed in various pages within products. For example, dashboard in JIRA. Conditions defined under local-conditions are evaluated by the individual products with product specific context. If a product does not evaluate these conditions, then these conditions will not have any effect in the system.

Example

The syntax of the module type is:

1
2
<atlassian-plugin name="Hello World" key="example.plugin.helloworld" plugins-version="2">
  <plugin-info>
    <description>A basic gadget module</description>
    <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
    <version>1.0</version>
  </plugin-info>

  <gadget key="unique-gadget-key" location="path/to/gadget.xml" 
          publish-location="my-custom-context/custom/location/gadget.xml">
    <enabled-conditions>
       <condition class="com.atlassian.plugin.awesome.MyEnabledCondition"/>
    </enabled-conditions>
    <local-conditions>
       <conditions type="OR">
         <condition class="com.atlassian.plugin.awesome.MyLocalCondition" />
         <condition class="com.atlassian.plugin.awesome.MyInvertedLocalCondition" inverted="true" />
       </conditions>
    </local-conditions>
 
  </gadget>
</atlassian-plugin>

URL for Published Gadgets

Gadgets published by an Atlassian container (such as JIRA or Confluence) are provided by the REST plugin module built into the Atlassian Gadgets framework. The URL of published gadgets has the following format:

1
2
http://my-server.com:port/my-context/rest/gadgets/1.0/g/my-plugin.key:my-gadget/my-path/my-gadget.xml

As of 3.4, gadgets may be published under a customised path if the default path is undesirable using the publish-location attribute.

Example:

Using the default path:

1
2
http://mycompany.com/jira/rest/gadgets/1.0/g/com.atlassian.streams.streams-jira-plugin:activitystream-gadget/gadgets/activitystream-gadget.xml

Using the customised path. A gadget module such as the following:

1
2
<gadget key="activitystream-gadget" location="gadgets/activitystream-gadget.xml" publish-location="activitystream/gadgets/gadget.xml" />

Will be published under the URL below:

1
2
http://mycompany.com/jira/rest/gadgets/1.0/g/activitystream/gadgets/gadget.xml

Creating your Gadget XML Specification
Writing an Atlassian Gadget
REST Plugin Module