dashboard-118733-web-dashboard-integrate-dashboard-component-aspnet-web-forms-dashboard-control-manage-dashboard-state.md
The dashboard state stores the state of individual dashboard items and dashboard parameter values. It can be master filter and drill-down values, active tab page, selected parameter values, and other results of user actions in a dashboard on the client.
On the server, the dashboard state is stored in a DashboardState class instance:
DashboardState dashboardState = new DashboardState();
DashboardParameterState parameterState =
new DashboardParameterState("countryParameter", "USA", typeof(string));
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>() {
treemapDrilldownState,
rangeFilterState }
);
Dim dashboardState As New DashboardState()
Dim parameterState As New DashboardParameterState("countryParameter", "USA", GetType(String))
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 {treemapDrilldownState, rangeFilterState})
Use the DashboardState.Items property to access the state of individual dashboard items:
DashboardItemState.MasterFilterValuesGets or sets selected master filter values stored in a dashboard state.DashboardItemState.DrillDownValues.DrillDownValuesGets or sets values for the drill-down hierarchy.DashboardItemState.TabPageNameGets the name of the tab page to which the dashboard item belongs.DashboardItemState.RangeFilterStateGets or sets the state of the Range Filter and Date Filter dashboard items.DashboardItemState.SelectedLayerIndexGets or sets an index of the selected dashboard item layer.
Use the DashboardState.Parameters property to access the selected dashboard parameter values.
You can use the following API to apply a DashboardState on the server:
ASPxDashboard.InitialDashboardStateGets or sets the initial dashboard state when loading a dashboard.ASPxDashboard.SetInitialDashboardStateAllows you to specify the initial dashboard state when loading a dashboard.DashboardConfigurator.SetDashboardStateServiceSpecifies a service that allows you to manage a dashboard state.
See the Examples section for implementation details.
Users can share a dashboard state by appending this state to the URL of the currently browsed dashboard. Enable the ASPxDashboard.IncludeDashboardStateToUrl property to display the state information in the URL. In this case, users can share a link to the dashboard with the applied state.
You can also add the identifier of the selected dashboard to the URL. For this, set the ASPxDashboard.IncludeDashboardIdToUrl property to true.
Note
These properties are in effect when the ASPxDashboard.WorkingMode is set to WorkingMode.Viewer or WorkingMode.ViewerOnly.
You can use the ASPxDashboardExporter to apply a dashboard state during the server-side export. For this, use the overload of the following methods with the dashboardState parameter:
For more information, see Manage Exporting Capabilities.
On the client, the dashboard state stores the same data: the state of individual dashboard items and dashboard parameter values. You can use the state as a JSON string or as a DashboardState object:
function setStateAsString() {
var currentState = `{"Items":{"listBoxDashboardItem1":{"MasterFilterValues":[["Beverages"]]},
"tabContainerDashboardItem1":{"TabPageName":"dashboardTabPage2"},
"cardDashboardItem1":{"SelectedLayerIndex":1}}}`
dashboardControl.GetDashboardControl().setDashboardState(currentState);
}
function setStateAsObject() {
dashboardControl.GetDashboardControl().setDashboardState({
"Parameters": {
"Year": 2008
},
"Items": {
"cardProductionImportByType": {
MasterFilterValues: [["Solid Fuels"]]
}
}
});
}
On the client, use the DashboardState.Items property to access the dashboard item’s state:
ItemState.MasterFilterValuesSpecifies the selected master filter values stored in a dashboard state.ItemState.DrillDownValuesSpecifies the current drill-down values.ItemState.TabPageNameSpecifies the name of the selected tab page in the Tab Container.ItemState.RangeFilterStateSpecifies the state of the Range Filter and Date Filter dashboard items.ItemState.SelectedLayerIndexSpecifies the index of the selected dashboard item layer for the Pie, Card, Treemap, Gauge, and Choropleth Map dashboard items.
Use the DashboardState.Parameters property to get access to the selected value of the dashboard parameters.
You can use the following API to apply the DashboardState on the client:
DashboardControlOptions.initialDashboardStateSpecifies the initial state of the loaded dashboard.DashboardControl.getDashboardStateGets the current dashboard state.DashboardControl.setDashboardStateApplies the dashboard state to the loaded dashboard.
The DashboardControlOptions.onDashboardStateChanged event occurs after the current dashboard state changes in the Web Dashboard. You can use this event to update the dashboard state value.
See the Examples section for implementation details.
To initialize the DashboardState object with the JSON object from the client, call the server-side DashboardStateExtensions.LoadFromJson method. Use DashboardStateExtensions.SaveToJson to save the current DashboardState object to JSON. Use the HttpRequest.Cookies property to get a collection of cookies sent by the client.
On the client, use the ASPxClientUtils.SetCookie method to create or update the HTTP cookie for the response. The document.cookie property reads and writes cookies associated with the document.
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.
View Example: How to specify a default dashboard state in code
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;
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb
Imports System
Imports System.Collections.Generic
Namespace WebDashboard_ManualDashboardState
Public Partial Class [Default]
Inherits 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 DashboardState = New DashboardState()
Dim parameterState As DashboardParameterState = New DashboardParameterState("countryParameter", "USA", GetType(String))
Dim gridFilterState As DashboardItemState = New DashboardItemState("gridDashboardItem1")
gridFilterState.MasterFilterValues.AddRange(New List(Of Object())() From {New String(0) {"Andrew Fuller"}, New String(0) {"Laura Callahan"}})
Dim treemapDrilldownState As DashboardItemState = New DashboardItemState("treemapDashboardItem1")
treemapDrilldownState.DrillDownValues.Add("Beverages")
Dim rangeFilterState As DashboardItemState = 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(Of DashboardItemState)() From {gridFilterState, treemapDrilldownState, rangeFilterState})
Return dashboardState
End Function
End Class
End Namespace
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:
View Example: How to save a dashboard state to cookies
On the server, the dashboard state is loaded from the cookies and applied to e.InitialState property to set the initial state of the loaded dashboard:
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) {
// Requests the "dashboardState" cookie:
HttpCookie cookie = Request.Cookies["dashboardState"];
if (cookie != null) {
DashboardState dashboardState = new DashboardState();
// Initializes a DevExpress.DashboardCommon.DashboardState object from the JSON state:
dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value));
if (e.DashboardId == "dashboard1")
// Applies the initial dashboard state if it exists in cookies:
e.InitialState = dashboardState;
}
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb
Imports System
Imports System.Web
Namespace WebDashboard_DashboardStateCookies
Public Partial Class [Default]
Inherits 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)
' Requests the "dashboardState" cookie:
Dim cookie As HttpCookie = Request.Cookies("dashboardState")
If cookie IsNot Nothing Then
Dim dashboardState As DashboardState = New DashboardState()
' Initializes a DevExpress.DashboardCommon.DashboardState object from the JSON state:
dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value))
' Applies the initial dashboard state if it exists in cookies:
If Equals(e.DashboardId, "dashboard1") Then e.InitialState = dashboardState
End If
End Sub
End Class
End Namespace
On the client, the control saves the dashboard state to cookies every time the state changes.
function onBeforeRender(sender) {
const dashboardControl = sender.GetDashboardControl();
if (dashboardControl)
dashboardControl.on('dashboardStateChanged', onDashboardStateChanged);
}
function onDashboardStateChanged(e) {
// Set the number of days until the cookie should expire (exdays):
const exdays = 1;
const date = new Date();
date.setTime(date.getTime() + (exdays * 24 * 60 * 60 * 1000));
let expires = "expires=" + date.toUTCString();
// Get the dashboard state:
let dState = "dashboardState=" + e.component.getDashboardState() + ";";
// Assign the cookie name (dashboardState), the cookie value, and the expires string to document.cookie:
document.cookie = dState + expires + ";path=/";
}
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs"
Inherits="WebDashboard_DashboardStateCookies.Default" %>
<%@ Register Assembly="DevExpress.Dashboard.v24.2.Web.WebForms, Version=24.2.13.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a"
Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title>Web Dashboard Application</title>
<script src="Script.js"></script>
</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 BeforeRender="onBeforeRender"></ClientSideEvents>
</dx:ASPxDashboard>
</div>
</form>
</body>
</html>
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.
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));
}
Note
The control variable is the obtained DashboardControl instance. Refer to the Extensions Overview topic for information on how to obtain a DashboardControl for each platform.