Writing JIRA4 Gadgets

Gadgets are a big leap in the JIRA reporting feature! The fact that JIRA is now an OpenSocial container lets its user add useful Gadgets, both JIRA's own and third-party, into its dashboard. At the same time gadgets written for JIRA can be added in other containers like iGoogle, Gmail etc!

Let us have a look at writing a very simple gadget, one that says 'Hello from JTricks'. By keeping the content simple, it will let us concentrate more on writing the gadget!

Before we start writing the gadget, it is probably worth to understand the key components of a JIRA gadget.

1. Gadget XML : This is the most important part of a JIRA Gadget. This holds the specification of the gadget and includes the following:
   
   a. Gadget Characteristics. It includes title, description, author's name etc
   b. Screenshot and a thumbnail image. Please note that the screenshot is not used within Atlassian Containers like JIRA or Confluence. We can optionally add it if we want them to be used in other Opensocial containers.
   c. Required features that the Gadget container must provide for the gadget.
   d. User preferences which will configured by the gadget users
   e. The Gadget Content created using HTML and JavaScript
   
2. A Screenshot and thumbnail image. These will be used during preview and while selecting the gadget from the container.
3. An i18n property file used for internationalization in the Gadget
4. Optional CSS and Javascript files used to render the display in the Content section of the gadget

As usual, have your skeleton plugin ready. The first step obviously is to modify the plugin descriptor with the gadget module and the resources required for our gadget.

• Add the Gadget module in the plugin descriptor.
  
  <gadget key="hello-gadget" name="Hello Gadget" location="hello-gadget.xml">
       <description>Hello Gadget! </description>
  </gadget>
  
  As you can see, this has a unique key and points to the location of the gadget XML! You can have as many gadget definitions as you want in your atlassian-plugin.xml but in our example we stick with the one above.
• Include the thumbnail and screenshot images as downloadable resources in the plugin descriptor. We have seen details on this in previous chapter and more can be learned here. In our example, the resources are added on to the plugin descriptor as:
  
  <resource name="screenshot.png" location="/images/screenshot.png"/>
  <resource name="thumbnail.png" location="/images/thumbnail.png"/>
  
  The location is relative to the src/main/resources folder in the plugin. As mentioned before, screenshot is optional.
• Add the i18n properties file that will be used in Gadget also as a downloadable resource.
  
  <resource name="i18n/messages.xml" location="i18n/messages.xml">
      <param name="content-type" value="text/xml; charset=UTF-8"/>
  </resource>

The atlassian-plugin.xml will now look like this:

    <atlassian-plugin key="com.jtricks.gadgets" name="Gadgets Plugin" plugins-version="2">
        <plugin-info>
            <description>Gadgets Example</description>
            <version>2.0</version>
            <vendor name="JTricks" url="http://www.j-tricks.com/" />
        </plugin-info>
        <gadget key="hello-gadget" name="Hello Gadget" location="hello-gadget.xml">
            <description>Hello Gadget!</description>
        </gadget>

        <resource name="screenshot.png" location="/images/screenshot.png"/>
        <resource name="thumbnail.png" location="/images/thumbnail.png"/>

        <resource name="i18n/messages.xml" location="i18n/messages.xml">
            <param name="content-type" value="text/xml; charset=UTF-8"/>
        </resource>
    </atlassian-plugin>

We now need to add the screenshot and thumbnail images under the src/main/resources/images folder. The thumbnail image should be of the size 120x60 pixels. We should also add the i18n properties file under the src/main/resources/i18n folder. The name of the filer we defined is messages.xml.

This file is an XML file en-wrapped within the messagebundle tag. Each property in the file is entered as an XML tag as shown below:

<msg name="gadget.title">Hello Gadget</msg>

The msg tag has a name attribute which is the property and the corresponding Value is enclosed in the msg tag. We use three properties in our example and the entire file in our example looks like the following:

<messagebundle>
    <msg name="gadget.title">Hello Gadget</msg>
    <msg name="gadget.title.url">http://www.j-tricks.com</msg>
    <msg name="gadget.description">Example Gadget from J-Tricks</msg>
</messagebundle>

Now the time has come to write he Gadget XML!

The Gadget XML has a Module element at the root of the XML. It has mainly 3 elements underneath - ModulePrefs, UserPref and Content. We will write of each of them in this example. The entire set of Attributes and Elements and other details of the Gadget Specification can be read here.

