Manage Dashboard State in JavaScript Applications

• Mar 13, 2023
• 4 minutes to read

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.

API Overview

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

Client-side API	Description
DashboardControl.getDashboardState	Gets the current dashboard state.
DashboardControl.setDashboardState	Applies the dashboard state to the loaded dashboard.
DashboardControlOptions.onDashboardStateChanged	A handler for the event that occurs after the current dashboard state in the Web Dashboard is changed.
DashboardControlOptions.initialDashboardState	Specifies the initial state of the loaded dashboard.

Use the initialDashboardId option to set the identifier of the dashboard to which the state is applied.

To specify the initial dashboard state, initialize the DashboardState object on a server, save this object to JSON using the DashboardStateExtensions.SaveToJson extension method and assign the resulting string to the initialDashboardState property.

The following code shows how to pass a string that contains a dashboard state saved in JSON format to the initialDashboardState property:

var dashboardControl = new DashboardControl(this.element.nativeElement.querySelector(".dashboard-container"),  {
  endpoint: "https://demos.devexpress.com/services/dashboard/api",
  workingMode: "Viewer",
  initialDashboardState: "{\"Items\":{\"gridSalesByState\":{\"MasterFilterValues\":[[\"Nevada\"]]}}}",
});

Include a Dashboard State to URL

You can enable the UrlStateExtensionOptions.includeDashboardStateToUrl property to include the dashboard state in the browsed dashboard’s URL and allow users to share the dashboard state. In this case, the resulting link allows users to open the dashboard with the specified state.

The code sample below shows how to include the dashboard state in the URL:

var dashboardControl = new DashboardControl(this.element.nativeElement.querySelector(".dashboard-container"),  {
    endpoint: "https://demos.devexpress.com/services/dashboard/api",
    workingMode: "Viewer",
    extensions: {
        "urlState": {
            includeDashboardStateToUrl: true
        }
    }
});

You can also include the identifier of the selected dashboard in the URL. For this, set the UrlStateExtensionOptions.includeDashboardIdToUrl property to true.

Note

These properties are in effect when the DashboardControlOptions.workingMode is set to Viewer or ViewerOnly.

The Dashboard Control for JavaScript does not read the dashboard state and dashboard identifier from the URL. You can also parse URL parameters and pass the values to the corresponding control options.

Examples

How to Apply a Dashboard State

The following example shows how to apply the dashboard state to the Energy Statistics demo. The Year parameter is 2008, the Card‘s master filter value is Solid Fuels. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
    "Parameters": {
      "Year": 2008
    },
    "Items": {
      "cardProductionImportByType": {
          MasterFilterValues: [["Solid Fuels"]]
      }
    }
  });
}

The code below shows how to apply the dashboard state to the Sales Overview demo. The Range Filter‘s predefined period is 6 Month, the Grid‘s master filter value is Nevada. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
      "Items": {
      "gridSalesByState": {
        MasterFilterValues: [["Nevada"]]
      },
      "range": {
        RangeFilterState: {
          PeriodName: "6 Months"
        }
      }
     }
  });
}

How to 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, pass an empty object of a dashboard item state to the entire dashboard state.

Note

The control variable in the example below is the obtained DashboardControl instance. Refer to the following topic for information on how to obtain a DashboardControl for each platform: Web Dashboard - Client-Side Specifics.

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