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