Display conditions
Modules

Rate this page:

Jira dashboard gadget (EAP)

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.

Configuration

Dashboard Gadgets can be configured using their edit mode.

Auto-refresh

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).

UI kit

When using the onSubmit method in the DashboardGadgetEdit UI kit component, provide a refresh field to the object returned by your onSubmit function.

1
2
const onSubmit = () => ({ ...otherFieldsToSubmit, refresh: 15 });

Custom UI

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
2
await view.submit({ ...otherFieldsToSubmit, refresh: 15 });

Conditional rendering

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;

Properties

PropertyTypeRequiredDescription
key

string

YesA key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestring or { text: string, href: string }YesCan be:
  • a plain string containing the gadget's title.
  • an object containing a text property containing the gadget's title and a href property containing a link that the user is sent to when they click the gadget’s title.
descriptionstringYesA description of what the gadget does.
thumbnailstringYesThe 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
stringA reference to the function module that provides the editing experience for dashboard gadgets.

Rate this page: