Manage Dashboard State

• Aug 01, 2019
• 6 minutes to read

A dashboard state describes a result of client actions performed by an end-user on a dashboard such as:

• selected master filters values,
• current drill-down levels,
• selected parameter values,
• a selected tab page.

The Web Dashboard allows you to manage a dashboard state in the following ways:

• API Overview
• Include a Dashboard State to URL
• Apply a Dashboard State during Server-Side Export
• Example 1: Specify a Default Dashboard State
• Example 2: Save a Dashboard State to Cookies
• Example 3: Clear Filter Values in a Dashboard State

API Overview

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

	API
Server-side	ASPxDashboard.InitialDashboardState ASPxDashboard.SetInitialDashboardState DashboardConfigurator.SetDashboardStateService
Client-side	ASPxClientDashboard.GetDashboardState ASPxClientDashboard.SetDashboardState ASPxClientDashboard.DashboardStateChanged

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

Include a Dashboard State to URL

You can supply end-users with the capability to share a dashboard state by appending it to the URL of the currently browsed dashboard. To do this, enable the ASPxDashboard.IncludeDashboardStateToUrl property.

In this case, the resulting link allows end-users to open the dashboard with the specified state. Note that these properties are in effect when the ASPxDashboard.WorkingMode is set to WorkingMode.Viewer or WorkingMode.ViewerOnly.

Note

You can also include the identifier of the selected dashboard to URL using the ASPxDashboard.IncludeDashboardIdToUrl property.

Apply a Dashboard State during Server-Side Export

You can apply a specified dashboard state when performing server-side exporting using methods exposed by the ASPxDashboardExporter class, for instance:

• WebDashboardExporter.ExportToPdf / WebDashboardExporter.ExportDashboardItemToPdf
• WebDashboardExporter.ExportToImage / WebDashboardExporter.ExportDashboardItemToImage
• WebDashboardExporter.ExportToExcel / WebDashboardExporter.ExportDashboardItemToExcel

To learn more, see Manage Exporting Capabilities.

Example 1: Specify a Default Dashboard State

The sample illustrates how to specify a dashboard state (such as 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 holds the required dashboard state. The ASPxDashboard.SetInitialDashboardState event is used to apply the specified dashboard state when loading a dashboard.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/aspxdashboard-how-to-specify-a-default-dashboard-state-in-code-t513681.

Default.aspx.cs

using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using System;
using System.Collections.Generic;

namespace WebDashboard_ManualDashboardState
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e) {
        }

        protected void ASPxDashboard1_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
            e.InitialState = InitializeDashboardState();
        }

        public DashboardState InitializeDashboardState() {
            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 dashboardState;
        }
    }
}

Default.aspx (C#)

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" 
    Inherits="WebDashboard_ManualDashboardState.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            DashboardStorageFolder="~/App_Data/Dashboards"
            WorkingMode="ViewerOnly"
            Height="100%" Width="100%" OnSetInitialDashboardState="ASPxDashboard1_SetInitialDashboardState">
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

Default.aspx.vb

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb
Imports System
Imports System.Collections.Generic

Namespace WebDashboard_ManualDashboardState
    Partial Public Class [Default]
        Inherits System.Web.UI.Page

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
        End Sub

        Protected Sub ASPxDashboard1_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
            e.InitialState = InitializeDashboardState()
        End Sub

        Public Function InitializeDashboardState() As DashboardState
            Dim dashboardState As New DashboardState()

            Dim parameterState As New DashboardParameterState("countryParameter", "USA", GetType(String))

            Dim gridFilterState As New DashboardItemState("gridDashboardItem1")
            gridFilterState.MasterFilterValues.AddRange(New List(Of Object())() From { _
                New String(0) { "Andrew Fuller" }, _
                New String(0) { "Laura Callahan" } _
            })

            Dim treemapDrilldownState As New DashboardItemState("treemapDashboardItem1")
            treemapDrilldownState.DrillDownValues.Add("Beverages")

            Dim rangeFilterState As New DashboardItemState("rangeFilterDashboardItem1")
            rangeFilterState.RangeFilterState.Selection = New RangeFilterSelection(New Date(2015, 1, 1), New Date(2016, 1, 1))

            dashboardState.Parameters.Add(parameterState)
            dashboardState.Items.AddRange(New List(Of DashboardItemState)() From {gridFilterState, treemapDrilldownState, rangeFilterState})
            Return dashboardState
        End Function
    End Class
End Namespace

Default.aspx (VB.NET)

<%@ Page Language="vb" AutoEventWireup="true" CodeBehind="Default.aspx.vb" 
    Inherits="WebDashboard_ManualDashboardState.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            DashboardStorageFolder="~/App_Data/Dashboards"
            WorkingMode="ViewerOnly"
            Height="100%" Width="100%" OnSetInitialDashboardState="ASPxDashboard1_SetInitialDashboardState">
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

Example 2: Save a Dashboard State to Cookies

The sample illustrates how to save the current ASPxDashboard state (such as master filter or parameter values) to cookies on the client side and restore this state on the server side. The following API is used in this example:

• The ASPxClientDashboard.DashboardStateChanged event is handled to obtain the current dashboard state.
• The ASPxClientUtils.SetCookie client-side method is used to save the dashboard state to cookies.
• In the ASPxDashboard.SetInitialDashboardState event handler, the dashboard state is loaded from the cookies and applied to a dashboard.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/aspxdashboard-how-to-save-a-dashboard-state-to-cookies-t513329.

Default.aspx (C#)

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" 
    Inherits="WebDashboard_DashboardStateCookies.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="ViewerOnly" 
            ClientInstanceName="webDashboard"
            IncludeDashboardIdToUrl="True"        
            DashboardStorageFolder="~/App_Data/Dashboards" 
            Height="100%" Width="100%" OnSetInitialDashboardState="ASPxDashboard1_SetInitialDashboardState">
            <ClientSideEvents DashboardStateChanged="
                function(s, e) {
                var cookies = e.DashboardState;
                ASPxClientUtils.SetCookie('ASPxDashboardState', cookies);
            }"></ClientSideEvents>
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

Default.aspx.cs

using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using System;
using System.Web;

namespace WebDashboard_DashboardStateCookies
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {            
        }

        protected void ASPxDashboard1_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e)
        {
            HttpCookie cookie = Request.Cookies["ASPxDashboardState"];
            if (cookie != null)
            {
                DashboardState dashboardState = new DashboardState();
                dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value));
                if (e.DashboardId == "dashboard1")
                    e.InitialState = dashboardState;
            }
        }
    }
}

Default.aspx.vb

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb
Imports System
Imports System.Web

Namespace WebDashboard_DashboardStateCookies
    Partial Public Class [Default]
        Inherits System.Web.UI.Page

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
        End Sub

        Protected Sub ASPxDashboard1_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
            Dim cookie As HttpCookie = Request.Cookies("ASPxDashboardState")
            If cookie IsNot Nothing Then
                Dim dashboardState As New DashboardState()
                dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value))
                If e.DashboardId = "dashboard1" Then
                    e.InitialState = dashboardState
                End If
            End If
        End Sub
    End Class
End Namespace

Default.aspx (VB.NET)

<%@ Page Language="vb" AutoEventWireup="true" CodeBehind="Default.aspx.vb" 
    Inherits="WebDashboard_DashboardStateCookies.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.3.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="ViewerOnly" 
            ClientInstanceName="webDashboard"
            IncludeDashboardIdToUrl="True"        
            DashboardStorageFolder="~/App_Data/Dashboards" 
            Height="100%" Width="100%" OnSetInitialDashboardState="ASPxDashboard1_SetInitialDashboardState">
            <ClientSideEvents DashboardStateChanged="
                function(s, e) {
                var cookies = e.DashboardState;
                ASPxClientUtils.SetCookie('ASPxDashboardState', cookies);
            }"></ClientSideEvents>
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

Example 3: Clear Filter Values in a Dashboard State

To clear filters (unselect all values) for a specific item, use the ASPxDashboard.SetInitialDashboardState event and assign an empty array of objects to the DashboardItemState.MasterFilterValues property:

C#

protected void ASPxDashboard1_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
    var state = new DashboardState();
    // ...
    var itemState = new DashboardItemState("comboBoxDashboardItem");
    itemState.MasterFilterValues.Add(new object[] { });
    state.Items.Add(itemState);
    // ...
    e.InitialState = state;
} 

VB.NET

Protected Sub ASPxDashboard1_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
    Dim state As New DashboardState()
    ' ...
    Dim itemState As New DashboardItemState("comboBoxDashboardItem")
    itemState.MasterFilterValues.Add(New Object[] { })
    state.Items.Add(itemState)
    ' ...
    e.InitialState = state
End Sub