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.
<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.
<?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. ![]()
29 Comments
Roger
5/4/2011 08:52:37 am
Hi J-Tricks,
Reply
J-Tricks
5/4/2011 08:58:29 am
You can put gadgets only into a Gadget container. JIRA's dashboard is an Opensocial gadget container. Other classic examples are iGoogle, Gmail etc.
Reply
sudhir
10/5/2011 04:32:03 am
Hi J-Tricks,
Reply
J-Tricks
10/5/2011 09:03:58 am
@Sudhir Unfortunately, that is not possible. See https://jira.atlassian.com/browse/JRA-20167 for details.
Reply
Mark DeMichele
2/15/2012 01:30:04 pm
I'm trying to write a stand alone gadget. That is a gadget that doesn't require a plugin. Making a hello world type is easy, but I want to make one that makes a rest call on the target jira site and I can't seem to figure out how. Do you have any advice on that?
Reply
J-tricks
2/15/2012 01:53:39 pm
Some basics are discussed in this post : http://www.j-tricks.com/1/post/2011/04/invoking-rest-services-from-gadgets.html
Reply
Mark DeMichele
2/15/2012 02:08:41 pm
But that's for Gadgets that require a plug-in not stand alone ones. For instance thing like __ATLASSIAN_BASE_URL__ are no available if you don't use a plug-in.
J-Tricks
2/15/2012 02:20:27 pm
@Mark But isn't that the only thing that is not available? You can replace that with the actual baseURL.
Reply
Mark DeMichele
2/16/2012 12:06:06 am
A stand alone gadget is one that you don't use a plugin and you just us e Javascript/Html and CSS inside the xml file and you host the xml file on another server (https://developer.atlassian.com/display/JIRADEV/Standalone+Gadget+Tutorial+-+Writing+a+JQL+Gadget).
Reply
J-tricks
2/16/2012 12:59:51 am
Got you! I am afraid I haven't tried it before but looks like the example is using OAuth. Maybe you can try it out!
Sebastian
6/1/2012 03:38:57 am
Hi,
Reply
J-Tricks
6/1/2012 03:51:54 am
I have posted an answer to your question in Answers. Hope it helps :)
Reply
Andris
7/20/2012 12:35:36 am
I seem to have some problems with making this gadget appear on the list of gadgets once plugin is deployed (It works if I add it manually using the xml file). Do I need to do something more for JIRA 5 to make it appear? Also, is finished source code of this tutorial available somewhere, so I could compare, what I've done wrong? Thanks
Reply
J-Tricks
7/20/2012 12:25:45 pm
Actually, all the files are exactly same as what is given above. If you can upload your plugin somewhere, we are happy to have a look.
Reply
Andris
7/22/2012 07:25:43 pm
I uploaded it here: http://www.2shared.com/file/nbjWjxmY/hello-gadget.html
J-Tricks
7/24/2012 04:44:00 am
It started working for me once I put a double quotes around email. Try that!
srikanth
8/21/2012 12:04:45 am
where should i need to place my gadget.xml file in order to appear it in jira gadget directory and also how to give url to the xml
Reply
J-Tricks
8/21/2012 02:34:58 am
Put it under resources in your plugin and give the relative path in the location attribute of gadget definition in the atlassian-plugin.xml.
Reply
9/20/2012 11:36:29 pm
You have really helped several of individuals like me, who have been searching internet from past quite a long time to find detailed information on this particular topic. Thanks a ton.
Reply
J-Tricks
9/21/2012 01:43:17 am
Glad you found it useful. Cheers :)
Reply
9/20/2012 11:47:10 pm
Great piece of writing, I really liked the way you highlighted some really important and significant points. Thanks so much, I appreciate your work.
Reply
3/31/2013 11:50:56 pm
Plug-ins is added on programs that increases the extension of a program. The young professionals from j-tricks develop plug-ins for JIRA. The open source plug-ins you provided is very useful and increases the program’s performance. It is very glad to hear that you are partner of Go2Group.
Reply
J-Tricks
4/4/2013 01:01:43 am
Is the plugin successfully installed? Are you able to find it under UPM, with all the modules enabled? If so, any error in the logs?
Reply
Jayashree
4/15/2014 04:13:57 pm
Hi. I am also facing the similar problem. No errors but the gadget doesnot appear in the other's directory. Also i have tried the invoking of rest, i end up getting some resource related error.<Locale? message doesnot work.i want to use REST 2.0 what changes needs to be done. Can you please update the REST code JIRA4 gadgets since it has some error when i try to run it
Reply
J-Tricks
4/25/2014 09:06:36 am
Jayashree,
Reply
Jayashree
4/28/2014 10:55:28 pm
Thank you , it worked :)
Jayashree
5/7/2014 05:14:45 pm
Hi Jobin, can you post the implementation of gadget with rest service displaying the projects in jira as a select list?
Reply
John McGahlot
4/21/2015 07:37:14 pm
how to generate the config form again and again to select multiple projects on the click of a check box
Reply
Your comment will be posted after it is approved.
Leave a Reply. |
AuthorJobin Kuruvilla - Works in Adaptavist as Head of DevOps Professional Services. Categories
All
Archives
October 2016
|