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.
Use the following reference to build custom widgets for your dashboards.
Dashboard API
Use the dashboard API to communicate with the widget wrapper and the dashboard. All of these methods are asynchronous and return Promise
objects. These methods are applied to the dashboardApi
object.
setTitle(label: string, ?labelUrl: string): void | ||
---|---|---|
Description | Sets the text that is displayed in the widget header. If a value is specified for the | |
Parameters | label | The text string that is shown as the widget title. |
labelURL | 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'); |
setLoadingAnimationEnabled(enabled: boolean): void | ||
---|---|---|
Description | 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. | |
Parameters | enabled | Determines whether the widget reload icon rotates or not. |
alert(message: string, ?type: string, ?timeout: number): string | ||
---|---|---|
Description | Displays a system alert at the top of the page. | |
Parameters | message | Sets the text that is displayed as the system alert. |
type | Determines which notification style is applied to the alert. Possible values include | |
timeout | 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); |
enterConfigMode(): void | |
---|---|
Description | 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. |
exitConfigMode(): void | |
---|---|
Description | Exits configuration mode. |
storeCache(cache: Object): Promise<Void> | ||
---|---|---|
Description | 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. | |
Parameters | cache | Specifies the object to be stored in the cache. |
readCache(): Promise<Object> | |
---|---|
Description | Reads and returns the object that was previously stored in the cache. |
storeConfig(config: Object): Promise<Void> | ||
---|---|---|
Description | Stores any object as a widget configuration. Exits configuration mode if configuration mode is active. | |
Parameters | config | Specifies the object to be stored as a widget configuration. |
readConfig(): Promise<Object> | |
---|---|
Description | Reads and returns the object that was previously stored as a configuration object. |
fetch(serviceID: string, url: string, fetchConfig: Object): Promise<Object> | ||
---|---|---|
Description | Makes an authorized request to the specified service. The service must be specified in the widget manifest. | |
Parameters | serviceID | Specifies the ID of the service. To get the service ID, use fetchHub first. For details, refer to the Hub REST API. |
url | 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 | 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(url: string, fetchConfig: Object): Promise<Object> | ||
---|---|---|
Description | Makes an authorized request to the Hub service. | |
Parameters | url | 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, refer to the Hub documentation. |
fetchConfig | 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(applicationName: string): Promise<Array<Object>> | ||
---|---|---|
Description | Returns a list of services that are connected to the Hub service and meet the minimum version requirements that are specified in the
| |
Parameters | applicationName | Determines which services are checked against the |
Example | The following example checks the Hub service for versions of YouTrack that are compatible with the YouTrack versions that are referenced in the dasboardApi.loadServices('YouTrack')
.then(youtracks => console.log(youtracks[0])); |
removeWidget(): void | |
---|---|
Description | Removes the custom widget from the dashboard. |
Widget API
Use the widget API to manipulate the visibility of controls on your custom widget. These methods are applied to the widgetApi
object.
onRefresh(): ?Promise<Void> | |
---|---|
Description | 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. |
onConfigure(): void | |
---|---|
Description | Calls an action when the Edit option is selected from the widget menu. If not set, the Edit option is not shown. |