Custom Widgets API Reference

We provide a custom library for JavaScript that includes an API for working with custom widgets. To install this library, use one of the following implementations:

Add a reference to the dashboard script on unpkg in the header of your index.html file. Wrap the reference inside a <script> tag. For example:
<script src="https://unpkg.com/hub-dashboard-addons@latest"></script>
Use the npm package manager to install the script with the npm install hub-dashboard-addons command. You can then add references to the script in your widget any way you want.

The Dashboard.registerWidget function accepts a callback that is called with the dashboardAPI and registerWidgetAPI parameters as shown in the following code sample. To view this sample in context, refer to the Create the Script.

// Register widget:
Dashboard.registerWidget(function (dashboardAPI, registerWidgetAPI) {
    // Load GitHub profile data
    loadAndRenderUser(USER_NAME)

    // Set the widget title
    .then(user => dashboardAPI.setTitle(`GitHub User ${user.login}`));

    // Add the refresh button.
    registerWidgetAPI({
        onRefresh: () => loadAndRenderUser(USER_NAME)
    });
});

Use the following reference to build custom widgets for your Hub dashboards and project overview pages.

Dashboard API

Use the dashboard API to communicate with the widget wrapper and the page that the widget is plugged into. All of these methods are asynchronous and return Promise objects. These methods are applied to the dashboardApi object.

alert

Displays a system alert in the lower-right corner of the page.

Syntax

alert(message: string, ?type: string, ?timeout: integer): string

Parameters

Parameter	Type	Description
message	string	Sets the text that is displayed as the system alert.
type	string	Determines which notification style is applied to the alert. Possible values include `error`, `message`, `success`, and `warning`.
timeout	integer	The amount of time the alert is shown on the page, in seconds.

Example

dashboardApi.alert('This is a standard notification', 'message');
dashboardApi.alert('This is an error', 'error', 10000);

clearError

Removes the warning icon that is added to the widget header with the setError method.

Available since Hub 2019.1.XXXXX

Syntax

clearError(): void

enterConfigMode

Invokes configuration mode. When in configuration mode, the visual presentation of the widget changes to indicate that its settings can be updated. The refresh icon is also hidden.

Syntax

enterConfigMode(): void

exitConfigMode

Exits configuration mode.

Syntax

exitConfigMode(): void

fetch

Makes an authorized request to the specified service. The service must be specified in the widget manifest.

Syntax

fetch(serviceID: string, url: string, fetchConfig: Object): Promise<Object>

Parameters

Parameter	Type	Description
serviceID	string	Specifies the ID of the service. To get the service ID, use fetchHub first. For details, see Get All Services.
url	string	Sets the URL to the service API endpoint. This is the path to the resource that you want to fetch. The URL is relative to the server home URL.
fetchConfig	Object	Defines an optional options object. This object contains any custom settings that you want to apply to the request.

Example

dashboardApi.fetch(serviceId, 'api/users')
                .then(users => console.log(users));

The following example shows how to use this method in a POST request:

dashboardApi.fetch(serviceId, 'api/users', {
    method: 'POST',
    body: {payload: 'test'}
})
    .then(result => console.log(result));

fetchHub

Makes an authorized request to the Hub service.

Syntax

fetchHub(url: string, fetchConfig: Object): Promise<Object>

Parameters

Parameter	Type	Description
url	string	Sets the URL to the Hub service API endpoint. This is the path to the resource that you want to fetch. The URL is relative to the server home URL. For more information, see REST API URL and Endpoints.
fetchConfig	Object	Defines an optional options object. This object contains any custom settings that you want to apply to the request.

Example

dashboardApi.fetchHub('api/rest/users/me?fields=name,login,profile(avatar(url))')
                .then(response => console.log(response));

The following example shows how to use this method in a POST request:

dashboardApi.fetchHub('api/rest/users/me', {
    method: 'POST',
    body: {favoriteProjects: []}
})
    .then(response => console.log(response));

loadServices

