DashboardControl Class

A client-side JavaScript Dashboard control, which allows end users to create dashboards and work with them.

Declaration

export class DashboardControl

Remarks

The code below shows how to generate a client-side JavaScript Dashboard control:

Modular Approach
Global Namespaces

// ...
ngAfterViewInit(): void {
    ResourceManager.embedBundledResources();
    let dashboardControl = new DashboardControl(this.element.nativeElement.querySelector(".web-dashboard"),  {      
      endpoint: "http://localhost:59770/api/dashboard",
      workingMode: "Designer",      
      extensions: {
        'dashboard-export': {
            allowExportDashboardItems: true,
        }
    }
    });

    dashboardControl.render();
  }

<html>
<head>
    <!-- ... -->
    <script>
        window.onload = function () {
            DevExpress.Dashboard.ResourceManager.embedBundledResources();
            var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
                endpoint: "http://localhost:59770/api/dashboard",
                workingMode: "Designer",
                extensions: {
                    'dashboard-export': {
                        allowExportDashboardItems: true,
                    }
                }
            });
            dashboardControl.render();
        }
    </script>
</head>
<body>    
    <div id="web-dashboard" style="position: absolute; left: 0; right: 0; top: 0; bottom: 0"></div>
</body>
</html>

See HTML JavaScript Dashboard Control for more information about the two approaches.

The Web Dashboard requires various server-side options to be configured. For instance, you need to prepare a dashboard storage, register predefined data sources, etc. Refer the following topics to learn more about server-side configuration:

The DashboardControlOptions class contains options you can use to configure the Web Dashboard.

constructor(element)

Initializes a new instance of the DashboardControl class with specified options.

Declaration

constructor(
    element: Element,
    options?: DashboardControlOptions
)

Parameters

Name	Type	Description
element	Element	An element inside which the DashboardControl is rendered.
options	DashboardControlOptions	A DashboardControlOptions object providing access to the DashboardControl options.

Remarks

Refer to DashboardControl to see an example on how to create and initialize the DashboardControl class instance.

Properties

allowSwitchToDesigner Property

Gets whether the ‘Edit in Designer’ button is displayed on the Dashboard Panel when the Web Dashboard operates in the Viewer mode.

Declaration

readonly allowSwitchToDesigner: boolean

Property Value

Type	Description
boolean	true if the ‘Edit in Designer’ button is displayed on the Dashboard Panel; otherwise, false.

Remarks

Warning

This member is obsolete. Use the allowSwitchToDesigner property instead.

colorSchemeCss Property

Gets the name of a CSS class used by a color scheme applied to the Web Dashboard.

Declaration

readonly colorSchemeCss: "dx-color-scheme-light" | "dx-color-scheme-dark"

Property Value

Name
"dx-color-scheme-light"
"dx-color-scheme-dark"

Remarks

See Appearance Customization to learn how specify the required color scheme.

customTemplates Property

Allows you to use custom templates in the Web Dashboard.

Declaration

customTemplates: ko.ObservableArray<KnockoutTemplate>

Property Value

Type	Description
ObservableArray<KnockoutTemplate>	An array of KnockoutTemplate objects that are custom templates.

dashboard Property

Specifies the currently opened dashboard.

Declaration

dashboard: ko.Computed<Dashboard>

Property Value

Type	Description
Computed<Dashboard>	A Dashboard object that is the currently opened dashboard.

Remarks

The dashboard property returns a dashboard model that contains the full description of a dashboard, including the collection of dashboard items and groups, data binding information, layout and appearance settings, etc.

dashboardContainer Property

Gets an object that contains information about the opened dashboard.

Declaration

dashboardContainer: ko.Observable<DashboardContainer>

Property Value

Type	Description
Observable<DashboardContainer>	The DashboardContainer object that contains information about the opened dashboard.

element Property

Returns an element inside which the DashboardControl is rendered.

Declaration

element: Element

Property Value

Type	Description
Element	An element inside which the DashboardControl is rendered.

Remarks

Call constructor(element) to create the DashboardControl and specify an element inside which this control is rendered.

encodeHtml Property

