The requested page is not available for the requested platform. You are viewing the content for Default platform.
All docs
V19.1
19.2 (EAP/Beta)
19.1
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Manage Dashboard State

  • 3 min 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

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

API Overview

The DashboardState class represents a dashboard's state on the server side and includes individual dashboard items' states (the DashboardState.Items property) and the selected parameter values (DashboardState.Parameters). On the client side, a 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 occurring 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](xref:DevExpress.DashboardWeb.DashboardStateExtensions.SaveToJson(DevExpress.DashboardCommon.DashboardState) 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 include a dashboard state in the browsed dashboard's URL to allow end-users to share a dashboard state. To do this, enable the UrlStateExtensionOptions.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 DashboardControlOptions.workingMode is set to "Viewer" or "ViewerOnly".

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

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

You can also include the selected dashboard's identifier in a URL using the UrlStateExtensionOptions.includeDashboardIdToUrl property.

Examples

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.

public btnClick() {
  var state: DashboardState = { 
    Parameters:{ 
      "Year": 2008 
    }, 
    Items: {
      "cardProductionImportByType": {
        MasterFilterValues: [["Solid Fuels"]]
      }
    } 
  }
  this.dashboardControl.setDashboardState(state);
}

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.

public btnClick() {
  var state: DashboardState = { 
    // ... 
    Items: {
      "gridSalesByState": {
        MasterFilterValues: [["Nevada"]]
      },
      "range": {
        RangeFilterState: {
          PeriodName: "6 Months"
        }
      }
    } 
  }
  this.dashboardControl.setDashboardState(state);
}