Jira provides the ability to display information about project/issues/data on a dashboard, through the use of gadgets. Gadgets are a big leap in JIRA reporting features.

In this document here I shall give instructions on how to write your first Jira gadget.
Before we start designing the gadget, we should know the key component of Jira gadgets:-

• GADGET.XML is the most important part of a Jira gadget. It holds the specification of the gadget, and includes the following:-
• Gadget Characteristics: It includes the title, description, and author’s name.Screenshot and thumbnail image: This is optional, so we can add it if we want. This is not used within Atlassian containers such as JIRA or CONFLUENCE.
  • Required features: we include it, to add some features in our Gadgets.
  • User preferences: this will be configured by gadget users.
  • The Gadget content is created using HTML and JavaScript.
• A screenshot and thumbnail image will be used during the preview and while selecting the gadget from the container.
• An i18n property file is used for internationalization in the gadget.
• Optional CSS and JavaScript file can be used to render the display in the content section of the gadget.

For writing your first gadget you will initially need to create a skeleton plugin using Atlassian Plugin SDK.

You can create your skeleton plugin by the help of the following link:- https://developer.atlassian.com/docs/common-coding-tasks/development-cycle/creating-a-plugin-skeleton-with-the-atlassian-sdk

After creating your skeleton plugin you need to perform the following steps to write your first Gadget:-

1. Modify your plugin descriptor with the Gadget module and resources.

-Add the Gadget Module in the plugin descriptor.

<gadget key=”jira-gadget” name=”Jira Gadget” location=”jira-gadget.xml”>
<description>Jira First Gadget</description>
</gadget>

-Add the resources in the plugin descriptor.

<!– add our web resources –>
<web-resource key=”Jira-Gadget-resources” name=”Jira-Gadget Web Resources”>  

<dependency>com.atlassian.auiplugin:ajs</dependency>
<resource type=”download” name=”Jira-Gadget.css” location=”/css/Jira-Gadget.css”/> <resource type=”download” name=”Jira-Gadget.js” location=”/js/Jira-Gadget.js”/>
<resource type=”download” name=”aui.css” location=”/css/aui.css”/>
<resource type=”download” name=”jquery-1.11.3.min.js” location=”/js/jquery-1.11.3.min.js”/>
<resource type=”download” name=”jquery-ui.js” location=”/js/jquery-ui.js”/>
<resource type=”download” name=”jquery-ui.min.js” location=”/js/jquery-ui.min.js”/> <resource type=”download” name=”images/” location=”/images”/>

<context>Jira-Gadget</context>
</web-resource>

2. To design the Gadget.XML file
The Gadget XML has a Module element at the root of the XML. It has mainly three child elements –

-ModulePrefs
-UserPref
-Content.

The entire set of attributes and elements and other details of the gadget specification can be read at https://developer.atlassian.com/display/GADGETS/Creating+your+Gadget+XML+Specification

a. To design the ModulePrefs element
This element holds information about the gadget. It has two child elements

-Require
-Optional

Anything that starts with __MSG_ and ends with __ is a property that is referred from the i18n properties file. The height of the gadget is optional and 200, by default. The images are referenced using #staticResourceUrl where the first argument is the fully qualified gadget module key and this is of the form ${atlassianplugin- key}:${module-key}. In our example, the plugin key is com.jtricks.gadgets and the module key is hello-gadget.
Add the optional gadget directory feature inside ModulePrefs. This is currently supported only in JIRA:

<Optional feature=”gadget-directory”>

<Param name=”categories”>
Other
</Param>

</Optional>

In the example, we can add the category as Other!
Other values supported for category are: JIRA, Confluence, FishEye, Crucible, Crowd, Clover, Bamboo, Admin, Charts, and External Content.
You can add the gadget to more than one category by adding the categories within the Param element (each in a new line).
Include Required features if there are any under the XML tag <require>. A full list of supported features can be found at http://confluence.atlassian.com/display/GADGETDEV/Including+Features+into+your+Gadget.
Add the Locale element to point to the i18n properties file:

<Locale messages=”__ATLASSIAN_BASE_URL__/download/resources/com.jtricks.gadgets/i18n/messages.xml/>

Here the property __ATLASSIAN_BASE_URL__ will be automatically substituted with JIRA’s configured base URL when the gadget is rendered. The path to the property file here is __ATLASSIAN_BASE_URL__/download/ resources/com.jira.gadgets, where com.jira.gadgets is the Atlassian plugin key. The path to the XML file /i18n/messages.xml is what is defined in the resource module earlier.

b. Add User Preferences if required, using the UserPref element. We will omit the same in this example as the ‘Jira Gadget’ doesn’t take any inputs from the user.

c. Add the Content for the gadget. This is where the gadget is rendered using HTML and JavaScript.

<![CDATA[ Write Your Text]]>
</Content>

Our gadget’s XML is now ready and looks like the following block of code:

Now let us deploy your plugin and test it.

How does it work?

After deploying your gadget you need to add your gadget on the dashboard screen. Go to the System Icon of Jira (Right top) and click on Add Gadget and search your gadget and add it.

I took help from the given link to write my first Jira Gadget:

https://www.packtpub.com/books/content/gadgets-jira,  https://developer.atlassian.com/display/GADGETS/Gadget+Developer+Documentation