Gets whether the web control’s value and element content are rendered as pure HTML, or HTML markers are stripped out.

Declaration

readonly encodeHtml: boolean

Property Value

Type	Description
boolean	true if the HTML code contained within the web control’s value and element content are not executed and are converted into the corresponding text for display purposes; false if the web control’s value and element content can contain pure HTML code.

Remarks

To prevent HTML-injection, make sure that the encodeHtml property is enabled.

extensions Property

Provides access to extensions registered in the Web Dashboard.

Declaration

readonly extensions: IExtension[]

Property Value

Type	Description
IExtension[]	An array of extensions registered in the Web Dashboard.

getWidgetContainer Property

Gets a widget container where the Web Dashboard is rendered.

Declaration

getWidgetContainer: () => HTMLElement

Property Value

Type
() => HTMLElement

isDesignMode Property

Gets a value that indicates whether the Web Dashboard works in the Designer mode.

Declaration

isDesignMode: ko.Observable<boolean>

Property Value

Type	Description
Observable<boolean>	true, if the Web Dashboard works as a designer; false, if the Web Dashboard works as a viewer.

Remarks

To specify a working mode for the Web Dashboard, use the workingMode property.

maximizedDashboardItemName Property

Declaration

readonly maximizedDashboardItemName: string

Property Value

Type
string

notificationController Property

For internal use.

Declaration

notificationController: NotificationController

Property Value

Type	Description
NotificationController	A NotificationController object.

remoteService Property

Declaration

remoteService: IRemoteService

Property Value

Type
IRemoteService

resizeByTimer Property

Specifies whether to redraw the DashboardControl automatically when the size of a container changes.

Declaration

resizeByTimer: ko.Observable<boolean>

Property Value

Type	Description
Observable<boolean>	true, to redraw the DashboardControl automatically when the size of the a container changes; otherwise, false.

Remarks

By default, the DashboardControl redraws itself automatically when the size of its parent container changes. You can set the resizeByTimer option to false to disable automatic redrawing. In this case, call the repaint method to redraw the DashboardControl.

showConfirmationOnBrowserClosing Property

Specifies whether to show a browser warning if an end-user attempts to leave the page with unsaved data.

Declaration

showConfirmationOnBrowserClosing: boolean

Property Value

Type	Description
boolean	true, to show dialog; otherwise, false.

surfaceLeft Property

Specifies the left indent of the DashboardControl.

Declaration

surfaceLeft: ko.Observable<number>

Property Value

Type	Description
Observable<number>	An integer value that specifies the left indent of the DashboardControl (in pixels).

Methods

dispose Method

Disposes of all resources associated with this DashboardControl.

Declaration

dispose(): void

findExtension(extensionName) Method

Allows you to obtain the specified extension registered in the Web Dashboard.

Declaration

findExtension(
    extensionName: string
): IExtension

Parameters

Name	Type	Description
extensionName	string	A string value that specifies the extension name.

Returns

Type	Description
IExtension	A dashboard extension.

Remarks

Use the extension’s name property value to pass as the extensionName parameter. For instance, the code snippet below shows how obtain the AvailableDataSourcesExtension:

var dataSourcesExtension = dashboardControl.findExtension('available-data-sources');

See the DevExpress.Dashboard.Designer module to find all available extensions.

getDashboardId Method

Declaration

getDashboardId(): string

Returns

Type
string

getDashboardState Method

Gets the current dashboard state.

Declaration

getDashboardState(): string

Returns

Type	Description
string	A string that identifies the state of the dashboard displayed in the `DashboardControl`.

Remarks

Use the DashboardControl.setDashboardState(dashboardState) method to apply a dashboard state.

initializeDashboard(id, dashboardJson) Method

Initializes a new dashboard with the specified name and JSON model.

Declaration

initializeDashboard(
    id: string,
    dashboardJson: Object,
    initialState?: DashboardState
): void

Parameters

Name	Type	Description
id	string	A string value that is a unique name of the created dashboard.
dashboardJson	Object	A dashboard model encoded in the specified JSON string.
initialState	DashboardState	A JSON object that specifies the dashboard state.

loadDashboard(dashboardId) Method

