Documentation under development
This page compares JIRA portlets with gadgets.
On this page:
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.
makeRequest back to the originating server.
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.
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
Test before deploying to JIRA 4 in production
Be sure to test your portlets in a JIRA 4 dashboard before deploying to a production instance of JIRA 4.
Converting a JIRA Portlet to a Gadget
We will have more information from this page after the Atlassian Summit. Tim is doing a presentation that we can adapt for this page.
There are three options for converting a portlet to a gadget:
- Use the legacy bridge described 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.)
- 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.
- Rewrite the portlet as a proper gadget, using a REST API to retrieve the data you need from JIRA using
- 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.
Using Atlassian REST APIs in your Gadget
Writing an Atlassian Gadget
Gadgets and Dashboards Development Hub
Writing a Plugin Upgrade Task for JIRA 4.0 (in the JIRA documentation)