# 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.
item MetadataItem Changed item.

# 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