YouTrack Standalone 2017.3 Help

Custom Widgets API Reference

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
DescriptionSets 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.
ParameterslabelThe text string that is shown as the widget title.
labelURLThe 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.
setLoadingAnimationEnabled(enabled: boolean): void
DescriptionToggles 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.
ParametersenabledDetermines whether the widget reload icon rotates or not.
alert(message: string, type: "error"|"message"|"success"|"warning", delay: number): void
DescriptionDisplays a system alert at the top of the page.
ParametersmessageSets the text that is displayed as the system alert.
typeDetermines which notification style is applied to the alert.
delayThe amount of time the alert is shown on the page, in seconds.
enterConfigMode(): void
DescriptionInvokes 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
DescriptionExits configuration mode.
storeCache(cache: Object): Object
DescriptionStores 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.
ParameterscacheSpecifies the object to be stored in the cache.
readCache(): Object
DescriptionReads and returns the object that was previously stored in the cache.
storeConfig(config: Object): void
DescriptionStores any object as a widget configuration. Exits configuration mode if configuration mode is active.
ParametersconfigSpecifies the object to be stored as a widget configuration.
readConfig(): Object
DescriptionReads and returns the object that was previously stored as a configuration object.
fetch(serviceID: string, url: string, fetchConfig: Object): Object
DescriptionMakes an authorized request to the specified service. The service must be specified in the widget manifest.
ParametersserviceIDSpecifies the ID of the service.
urlSets 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.
fetchConfigDefines an optional options object. This object contains any custom settings that you want to apply to the request.
fetchHub(url: string, fetchConfig: Object): Object
DescriptionMakes an authorized request to the built-in Hub service.
ParametersurlSets 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.
fetchConfigDefines an optional options object. This object contains any custom settings that you want to apply to the request.

Widget API

Use the widget API to manipulate the visibility of controls on your custom widget. These methods are also asynchronous and return Promise objects. These methods are applied to the widgetApi object.

onRefresh(): void
DescriptionCalls 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
DescriptionCalls an action when the Edit option is selected from the widget menu. If not set, the Edit option is not shown.
Last modified: 17 November 2017