Returns a list of services that are connected to the Hub service and meet the minimum version requirements that are specified in the dependencies section of the manifest.json file for the widget.

If the service that is specified with the applicationName parameter is not referenced in the dependencies section of the widget manifest, an exception is thrown.
If the specified service that is connected to the Hub service does not meet the minimum version requirements, returns an empty array.

Syntax

loadServices(applicationName: string): Promise<Array<Object>>

Parameters

Parameter	Type	Description
applicationName	string	Determines which services are checked against the `dependencies` in the widget manifest.

Example

The following example checks the Hub service for versions of YouTrack that are compatible with the YouTrack versions that are referenced in the dependencies section of the widget manifest. The list of compatible versions of the application is printed to the console.

dasboardApi.loadServices('YouTrack')
    .then(youtracks => console.log(youtracks[0]));

readCache

Reads and returns the object that was previously stored in the cache.

Syntax

readCache(): Promise<Object>

readConfig

Reads and returns the object that was previously stored as a configuration object.

Syntax

readConfig(): Promise<Object>

removeWidget

Removes the custom widget from the dashboard or project overview page.

Syntax

removeWidget(): void

setLoadingAnimationEnabled

Toggles the image rotation animation for the widget reload icon. Call this method when the widget populates data from a remote server to indicate that a process is running in the background.

Syntax

setLoadingAnimationEnabled(enabled: boolean): void

Parameters

Parameter	Type	Description
enabled	Boolean	Determines whether the widget reload icon rotates or not.

setError

Adds a warning icon to the left of the title in the widget header. The string of text that is specified for the data parameter is shown when the user hovers the pointer over the warning icon.

Available since Hub 2019.1.XXXXX

Syntax

setError(data: string): void

Parameters

Parameter	Type	Description
data	string	The text that is shown when the user hovers the poiner over the warning icon.

setTitle

Sets the text that is displayed in the widget header. If a value is specified for the labelUrl parameter, the text is set as a link to the target URL.

Syntax

setTitle(label: string, ?labelUrl: string): void

Parameters

Parameter	Type	Description
label	string	The text string that is shown as the widget title.
labelURL	string	The address of the target page that opens when a user clicks the widget title. If this optional parameter is not specified, the widget title is set as text only.

Example

dashboardApi.setTitle('Some widget');
dashboardApi.setTitle('A link header', 'https://example.com');

storeCache

Stores any object in the client-side cache. Use this method to store populated data locally and display it immediately on the dashboard, then refresh it from server. Returns a configuration object.

Syntax

storeCache(cache: Object): Promise<Void>

Parameters

Parameter	Type	Description
cache	Object	Specifies the object to be stored in the cache.

storeConfig

Stores any object as a widget configuration. Exits configuration mode if configuration mode is active.

Syntax

storeConfig(config: Object): Promise<Void>

Parameters

Parameter	Type	Description
config	Object	Specifies the object to be stored as a widget configuration.

Use the widget API to manipulate the visibility of controls on your custom widget. These methods are applied to the widgetApi object.

onConfigure

Calls an action when the Edit option is selected from the widget menu. If not set, the Edit option is not shown.

Syntax

onConfigure(): void

onRefresh

Calls an action when the refresh icon is clicked in the widget header. If not set, the refresh icon is not shown in the header.

Syntax

onRefresh(): ?Promise<Void>

Last modified: 17 February 2020

Custom Widgets API Reference

Dashboard API

alert

Syntax

Parameters

Example

clearError

Syntax

enterConfigMode

Syntax

exitConfigMode

Syntax

fetch

Syntax

Parameters

Example

fetchHub

Syntax

Parameters

Example

loadServices

Syntax

Parameters

Example

readCache

Syntax

readConfig

Syntax

removeWidget

Syntax

setLoadingAnimationEnabled

Syntax

Parameters

setError

Syntax

Parameters

setTitle

Syntax

Parameters

Example

storeCache

Syntax

Parameters

storeConfig

Syntax

Parameters

Widget API

onConfigure

Syntax

onRefresh

Syntax