Dashboard Class

Defines the dashboard's attributes, including layout, contained widgets, and filters.

Properties

Name	Type	Readonly	Description
`oid`	`string`	Yes	Dashboard ID
`title`	`string`	No	Title
`desc`	`string`	No	Description
`owner`	`string`	Yes	Owner OID
`userId`	`string`	Yes	Instance User OID
`instanceType`	`string`	Yes	Whether the instance is the origin (owner) or a viewer's copy
`created`	`Date`	Yes	Date created
`lastUpdated`	`Date`	Yes	Date last updated
`lastUsed`	`Date`	Yes	Date last used
`lastOpened`	`Date`	Yes	Date last opened
`instanceid`	`string`	Yes	Unique ID of the dashboard instance
`datasource`	`Datasource`	No	Primary Datamodel used by the Dashboard
`filters`	`DashboardFilters`	No	An array of Dashboard Filters
`widgets`	`DashboardWidgets`	No	An array of Widgets in the Dashboard
`layout`	`DashboardLayout`	No	An Object describing the Dashboard's grid-like layout
`initialized`	`boolean`	Yes	Indicates if the dashboard has been initialized
`refreshing`	`boolean`	Yes	Indicates if the dashboard is currently refreshing
`editing`	`boolean`	Yes	Indicates if the dashboard is currently in edit state
`autoUpdateOnFiltersChange`	`boolean`	Yes	Indicates if the dashboard is in auto-refresh mode
`$$events`	`EventsCollection`	Yes	Contains all available events for the dashboard and their handlers

Methods

refresh

refresh() → Promise

Refreshes the dashboard.

Arguments

N/A

Returns

A Promise that resolves when the dashboard has refreshed

Example

dashboard.refresh().then(function () {
    console.log('dashboard is refreshed');
});

addWidget

addWidget(widget[, layout])

Adds the given widget to the dashboard.
If layout is not provided, the widget is placed at the bottom of the first column in the dashboard.

Arguments

Name	Type	Required	Description
`widget`	`Widget`	Yes	Widget model to be added.
`layout`	`WidgetLayout`	No	Layout object that defines the widget's placement.

Returns

N/A

Example

dashboard.addWidget(
    {
        // Widget model
    },
    {
        // Layout model
    }
);

datasources

datasources() → Array<Datasource>

Returns an array of datasource objects used by the various widgets in the dashboard.

Arguments

N/A

Returns

An array of Datasource objects

Example

console.log(dashboard.datasources().length);

isEmpty

isEmpty() → boolean

Returns a response stating whether the dashboard includes widgets, or is empty.

Arguments

N/A

Returns

A boolean indicating whether the dashboard is empty (has no widgets).

Example

console.log(dashboard.isEmpty());

destroy

destroy()

Releases the resources of the dashboard object and contained widgets.

Arguments

N/A

Returns

N/A

Example

dashboard.destroy();

on

on(eventName, eventHandler)

Subscribe to a dashboard event

Arguments

Name	Type	Description	Example
`eventName`	`string`	Event to register to	`'beforemenu'`
`eventHandler`	`function`	Event handler function

Returns

N/A

Example

dashboard.on('initialized', function () {
    console.log('dashboard initialized');
});

Events

initialized

Fired after the dashboard is initialized.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.

refreshstart

Fired after one or more widgets have started the refresh process.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.
`totalQueries`	`number`	Number of queries in the current run.

refreshend

Fired when a refresh process ends for one or more widgets.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.
`completedQueries`	`number`	of completed queries.

widgetrefreshed

Fired when a widget refresh has ended.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.
`widget`	`Widget`	Refreshed widget.
`totalQueries`	`number`	Number of queries in the current run.
`completedQueries`	`number`	Number of completed queries.

widgetadded

Fired when a widget was added to the dashboard.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.
`widget`	`Widget`	Added widget.
`layout`	`widgetLayout`	Layout options object.

stylechanged

Fired when the dashboard style is changed.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.

destroyed

Fired when the dashboard is destroyed.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.

editstart

Fired when entering edit mode.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.

editend

Fired when leaving edit mode.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.

filterschanged

Fired when the dashboard filter changes.

Arguments

Name	Type	Description
`dashboard`	`Dashboard`	Dashboard instance.
`type`	`string`	Change type. Available values: add/update and remove.
`items`	`MetadataItem[]`	Affected filter items

widgetinitialized

Fired when the widget is initialized.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.

widgetbuildquery

Fired when executing the widget’s native build query, and allows customization of the JAQL query object before execution.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.
`query`	`object`	JAQL query object.

widgetbeforequery

Fired before the query is executed.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.
`query`	`object`	JAQL query object.

widgetprocessresult

Fired after executing the widget’s native result processing, and allows customization of the query result before being rendered.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.
`query`	`object`	JAQL query object.
`result`	`queryResult`	Processed result.
`rawResult`	`rawQueryResult`	JAQL query result.
`reason`	`string`	Query reason.

widgetrender

Fired when the widget is rendered.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.
`reason`	`string`	Rendering reason.
`disableAnimations`	`boolean`	Indicates whether animations are enabled.

widgetready

Fired when the widget’s rendering is complete and the widget is ready.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.

beforewidgetmenu

Fired before a widget shown in a dashboard shows it’s context menu.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.
`items`	`object[]`	Array of items to be displayed.
`element`	`DOMElement`	The source element that triggers the event.
`cancel`	`boolean`	Determines whether the menu is displayed.

widgetdestroyed

Fired when the widget is destroyed and it’s resources are released.

Arguments

Name	Type	Description
`widget`	`Widget`	Widget instance.

Types

widgetLayout

Groups a set of widget layout related attributes in a single object, used to define where within a dashboard's layout a new widget should be positioned.

Properties

Property	Type	Description
`col`	`DashboardLayoutColumn`	Ancestor column object.
`colidx`	`integer`	Column index.
`cell`	`DashboardLayoutCell`	Ancestor cell object.
`cellidx`	`integer`	Cell index in its parent column cells collection.
`subcell`	`DashboardLayoutSubcell`	Ancestor sub-cell object.
`subcellidx`	`integer`	Sub-cell index in its parent cell sub-cells collection.
`element`	`DashboardLayoutElement`	Parent element object.
`elementidx`	`integer`	Element index in its parent sub-cell elements collection.

EventsCollection

The property $$events of the Dashboard and Widget objects contains this key-value pair of all available events for the object and all event handlers registered to them.

The basic structure of the object is:

{
    eventName: {
        name: 'eventName',
        handlers: []
    }
}

Each event name key contains an object with the following properties:

Property	Type	Description
`name`	`string`	String representation of the event name
`handlers`	`function[]`	An array of registered handlers for the event