ItemState Class

Contains states of individual dashboard items displayed in the dashboard.

Declaration

export class ItemState

Remarks

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.

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

Call the DashboardControl.setDashboardState method to apply a dashboard state to the loaded dashboard.

Properties

DrillDownValues Property

Specifies the current drill-down values.

Declaration

DrillDownValues?: Array<DevExpress.Dashboard.Data.PrimitiveType>

Property Value

Type
PrimitiveType[]

Remarks

The code below shows how to specify the drill-down values in the Customer Support demo when you set a dashboard state. The Chart’s drill-down value is Mobile. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
    "Items": {
      "chartProcessedIssuesByPlatform": {
        DrillDownValues: ["Mobile"]
      }
    } 
  });
}

MasterFilterValues Property

Specifies the selected master filter values stored in a dashboard state.

Declaration

MasterFilterValues?: Array<Array<DevExpress.Dashboard.Data.PrimitiveType>>

Property Value

Type
PrimitiveType[][]

Remarks

The code below shows how to apply the master filter values in the Sales Overview demo when you set a dashboard state. The Grid’s master filter values are Nevada and Texas. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
    "Items": {
      "gridSalesByState": {
        MasterFilterValues: [["Nevada"], ["Texas"]]
      }
    } 
  });
}

RangeFilterState Property

Specifies the state of the Range Filter and Date Filter dashboard items.

Declaration

RangeFilterState?: RangeFilterState

Property Value

Type	Description
RangeFilterState	A RangeFilterState object that specifies the state of the Range Filter and Date Filter dashboard items.

Remarks

The code below shows how to specify a predefined period (6 months) to a Range Filter when you set a 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() {
  //...
  control.setDashboardState({
      "Items": {
          "range": {
              RangeFilterState: {
                  PeriodName: "6 Months"
              }
          }
      }
  });
}

The code below shows how to apply a custom period (from January, 2017 to June, 2018) to a Range Filter when you set a dashboard state:

function onClick() {
  //...
  control.setDashboardState({
      "Items": {
          "range": {
              RangeFilterState: {
                  Selection: {
                      Minimum: new Date(2017, 0, 1),
                      Maximum: new Date(2018, 5, 1)
                  }
              }
          }
      }
  });
}

The code below clears states of the Range Filter and Date Filter dashboard items:

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.RangeFilterState = { };
      }) 
  }
  control.setDashboardState(JSON.stringify(state));

SelectedLayerIndex Property

Specifies the index of the selected dashboard item layer for the Pie, Card, Treemap, Gauge, and Choropleth Map dashboard items.

Declaration

SelectedLayerIndex?: number

Property Value

Type	Description
number	An integer value that specifies an index of the selected layer.

Remarks

The code below shows how to apply the selected layer index in the Sales Performance demo when you set a dashboard state. The Choropleth Map’s layer index is set to 2. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
    "Items": {
      "choroplethMapSalesByState": {
        SelectedLayerIndex: 2
      }
    } 
  });
}

TabPageName Property

Specifies the name of the selected tab page in the Tab Container.

Declaration

TabPageName?: string

Property Value

Type	Description
string	A string that is a component name of the selected tab page.

Remarks

The code below shows how to specify a tab page in the Sales Details demo when you set a dashboard state. The tab page’s name is set to pageDashboardItem3. MVCxDashboard is the client instance name of the DashboardControl.

function onClick() {
  var control = MVCxDashboard.GetDashboardControl();
  control.setDashboardState({
    "Items": {
      "tabContainerDashboardItem1": {
        TabPageName: "pageDashboardItem3"
        }            
      }
  });
}