Manage Dashboard State
- 8 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 | |
current drill-down levels | |
a selected tab page | |
Range Filter/Date Filter settings | |
a selected dashboard item layer[1] | |
selected parameter values |
API Overview
The DashboardState class represents a dashboard’s state on the server side and 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 | |
Client-side | ASPxClientDashboard.GetDashboardState |
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 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 DashboardExtensionSettings.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.
Note
You can also include the identifier of the selected dashboard to URL using the DashboardExtensionSettings.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 DashboardConfigurator.SetDashboardStateService method is used to apply the specified dashboard state when loading a dashboard.
using DevExpress.DashboardWeb;
using DevExpress.DashboardWeb.Mvc;
using System.Web.Routing;
namespace MvcDashboard_DefaultDashboardState {
public static class DashboardConfig {
public static void RegisterService(RouteCollection routes) {
routes.MapDashboardRoute("dashboardControl");
DashboardFileStorage dashboardFileStorage = new DashboardFileStorage("~/App_Data/Dashboards");
DashboardConfigurator.Default.SetDashboardStorage(dashboardFileStorage);
DashboardConfigurator.Default.SetDashboardStateService(new CustomDashboardStateService());
}
}
}
<script type="text/javascript">
function onBeforeRender(sender) {
var control = sender.getDashboardControl();
control.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(control));
}
</script>
@Html.DevExpress().Dashboard(settings => {
settings.Name = "Dashboard";
settings.WorkingMode = DevExpress.DashboardWeb.WorkingMode.Viewer;
settings.Width = Unit.Percentage(100);
settings.Height = Unit.Percentage(100);
settings.ClientSideEvents.BeforeRender = "onBeforeRender";
}).GetHtml()
using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using System;
using System.Collections.Generic;
namespace MvcDashboard_DefaultDashboardState {
public class CustomDashboardStateService : IDashboardStateService {
public DashboardState GetState(string dashboardId, System.Xml.Linq.XDocument dashboard) {
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;
}
}
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Mvc;
using System.Web.Routing;
namespace MvcDashboard_DefaultDashboardState {
// Note: For instructions on enabling IIS6 or IIS7 classic mode,
// visit http://go.microsoft.com/?LinkId=9394801
public class MvcApplication : System.Web.HttpApplication {
protected void Application_Start() {
DashboardConfig.RegisterService(RouteTable.Routes);
AreaRegistration.RegisterAllAreas();
GlobalConfiguration.Configure(WebApiConfig.Register);
FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
RouteConfig.RegisterRoutes(RouteTable.Routes);
ModelBinders.Binders.DefaultBinder = new DevExpress.Web.Mvc.DevExpressEditorsBinder();
DevExpress.Web.ASPxWebControl.CallbackError += Application_Error;
}
protected void Application_Error(object sender, EventArgs e) {
Exception exception = System.Web.HttpContext.Current.Server.GetLastError();
//TODO: Handle Exception
}
}
}
Example 2: Save a Dashboard State to Cookies
The sample illustrates how to save the current ASP.NET MVC Dashboard 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.
- The DashboardConfigurator.SetDashboardStateService method is used to apply the dashboard state loaded from the cookies.
using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using System.Web;
using System.Xml.Linq;
namespace MvcDashboard_DashboardStateCookies {
internal class CustomDashboardStateService : IDashboardStateService {
public DashboardState GetState(string dashboardId, XDocument dashboard) {
HttpCookie cookie = HttpContext.Current.Request.Cookies["MVCxDashboardState"];
if (cookie != null) {
DashboardState dashboardState = new DashboardState();
dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value));
return dashboardState;
}
else
return null;
}
}
}
using System;
using System.Web.Mvc;
using System.Web.Routing;
namespace MvcDashboard_DashboardStateCookies {
public class MvcApplication : System.Web.HttpApplication {
protected void Application_Start() {
DashboardConfig.RegisterService(RouteTable.Routes);
AreaRegistration.RegisterAllAreas();
FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
RouteConfig.RegisterRoutes(RouteTable.Routes);
ModelBinders.Binders.DefaultBinder = new DevExpress.Web.Mvc.DevExpressEditorsBinder();
DevExpress.Web.ASPxWebControl.CallbackError += Application_Error;
}
protected void Application_Error(object sender, EventArgs e) {
Exception exception = System.Web.HttpContext.Current.Server.GetLastError();
}
}
}
<script type="text/javascript">
function onDashboardStateChanged(s, e) {
var cookies = e.DashboardState;
ASPxClientUtils.SetCookie('MVCxDashboardState', cookies);
}
</script>
@Html.DevExpress().Dashboard(settings => {
settings.Name = "Dashboard";
settings.WorkingMode = DevExpress.DashboardWeb.WorkingMode.ViewerOnly;
settings.Width = Unit.Percentage(100);
settings.Height = Unit.Percentage(100);
settings.ClientSideEvents.DashboardStateChanged = "onDashboardStateChanged";
}).GetHtml()
using DevExpress.DashboardWeb;
using DevExpress.DashboardWeb.Mvc;
using System.Web.Routing;
namespace MvcDashboard_DashboardStateCookies {
public static class DashboardConfig {
public static void RegisterService(RouteCollection routes) {
routes.MapDashboardRoute("dashboardControl");
DashboardFileStorage dashboardFileStorage = new DashboardFileStorage("~/App_Data/Dashboards");
DashboardConfigurator.Default.SetDashboardStorage(dashboardFileStorage);
DashboardConfigurator.Default.SetDashboardStateService(new CustomDashboardStateService());
}
}
}
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.