Manage Dashboard State

Jun 30, 2020
4 minutes to read

A dashboard state describes the result of client actions users perform on a dashboard. The DashboardState class contains:

dashboard parameter values (the DashboardState.Parameters property)
states of individual dashboard items (the DashboardState.Items property).

You can manage the following objects in a dashboard state:

State Value	API
selected master filters values	ItemState.MasterFilterValues
current drill-down levels	ItemState.DrillDownValues
a selected tab page	ItemState.TabPageName
Range Filter/Date Filter settings	ItemState.RangeFilterState
a selected dashboard item layer^[1]	ItemState.SelectedLayerIndex
selected parameter values	DashboardState.Parameters

API Overview

The DashboardState class represents a dashboard’s state on the server side and includes individual dashboard items’ states (the DashboardState.Items property) and the selected parameter values (DashboardState.Parameters). On the client side, a dashboard state is a JSON object that stores the same data. The table below lists the main server-side and client-side API members related to obtaining and setting a dashboard state.

	API
Server-side	DashboardBuilder.InitialDashboardState DashboardConfigurator.SetDashboardStateService
Client-side	DashboardControl.getDashboardState DashboardControl.setDashboardState DashboardControlOptions.onDashboardStateChanged DashboardControlOptions.initialDashboardState

API

Server-side

DashboardBuilder.InitialDashboardState

DashboardConfigurator.SetDashboardStateService

Client-side

DashboardControl.getDashboardState

DashboardControl.setDashboardState

DashboardControlOptions.onDashboardStateChanged

DashboardControlOptions.initialDashboardState

To initialize the DashboardState object using a JSON object obtained from the client side, use the DashboardStateExtensions.LoadFromJson extension method. Use DashboardStateExtensions.SaveToJson to save the current DashboardState to JSON.

Example 1: Include a Dashboard State to URL

You can include a dashboard state in the browsed dashboard’s URL to allow users to share a dashboard state. To do this, enable the DashboardUrlStateOptionBuilder.IncludeDashboardStateToUrl property. In this case, the resulting link allows users to open the dashboard with the specified state. Note that these properties are in effect when the DashboardExtensionSettings.WorkingMode is set to WorkingMode.Viewer or WorkingMode.ViewerOnly.

The code sample below shows how to include a dashboard state to URL.

<div style="position: absolute; left:0;top:0;right:0;bottom:0;">
    @(Html.DevExpress().Dashboard("clientDashboardDesigner1")
        .Width("100%")
        .Height("100%")
        .WorkingMode(WorkingMode.Designer)
        .Extensions(extension => extension.UrlState(state => state.IncludeDashboardStateToUrl(true)))
    )    
</div>

Note

You can also include the selected dashboard’s identifier in a URL using the DashboardUrlStateOptionBuilder.IncludeDashboardIdToUrl property.

Example 2: Specify a Default Dashboard State

The sample illustrates how to specify a dashboard state (such as a master filter or parameter values) in code and how to apply this state when loading a dashboard for the first time. In this example, the DashboardState object defined in the Controller stores the required dashboard state. The MVC approach is used to pass the specified dashboard state to the View’s DashboardBuilder.InitialDashboardState property and use this state when loading a dashboard.

View Example: ASP.NET Core Dashboard Control - How to specify a default dashboard state in code

@using DevExpress.DashboardWeb
@using DevExpress.AspNetCore
@using DevExpress.DashboardAspNetCore
@using AspNetCoreDashboardState
@using AspNetCoreDashboardState.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@model DevExpress.DashboardCommon.DashboardState
<div style="position: absolute; left:0;top:0;right:0;bottom:0;">
    @(Html.DevExpress().Dashboard("clientDashboardDesigner1")
            .Width("100%")
            .Height("100%")
            .WorkingMode(WorkingMode.Viewer)
            .InitialDashboardState(Model.SaveToJson())
            .Extensions(extension => extension.UrlState(state => state.IncludeDashboardStateToUrl(true)))

    )
</div>

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AspNetCoreDashboardState</title>

    @Html.DevExpress().StyleSheets(styles => styles.AddDashboard(settings => settings.ColorScheme("light")))


</head>
<body>
    @RenderBody()
    @Html.DevExpress().Scripts()
</body>
</html>

using AspNetCoreDashboardState.Models;
using DevExpress.DashboardCommon;
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Diagnostics;

namespace AspNetCoreDashboardState.Controllers {
    public class HomeController : Controller
    {
        public IActionResult Index() {
            DashboardState dashboardState = new DashboardState();

            DashboardParameterState parameterState =
                new DashboardParameterState("countryParameter", "USA", typeof(string));

            DashboardItemState gridFilterState = new DashboardItemState("gridDashboardItem1");
            gridFilterState.MasterFilterValues.AddRange(new List<object[]>() {
                new string[1] { "Andrew Fuller" },
                new string[1] { "Laura Callahan" }
            }
            );

            DashboardItemState treemapDrilldownState = new DashboardItemState("treemapDashboardItem1");
            treemapDrilldownState.DrillDownValues.Add("Beverages");

            DashboardItemState rangeFilterState = new DashboardItemState("rangeFilterDashboardItem1");
            rangeFilterState.RangeFilterState.Selection =
                new RangeFilterSelection(new DateTime(2015, 1, 1), new DateTime(2016, 1, 1));

            dashboardState.Parameters.Add(parameterState);
            dashboardState.Items.AddRange(new List<DashboardItemState>() {
                gridFilterState,
                treemapDrilldownState,
                rangeFilterState }
            );

            return View(dashboardState);
        }

        public IActionResult Error() {
            return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
        }
    }
}

Example 3: Reset a Dashboard State to Default

The code below clears filters (unselects all master filter values), the RangeFilter state and drill-down levels for dashboard items. To do this, assign an empty array of objects to the ItemState.MasterFilterValues, ItemState.DrillDownValues and ItemState.RangeFilterState properties.

Note

The control variable in the example below is the obtained DashboardControl instance. Refer to the Extensions Overview topic for information on how to obtain a DashboardControl for each platform.

function onClick() {
    //...
    var state = JSON.parse(control.getDashboardState());
    if (state && state.Items) {
        Object.keys(state.Items).forEach(function (itemName) {
            var itemState = state.Items[itemName];
            itemState.MasterFilterValues = [];
            itemState.DrillDownValues = [];
            itemState.RangeFilterState = { };
        }) 
    }
    control.setDashboardState(JSON.stringify(state));
}

For the Pie, Card, Treemap, Gauge and Choropleth Map dashboard items.

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

API Overview

Example 1: Include a Dashboard State to URL

Example 2: Specify a Default Dashboard State

Example 3: Reset a Dashboard State to Default