Gadgets and JIRA portlets

This page compares JIRA portlets with gadgets.

What's Changed

From a user's perspective...

In JIRA versions prior to 4.0, you could configure your dashboard by adding portlets. In JIRA 4.0 and later, portlets have been converted to industry-standard gadgets.

From a developer's perspective...

In the portlets world, you do everything server-side (on the server where the data is held) and use your portlet class and your Velocity templates to render the UI.

In the gadgets world, the UI is rendered entirely using HTML and JavaScript (on the dashboard server). To get dynamic data into the gadget, you will make Ajax calls using makeRequest back to the originating server.

Why a special API for making requests? When we render gadgets, even if the gadget specification is coming from your server out there, it is pulled into the dashboard server and parsed and rendered into HTML on the dashboard server. So your JavaScript can only talk to the server where the dashboard is running. The makeRequest call will proxy back (in a process that is called 'phoning home') to the originating server to request data, using one of the following:

• The REST APIs that the application already supports.
• A custom servlet that you build in a plugin for that product.
• A custom REST plugin module. This is the recommended option.

Here is a summary of the difference between gadgets and portlets, from the perspective of a JIRA portlet developer:

• With gadgets you will not have to write any Java, unless you need to create a new REST API.
• All you need to do is write the gadget specification file and deploy it into JIRA. That's it.
• If you need to access internal data for reporting, have customised APIs, etc, you will be able to access those as well.
• The container handles a lot of stuff for you, such as:
  • HTTP caching.
  • Rendering the content to the browser.
• You will write JavaScript to make a request to the remote APIs, to grab the data and populate the content. This replaces the Java code you need to write for a portlet, that populates a Velocity template, context etc.

JIRA Portlet-to-Gadget Bridge

We have built a bridge so that you do not have to convert all the JIRA portlets to gadgets right away. Instead, you can use the bridge to display your existing portlet's output on your JIRA gadgets dashboard.

The bridge will not work for all the portlets. Some portlets contain advanced Ajax functionality that will not be pulled into the gadget properly. But you should be able to make backwards-compatible changes to most portlets that will allow them to work in the bridge as well as in older versions of JIRA.

Note: The bridge is applicable to existing portlets only and is an interim solution. Such legacy portlets can run only on:

• JIRA dashboards, not iGoogle or Confluence or other OpenSocial containers.
• The gadget's local instance of JIRA, i.e. the portlet cannot pull information from another JIRA installation, as a gadget can

Converting a JIRA Portlet to a Gadget

There are three options for converting a portlet to a gadget:

1. Use the legacy bridge described GADGETDEV:above.

   • Pros: Easy (should just work automatically); can deploy one plugin to older JIRA versions as well as JIRA 4.
   • Cons: Cannot take advantage of gadget features; may not be the fastest; legacy portlet API is deprecated and may be removed in the future; no way to make this kind of gadget work cross-application on the server-side. (The portlets from JIRA can still be displayed in other gadget containers, so this is not a big con for that many people.)

2. Convert the portlet to a servlet or webwork plugin module that renders the content pretty much exactly the same way the portlet did. Then write a gadget that uses gadgets.io.makeRequest to get those contents, and replaces the body of the gadget with the retrieved contents.

   • Pros: Easier than rewriting entirely as a gadget; can make use of gadget APIs; may be more familiar technology for people used to writing portlets (server-side Java servlets and Velocity templates, versus JavaScript/AJAX).
   • Cons: Not ideal from a performance standpoint; does not take full advantage of dynamic JavaScript UI capabilities; using JavaScript and CSS might be awkward; difficult to make backwards-compatible with older JIRA versions.

3. Rewrite the portlet as a proper gadget, using a REST API to retrieve the data you need from JIRA using gadgets.io.makeRequest, and DOM manipulation in JavaScript to handle the UI.

   • Pros: Allows you to take full advantage of modern AJAX UI techniques; may have performance benefits; best way to take advantage of caching.
   • Cons: May require a substantial rewrite; may require learning a lot of new technology; difficult or impossible to make backwards-compatible with older JIRA versions.

RELATED TOPICS

Using Atlassian REST APIs in your Gadget
Writing an Atlassian Gadget
Gadget Developer Documentation
Writing a Plugin Upgrade Task for JIRA 4.0 (in the JIRA documentation)