Loads the dashboard with the specified identifier from the dashboard storage.

Declaration

loadDashboard(
    dashboardId: string
): JQueryPromise<any>

Parameters

Name	Type	Description
dashboardId	string	A string value that specifies the dashboard identifier.

Returns

Type	Description
JQueryPromise<any>	A Promise that is resolved after the dashboard is loaded.

Remarks

The loadDashboard method loads the dashboard with the specified identifier from the dashboard storage and displays this dashboard. The following code snippet demonstrates how to load a dashboard with the dashboard1 identifier:

dashboardControlGlobal.loadDashboard("dashboard1")
    .done(function () { alert("A dashboard is loaded successfully."); })
    .fail(function() { alert("Cannot load a dashboard."); });

To close the dashboard, use the unloadDashboard method.

maximizeDashboardItem(itemName) Method

Expands the specified dashboard item to the entire dashboard size to examine data in greater detail.

Declaration

maximizeDashboardItem(
    itemName: string
): void

Parameters

Name	Type	Description
itemName	string	A string that is the dashboard item component name.

Remarks

To maximize an item:

Call the maximizeDashboardItem(itemName) method in code.
End-users can click the Maximize button in the dashboard item caption.

To restore an item’s size:

Call the restoreDashboardItem method in code.
End users can click the Restore button in the dashboard item caption.

Note

The dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

refresh Method

Refreshes dashboard items.

Declaration

refresh(
    args?: RefreshItemsArgs
): void

Parameters

Name	Type	Description
args	RefreshItemsArgs	A RefreshItemsArgs object that speciifies the component name(s) of the dashboard item(s) to be refreshed.

Remarks

Call the refresh method without parameters to refresh all dashboard items:

dashboardControl.refresh();

To refresh specific dashboard items, pass their names as a parameter:

dashboardControl.refresh( ["chartDashboardItem1", "gridDashboardItem1"] );

registerExtension(extensions) Method

Registers an extension(s) to add its functionality to the Web Dashboard.

Declaration

registerExtension(
    ...extensions: IExtension[]
): void

Parameters

Name	Type	Description
extensions	IExtension[]	An array of extensions.

Remarks

The code snippet below shows how to register the DashboardPanelExtension extension:

dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));

To unregister the extension, call the unregisterExtension(extensionNames) method.

registerIcon(icon) Method

Embeds an icon’s SVG definition onto the page.

Declaration

registerIcon(
    icon: string
): void

Parameters

Name	Type	Description
icon	string	A string that specifies an icon’s SVG definition.

Remarks

Warning

This member is obsolete. Use the registerIcon(icon) property instead.

reloadData Method

Reloads data in the data sources.

Declaration

reloadData(): void

Remarks

When the client data processing mode is used, Web Dashboard caches data on the server side to improve data loading performance. When you call the reloadData method on the client side, a callback is sent to the server. The server-side’s cache for all data sources is reset and all dashboard items request new data from data sources.

Important

Since multiple users can simultaneously open the dashboard and share the same server-side cache, execution of the reloadData method by one of the clients forces the server cache to be reset. All users get new data on the next request to the server.

render Method

Renders the DashboardControl inside the specified element.

Declaration

render(): void

Remarks

Note that you need to call the render method only once after creating and configuring the DashboardControl. See DashboardControl to learn how to do this.

To redraw the DashboardControl after resizing its parent container, call the repaint method.

repaint Method

Redraws the DashboardControl when the size of a container changes.

Declaration

repaint(): void

Remarks

By default, the DashboardControl redraws itself automatically when the size of its parent container changes. You can set the resizeByTimer option to false to disable automatic redrawing. In this case, call the repaint method to redraw the DashboardControl.

requestDashboardList Method

Requests information about the dashboards available in the dashboard storage.

Declaration

requestDashboardList(): JQueryPromise<any>

Returns

Type	Description
JQueryPromise<any>	A Promise that is resolved after the dashboard is loaded.

Remarks

The code snippet below shows how to display information about the available dashboards in the browser console:

dashboardControl.requestDashboardList()
    .done(function (e) { e.forEach(function (dashboardInfo) {
            console.log(dashboardInfo);
        });
    });

