drillMembers

Property is read-only. It cannot be set in script.

Returns an array of the levels at which the user has made a selection. The array includes all levels from the top level to one level below the current selection. (The top level is included even when no selection is made.)

drillMembers does not apply to Selection Lists.

For example, consider a three-level Selection Tree hierarchy: Region  State  City.

Selection Tree 3 Level 1

If the user makes a selection at the level of region, drillMembers returns the array ['Region','State']. If the user makes a selection at the level of state or city, drillMembers returns the array ['Region','State','City']. This array is useful for displaying multiple geographical levels on a map, as shown in the example below.

Type

Array

array of field names for selected levels

Example

Follow the steps below to create a dynamic multi-level map drill:

  1. Create a new Dashboard based on the ‘Sales Explore’ Data Worksheet. (See Create a New Dashboard.)

    The 'Sales Explore' Data Worksheet can be found in Data Worksheet  Examples. You may need to download the examples.zip file from GitHub into your environment. (This requires access to Enterprise Manager.) See Import and Export Assets for instructions on how to import.

  2. From the Toolbox panel, drag a Chart component into the Dashboard. Resize the Chart as desired.

  3. From the Toolbox panel, drag a Selection Tree component into the Dashboard.

  4. Add a two-level geographical hierarchy to the Selection Tree. Follow the steps below:

    1. Expand the ‘Sales’ data block in the Toolbox panel.

    2. Drag the ‘State’ field from the data block onto the Selection Tree. This adds the ‘State’ values to the tree.

    3. Drag the ‘City’ field from the data block onto the Selection Tree. This adds the ‘City’ values to the tree.

    4. Resize the Selection Tree so that it can display a reasonable number of options.

      DrillMembersExample1

  5. Press the ‘Edit’ button edit on the Chart to open the Visualization Recommender. Press the ‘Full Editor’ button edit at the top right of the Recommender to bypass the Recommender and open the Chart Editor.

  6. Press the ‘Select Chart Style’ button auto chart type in the Data panel, and choose the ‘Map’ chart type.

  7. In the Data Source panel, right click on the ‘State’ field, and select ‘Set Geographic’.

  8. In the Data Source panel, right click on the ‘City’ field, and select ‘Set Geographic’.

    DrillMembersExample3

    A red question mark indicates that not all cities in the ‘City’ field of this example have mappings.

  9. From the Data Source panel of the Chart Editor, drag the ‘Total’ measure to the ‘Color’ region in the Visual panel.

  10. From the Data Source panel of the Chart Editor, drag the ‘State’ dimension to the ‘Geographic’ region in the Data panel.

  11. Configure the Chart to adapt the geographical level based on the user’s selection in the Selection Tree. To do this, follow the steps below:

    1. Press the ‘Value Type’ button function and variable button next to the ‘State’ dimension in the Data panel. In the pop-up menu, select the ‘Expression’ option.

      DrillMembersExample5

    2. Press the ‘Edit Formula’ button formula edit to open the Script Editor.

      DrillMembersExample6

    3. In the top-left panel of the Script Editor, expand the SelectionTree1 node, and click drillMembers (not drillMember). This adds the SelectionTree1.drillMembers property in the editing area.

      DrillMembersExample7

      If the user makes no selection in the Selection Tree, the drillMembers property returns the array ['State'], which displays the ‘Total’ measure on a state-basis. If the user selects one or more states or cities in the Selection Tree, drillMembers returns the array ['State','City'], which displays the ‘Total’ measure on a city-basis.

    4. Press OK to close the Script Editor. The output of SelectionTree1.drillMembers is now assigned to the Chart Geographical binding.

      DrillMembersExample8

  12. Verify that the map adapts to the user’s selections:

    1. Press the ‘Clear Selection’ button 24 in the Selection Tree to remove any existing selections. Observe that the map represents the measure on a state level, the top level of the Selection Tree hierarchy.

      DrillMembersExample10

    2. Select the ‘CA’ option in the Selection Tree. Observe that the Selection Tree filters the map to display only data from California. In addition, the drillMembers property changes the geographical binding to represent the ‘City’ dimension, and the measure is now displayed at the city-level.

      DrillMembersExample9

To automatically zoom a map to display only the regions that the user selects, see the example for Coordinate.setFullMap(boolean).

Either syntax below can be used in component script:

drillMembers                       // unqualified
SelectionTree1.drillMembers     // qualified

For onInit/onRefresh scripts, and for component and property scripts on other components, the second (qualified) form is required.