ItemState Class

Contains states of individual dashboard items displayed in the dashboard.

Declaration

export class ItemState

Remarks

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	ItemState.MasterFilterValues
current drill-down levels	ItemState.DrillDownValues
a selected tab page	ItemState.TabPageName
Range Filter/Date Filter settings	ItemState.RangeFilterState
a selected dashboard item layer[1]	ItemState.SelectedLayerIndex
selected parameter values	DashboardState.Parameters

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

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

Footnotes

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

Properties

DrillDownValues Property

Specifies values for the drill-down hierarchy.

Declaration

DrillDownValues?: Array<PrimitiveType>

Property Value

Type	Description
Array<PrimitiveType>	An array of the PrimitiveType objects that specify values for the drill-down hierarchy.

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 selected master filter values stored in a dashboard state.

Declaration

MasterFilterValues?: Array<Array<PrimitiveType>>

Property Value

Type	Description
Array<Array<PrimitiveType>>	An array of the PrimitiveType object arrays that specify selected master filter values.

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 examples 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() {
  //...
  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 an index of the selected dashboard item layer.

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 selected tab page name for 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"
        }            
      }
  });
}