restoreDashboardItem Method

Restores the item size if an item is expanded to the entire dashboard size (maximized).

Declaration

restoreDashboardItem(): void

Remarks

To maximize an item:

Call the maximizeDashboardItem(itemName) method in code.
End-users can click the Maximize button in the dashboard item caption.

To restore an item’s size:

Call the restoreDashboardItem method in code.
End users can click the Restore button in the dashboard item caption.

Note

The dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

setDashboardState(dashboardState) Method

Applies the dashboard state to the loaded dashboard.

Declaration

setDashboardState(
    dashboardState: DashboardState | string
): void

Parameters

Name	Type	Description
dashboardState	DashboardState \| string	A DashboardState object or a string that specifies the dashboard state.

Remarks

Use the DashboardControl.getDashboardState method to get the current dashboard state.

The following examples demonstrates how to pass a string that contains a dashboard state.

Sets master-filter values for the Grid and Card dashboard items:

var state = '{"Items":{"gridItem1":{"MasterFilterValues":[[2018]]},"cardItem1":{"MasterFilterValues":[["Manufacturing"]]}}}';
clientDashboard1.setDashboardState(state);

Sets a drill-down value for the Chart dashboard item:

var state = '{"Items":{"chartItem1":{"DrillDownValues":["Web Forms"]}}}';
clientDashboard1.setDashboardState(state);

Sets a dashboard parameter value and a master-filter value for the Card dashboard item:

var state = '{"Parameters":{"Year":2017},"Items":{"card1":{"MasterFilterValues":[["Petroleum Products"]]}}}';
clientDashboard1.setDashboardState(state);

Specifies a tab page:

var state = '{"Items":{"tabContainerDashboardItem1":{"TabPageName":"pageDashboardItem2"}}}';
clientDashboard1.setDashboardState(state);

subscribeExtensionsChanged(handlers) Method

Allows you to subscribe to adding or removing extensions.

Declaration

subscribeExtensionsChanged(handlers: {
    added?: (item: IExtension) => void;
    deleted?: (item: IExtension) => void;
}): ko.Subscription

Parameters

Name	Type	Description
handlers	{added: (item: IExtension) => void, deleted: (item: IExtension) => void}	An object that returns added/removed extensions.

Returns

Type	Description
Subscription	A KnockoutSubscription object that allows you to terminate a subscription.

Remarks

The subscribeExtensionsChanged method allows you to subscribe to adding or removing extensions (for instance, added or removed using the registerExtension(extensions) or unregisterExtension(extensionNames)methods, respectively). The code snippet below shows how to display a name of the added or removed extension in the alert box:

dashboardControl.subscribeExtensionsChanged({
    added: (extension) => {
        alert("The " + extension.name + " extension was added.");
    },
    deleted: (extension) => {
        alert("The " + extension.name + " extension was removed.");
    }
});

switchToDesigner Method

Switches the Web Dashboard to the designer mode.

Declaration

switchToDesigner(): void

Remarks

Use the switchToViewer method to switch the Web Dashboard to the viewer mode.

The workingMode option allows you to specify the Web Dashboard’s working mode.

switchToViewer Method

Switches the Web Dashboard to the viewer mode.

Declaration

switchToViewer(): void

Remarks

Use the switchToViewer method to switch the Web Dashboard to the designer mode.

The workingMode option allows you to specify the Web Dashboard’s working mode.

unloadDashboard Method

Closes the displayed dashboard.

Declaration

unloadDashboard(): void

Remarks

To load the dashboard from the dashboard storage, use the loadDashboard(dashboardId) method.

unregisterExtension(extensionNames) Method

Unregisters an extension(s) to remove its functionality from the Web Dashboard.

Declaration

unregisterExtension(
    ...extensionNames: string[]
): void

Parameters

Name	Type	Description
extensionNames	string[]	An array of strings that are extension names.

Remarks

To disable the extension, call the unregisterExtension method and pass the extension’s unique name as a parameter. For instance, the code snippet below shows how to disable the AvailableDataSourcesExtension:

dashboardControl.unregisterExtension('available-data-sources');

To register the extension, call the registerExtension(extensions) method.