Rate this page:
The jira:dashboardGadget
module creates a dashboard gadget that is displayed on the Dashboards page.
This module can be used in Jira Work Management, Jira Software, and Jira Service Management.
See the DashboardGadget component documentation for an example.
Dashboard Gadgets can be configured using their edit mode.
Dashboard Gadgets can be refreshed manually by your users and automatically. The automatic refresh interval (in minutes) is configured by submitting a refresh
field as part of an edit view (the API accepts positive integers for this field).
When using the onSubmit
method in the DashboardGadgetEdit UI kit component, provide a refresh
field to the object returned by your onSubmit function.
1 2const onSubmit = () => ({ ...otherFieldsToSubmit, refresh: 15 });
When using Custom UI to work with the Dashboard Gadget module, use the submit API as part of your edit view to provide a refresh
field to the submit function:
1 2await view.submit({ ...otherFieldsToSubmit, refresh: 15 });
refreshable
property to false
in the gadget's manifest file.JIRA_DASHBOARD_GADGET_REFRESH
event using the on()
function from the
Forge bridge.1 2import { on } from '@forge/bridge'; function App() { function refresh() { // your refresh logic } useEffect(() => { on('JIRA_DASHBOARD_GADGET_REFRESH', refresh); }, []); }
When the user clicks the refresh button of any Forge dashboard gadget that has overridden the default refresh behavior, the
JIRA_DASHBOARD_GADGET_REFRESH
event will be triggered and all Forge gadgets will receive it.
With Custom UI, you can define the same resource for viewing and editing your dashboard gadget.
First, define your manifest:
1 2# manifest.yml modules: jira:dashboardGadget: - key: hello-world-gadget title: Hello world! description: A hello world dashboard gadget. thumbnail: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg resource: main # the resource used to view our dashboardGadget resolver: function: resolver edit: resource: main # the same resource, used to edit our dashboardGadget configuration resources: - key: main path: static/hello-world/build
Then in your Custom UI, use the view API to determine whether to display the view mode or edit mode:
1 2// App.jsx import React, { useEffect, useState } from 'react'; import { view } from '@forge/bridge'; import View from './View'; import Edit from './Edit'; function App() { const [context, setContext] = useState(); useEffect(() => { view.getContext().then(setContext); }, []); if (!context) { return 'Loading...'; } return context.extension.entryPoint === 'edit' ? <Edit/> : <View/>; } export default App;
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest.
Regex: |
function | string | The dashboard gadget module requires a function for use with the UI kit or a resource when building with custom UI. | A reference to the function module that defines the dashboard gadget. This function must return the DashboardGadget component. |
resource | string | A reference to the static resources entry that the dashboard gadget displays. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string or { text: string, href: string } | Yes | Can be:
|
description | string | Yes | A description of what the gadget does. |
thumbnail | string | Yes | The absolute URL of the icon that's displayed next to the gadget's name and description in the list of gadgets that can be added to a dashboard. |
edit:function | string | A reference to the function module that provides the editing experience for dashboard gadgets. | |
refreshable | boolean | Set the refreshable property of the dashboard item to false to override the native Jira refresh behavior. |
Property | Type | Description |
---|---|---|
gadgetConfiguration | object | Object containing gadget configuration. |
dashboard:id | string | ID of the dashboard. |
gadget:id | string | ID of the gadget. |
type | string | The type of the module. |
Rate this page: