Manage Dashboard State

• Jul 05, 2019
• 8 minutes to read

A dashboard state describes the result of client actions end-users perform on a dashboard:

State Value	API
selected master filters values	ItemState.MasterFilterValues
current drill-down levels	ItemState.DrillDownValues
a selected tab page	ItemState.TabPageName
Range Filter settings	ItemState.RangeFilterState
a selected dashboard item layer1	ItemState.SelectedLayerIndex
selected parameter values	DashboardState.Parameters

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

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

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	DashboardExtensionSettings.InitialDashboardState 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 DashboardExtensionSettings.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 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.

Note

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

HomeController.vb

Imports System.Web.Mvc

Namespace MvcDashboard_DefaultDashboardState.Controllers
    Public Class HomeController
        Inherits Controller

        Public Function Index() As ActionResult
            Return View()
        End Function
    End Class
End Namespace

DashboardConfig.vb

Imports System.Web.Routing
Imports DevExpress.DashboardWeb
Imports DevExpress.DashboardWeb.Mvc

Namespace MvcDashboard_DefaultDashboardState
    Public NotInheritable Class DashboardConfig

        Private Sub New()
        End Sub

        Public Shared Sub RegisterService(ByVal routes As RouteCollection)
            routes.MapDashboardRoute("dashboardControl")
            Dim dashboardFileStorage As New DashboardFileStorage("~/App_Data/Dashboards")
            DashboardConfigurator.Default.SetDashboardStorage(dashboardFileStorage)

            DashboardConfigurator.Default.SetDashboardStateService(New CustomDashboardStateService())
        End Sub
    End Class
End Namespace

Index.cshtml (VB.NET)

<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()

CustomDashboardStateService.vb

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb

Namespace MvcDashboard_DefaultDashboardState
    Public Class CustomDashboardStateService
        Implements IDashboardStateService

        Public Function GetState(ByVal dashboardId As String, ByVal dashboard As XDocument) As DashboardState Implements IDashboardStateService.GetState
            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

Global.asax.vb

Imports System.Web.Http
Imports System.Web.Mvc
Imports 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
        Inherits System.Web.HttpApplication

        Protected Sub Application_Start()
            DashboardConfig.RegisterService(RouteTable.Routes)
            AreaRegistration.RegisterAllAreas()

            GlobalConfiguration.Configure(AddressOf WebApiConfig.Register)
            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters)
            RouteConfig.RegisterRoutes(RouteTable.Routes)

            ModelBinders.Binders.DefaultBinder = New DevExpress.Web.Mvc.DevExpressEditorsBinder()

            AddHandler DevExpress.Web.ASPxWebControl.CallbackError, AddressOf Application_Error
        End Sub

        Protected Sub Application_Error(ByVal sender As Object, ByVal e As EventArgs)
            Dim exception As Exception = System.Web.HttpContext.Current.Server.GetLastError()
            'TODO: Handle Exception
        End Sub
    End Class
End Namespace

CustomDashboardStateService.cs

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;
        }
    }
}

HomeController.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;

namespace MvcDashboard_DefaultDashboardState.Controllers {
    public class HomeController : Controller {
        public ActionResult Index() {
            return View();
        }
    }
}

Global.asax.cs

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
        }
    }
}

DashboardConfig.cs

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());
        }
    }
}

Index.cshtml (C#)

<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()

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.

Note

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

CustomDashboardStateService.cs

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;
        }
    }
}

Global.asax.cs

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();
        }
    }
}

HomeController.cs

using System.Web.Mvc;

namespace MvcDashboard_DashboardStateCookies.Controllers {
    public class HomeController : Controller {
        public ActionResult Index() {
            return View();
        }
    }
}

Index.cshtml (C#)

<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()

DashboardConfig.cs

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());
        }
    }
}

HomeController.vb

Imports System.Web.Mvc

Namespace MvcDashboard_DashboardStateCookies.Controllers
    Public Class HomeController
        Inherits Controller

        Public Function Index() As ActionResult
            Return View()
        End Function
    End Class
End Namespace

DashboardConfig.vb

Imports System.Web.Routing
Imports DevExpress.DashboardWeb
Imports DevExpress.DashboardWeb.Mvc

Namespace MvcDashboard_DashboardStateCookies
    Public NotInheritable Class DashboardConfig

        Private Sub New()
        End Sub

        Public Shared Sub RegisterService(ByVal routes As RouteCollection)
            routes.MapDashboardRoute("dashboardControl")

            Dim dashboardFileStorage As New DashboardFileStorage("~/App_Data/Dashboards")
            DashboardConfigurator.Default.SetDashboardStorage(dashboardFileStorage)

            DashboardConfigurator.Default.SetDashboardStateService(New CustomDashboardStateService())
        End Sub
    End Class
End Namespace

CustomDashboardStateService.vb

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb

Namespace MvcDashboard_DashboardStateCookies
    Friend Class CustomDashboardStateService
        Implements IDashboardStateService

        Public Function GetState(ByVal dashboardId As String, ByVal dashboard As XDocument) As DashboardState Implements IDashboardStateService.GetState
            Dim cookie As HttpCookie = HttpContext.Current.Request.Cookies("MVCxDashboardState")
            If cookie IsNot Nothing Then
                Dim dashboardState As New DashboardState()
                dashboardState.LoadFromJson(HttpUtility.UrlDecode(cookie.Value))
                Return dashboardState
            Else
                Return Nothing
            End If
        End Function
    End Class
End Namespace

Index.cshtml (VB.NET)

<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()

Global.asax.vb

Imports System.Web.Mvc
Imports System.Web.Routing

Namespace MvcDashboard_DashboardStateCookies
    Public Class MvcApplication
        Inherits System.Web.HttpApplication

        Protected Sub Application_Start()
            DashboardConfig.RegisterService(RouteTable.Routes)
            AreaRegistration.RegisterAllAreas()

            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters)
            RouteConfig.RegisterRoutes(RouteTable.Routes)

            ModelBinders.Binders.DefaultBinder = New DevExpress.Web.Mvc.DevExpressEditorsBinder()

            AddHandler DevExpress.Web.ASPxWebControl.CallbackError, AddressOf Application_Error
        End Sub

        Protected Sub Application_Error(ByVal sender As Object, ByVal e As EventArgs)
            Dim exception As Exception = System.Web.HttpContext.Current.Server.GetLastError()
        End Sub
    End Class
End Namespace