• Write the ModulePrefs element. This element holds the information about the Gadget. It also has two child elements - Require and Optional that are used to define required or optional features for the gadget.
  
  Following is how the ModulePrefs element looks in our example after populated with all the attributes:
  
  <ModulePrefs title="__MSG_gadget.title__" title_url="__MSG_gadget.title.url__"
  description="__MSG_gadget.description__" author="Jobin Kuruvilla" author_email="jobinkk@gmail.com"        screenshot='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "screenshot.png")'
  thumbnail='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "thumbnail.png")' height="150"  >
  </ModulePrefs>
  
  As you can see, it holds information like title, title URL (to which the gadget title will link to), description, author name and email, height of the gadget and URLs to screenshot and thumbnail images.
  
  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 which is of the form ${atlassian-plugin-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 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. A full list of supported features can be found here .
• 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.jtricks.gadgets where com.jtricks.gadgets is the atlassian plugin key. The path to XML /i18n/messages.xml is what is defined in the resource module earlier.
• Add User Preferences if required, using the UserPref element. We will omit the same in this example as the 'Hello Gadget' doesn't take any inputs from the user.
• Add the Content for the gadget. This is where the gadget is rendered using HTML and JavaScript. In our example, we just need to provide the static text 'Hello From JTricks' and it is fairly easy.
  
  The entire content is wrapped within the <![CDATA[ and ]]> so that they won't be treated as XML tags. Following is how it looks in our example:
  
  <Content view="profile">
      <![CDATA[ Hello From JTricks ]]>
  </Content>

Our Gadgets XML is now ready and looks like the following:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
    <ModulePrefs title="__MSG_gadget.title__" title_url="__MSG_gadget.title.url__" description="__MSG_gadget.description__" author="Jobin Kuruvilla" author_email="jobinkk@gmail.com" screenshot='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "screenshot.png")'  thumbnail='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "thumbnail.png")' height="150" >
        <Optional feature="gadget-directory">
            <Param name="categories">
                Other
            </Param>
        </Optional>
        <Locale messages="__ATLASSIAN_BASE_URL__/download/resources/com.jtricks.gadgets/i18n/messages.xml"/>
    </ModulePrefs>
    <Content view="profile">
        <![CDATA[ Hello From JTricks ]]>
     </Content>
</Module>

All we need to do now is to package the plugin and deploy it.

Once the plugin is deployed, we need to add the gadget in the JIRA dashboard. Following is how it appears in the Add Gadget screen. Note the thumbnail is the one we have in the plugin and also note that it appears in the Other section.

Once it is added, it appears like the following in the Dashboard.

There it is! Our little Gadget!! If you think it doesn't look pretty, we can modify the look and feel of the gadgets by adding more HTML or Gadget preferences! For example:

<font color="red">Hello From JTricks</font> will make it appear in red!

We can adjust the size of the gadget using the dynamic-height feature. We should add the following under ModulePrefs element.

<Require feature="dynamic-height"/>

We should then invoke gadgets.window.adjustHeight(); whenever the content is reloaded. For example, we can do it in a window onload event like this:

                <script charset="utf-8">
                                function resize()
                                {
                                                gadgets.window.adjustHeight();
                                }
                                window.onload=resize;
                </script>

The gadget xml in this case will look like this:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
    <ModulePrefs title="__MSG_gadget.title__"
                 title_url="__MSG_gadget.title.url__"
                 description="__MSG_gadget.description__"
                 author="Jobin Kuruvilla"
         author_email="jobinkk@gmail.com"
                 screenshot='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "screenshot.png")'
                 thumbnail='#staticResourceUrl("com.jtricks.gadgets:hello-gadget", "thumbnail.png")'
         height="150"
                 >
        <Optional feature="gadget-directory">
            <Param name="categories">
            Other
        </Param>
        </Optional>
    <Require feature="dynamic-height"/>
    <Locale messages="__ATLASSIAN_BASE_URL__/download/resources/com.jtricks.gadgets/i18n/messages.xml"/>
    </ModulePrefs>
    <Content view="profile">
        <![CDATA[
    <script charset="utf-8">
        function resize()
        {
        gadgets.window.adjustHeight();
        }
    window.onload=resize;
    </script>
    Hello From JTricks
        ]]>
    </Content>
</Module>

The Gadget should now appear like this:

Well, that is only an example of what we can do! Learn about more of those at Atlassian Gadget Devlopment pages. Watch this space for more on invoking REST services from Gadgets and thus rendering dynamic content.

gadget-extended-plugin.zip
File Size:	20 kb
File Type:	zip

Download File

---