Gadgets are like mini-applications that live on a dashboard in JIRA. They are similar to widgets in most of the smart phones we have today or portlets in most portal applications. Each gadget has its own unique interface and behavior. For example, the Pie Chart gadget displays data in a pie chart, while the Assigned to Me gadget lists all the unresolved issues that are assigned to the current user in a table.
To discuss the in-depth details of gadgets and their underlying technology (OpenSocial) is beyond the scope of this book, but there is much information on this topic available on the Internet, if you are interested in creating your own gadgets to use with JIRA. A good place to start will be the Atlassian documentation at https://developer.atlassian.com/x/IgA3.
All gadgets are listed in the Gadget Directory. JIRA comes with a number of useful gadgets, such as the Assigned to Me gadget that you see on the System Dashboard. The following screenshot shows the gadget directory, listing all the bundled gadgets in JIRA.
Perform the following steps to place a gadget onto your dashboard:
- Bring up the drop-down menu from Dashboards.
- Select the dashboard you wish to add a gadget to.
- Click on the Add Gadget option at the top-right corner. This will bring up the Gadget Directory window.
- Click on the Add gadget button for the gadget you wish to add.
- Click on the Close link to return to the dashboard, as shown in the following screenshot:
Depending on the gadget you selected, some gadgets will require additional options to be configured. For these gadgets, you will be presented with their configuration screen on the dashboard. Fill in the options and click on the Save button.
The following screenshot shows the configuration screen for the Filter Results gadget, where you can select the search filter to display and control the number of results to show and the fields to include. One common parameter is the Refresh Interval option, where you can decide how often the gadget can refresh its content or stay static if you choose never. Whenever you refresh the entire dashboard, all gadgets will load the latest data, but if you stay on the dashboard for an extended period of time, each gadget can automatically refresh its data, so the content will not become stale overtime.
Take a look at the following screenshot:
When you add a gadget, it's usually added to the first available spot on the dashboard. This sometimes might not be where you want to display the gadget on the dashboard, and in other cases, you might want to move the existing gadgets around from time to time. As the owner of the dashboard, you can easily move gadgets on a dashboard through a simple drag-and-drop interface:
- Browse to the dashboard that has gadgets you wish to move.
- Click on the gadget's title and drag it to the new position on the dashboard.
As soon as you drop the gadget to its new location (by releasing your mouse button), the gadget will be moved permanently until you decide to move it again.
After configuring your gadget when you first place it on your dashboard, the gadget will remember this and use it to render its content. You can update the configuration details or even its look and feel, as follows:
- Browse to the dashboard that has gadgets you wish to update.
- Hover over the gadget and click on the down arrow button at the top-right corner of it. This will bring up the gadget configuration menu.
- Click on the Edit option.
- This will change the gadget into its configuration mode.
- Update the configuration options.
- Click on the Save button to apply the changes:
The preceding screenshot shows the Edit menu for the Assigned to Me gadget. You can force a refresh with the Refresh option. Since gadgets retrieve their data asynchronously through AJAX, you can use this option to refresh the gadget itself without refreshing the entire page. The edit, delete, and color options are only available to the owner of the dashboard.
As the owner of the dashboard, you can remove the existing gadgets from the dashboard when they are no longer needed. When you remove a gadget from a dashboard, please note that all the other users who have access to your dashboard will no longer see it:
- Browse to the dashboard that has gadgets you wish to delete.
- Hover over the gadget and click on the down arrow button at the top-right-hand corner of it. This will bring up the gadget configuration menu.
- Click on the Delete option.
- Confirm the removal when prompted.
Once removed, the gadget will disappear from the dashboard. If you choose to re-add the same gadget again at a later stage, you will have to reconfigure it again.