GetFieldSelections - chart function
GetFieldSelections() returns a string with the current selections in a field.
If all but two, or all but one of the values are selected, the format 'NOT x,y' or 'NOT y' will be used respectively. If you select all values and the count of all values is greater than max_values, the text ALL will be returned.
Syntax:
GetFieldSelections ( field_name [, value_sep [, max_values [, state_name]]])
Return data type: string
| Format | Description |
|---|---|
| 'a, b, c' |
If the number of selected values is max_values or less, the string returned is a list of the selected values. The values are separated with value_sep as delimiter. |
| 'NOT a, b, c' |
If the number of non-selected values is max_values or less, the string returned is a list of the non-selected values with NOT as a prefix. The values are separated with value_sep as delimiter. |
| 'x of y' |
x = the number of selected values y = the total number of values This is returned when max_values < x < ( y - max_values). |
| 'ALL' | Returned if all values are selected. |
| '-' | Returned if no value is selected. |
| <search string> | If you have selected using search, the search string is returned. |
| Arguments | Description |
|---|---|
| field_name | The field containing the range of data to be measured. |
| value_sep | The separator to be put between field values. The default is ', '. |
| max_values |
The maximum number of field values to be individually listed. When a larger number of values is selected, the format 'x of y values' will be used instead. The default is 6. |
| state_name |
The name of an alternate state that has been chosen for the specific visualization. If the state_name argument is used, only the selections associated with the specified state name are taken into account. For more information, see Using alternate states for comparative analysis. |
| Example | Result |
|---|---|
|
GetFieldSelections( FirstName ) |
Returns '-' (NULL) if no selection has been made in the FirstName field. Otherwise, it returns the value of the selections, for example John. |
Example - GetFieldSelections fundamentals
Overview
Open the Data load editor and add the load script below to a new section.
The load script contains:
-
A dataset which is loaded into a data table called Example.
-
The following fields in the data table:
-
FirstName
-
LastName
-
Initials
-
HasCellphone
-
Load script
Example:
LOAD * inline [
FirstName|LastName|Initials|HasCellphone
John|Anderson|JA|Yes
Sue|Brown|SB|Yes
Mark|Carr|MC|No
Peter|Devonshire|PD|No
Jane|Elliot|JE|Yes
Peter|Franc|PF|Yes ] (delimiter is '|');Results
-
Load the data and open a sheet. Create a new filter pane and add this field as a dimension:
-
FirstName
-
-
Create a KPI object and add the following measure:
-
=GetFieldSelections(FirstName), to return the values of the selection made in the FirstName field.
Tip noteIn this example the styling of the KPI has been adjusted to use a responsive layout behavior to make it easier to view the output. For more information about changing the chart layout behavior, see Styling the KPI -
-
Click Edit sheet to switch to analysis mode, and do the following actions in the order that they appear in the table:
Actions and results in analysis mode Action KPI results Select John in the FirstName filter. The measure returns the value: John.
Select John and Peter in the FirstName filter. The measure returns the values: John, Peter.
Click Edit sheet to switch to edit mode, and then edit the KPI measure expression to the following: =GetFieldSelections(FirstName,'; ') The measure returns the values with the new value_sep format: John; Peter.
Edit the KPI measure expression to the following: =GetFieldSelections(FirstName,';', 2) The measure returns the values with the new value_sep format spacing: John;Peter.
Click Edit sheet to switch back to analysis mode. Clear the selections from the FirstName filter, and then select John, Sue, and Mark. The measure returns NOT Jane;Peter, because the number of selections exceeds the max_value argument of 2. If no max_value is set, all selected names will appear: John; Sue; Mark.
The following image shows the results of the last action in the table where the number of selections exceeds the max_values argument.
KPI results when selecting the first names John, Sue, and Mark
In this example you can see how the values returned by the GetFieldSelections function change as selections are made.
Example - GetFieldSelections scenario
Overview
The GetFieldSelections function is used to highlight customer names as they are selected.
Open the Data load editor and add the load script below to a new section.
The load script contains:
-
A dataset which is loaded into a data table called Example.
-
The following fields in the data table:
-
OrderID
-
CustomerName
-
Product
-
Quantity
-
Load script
Example:
LOAD * INLINE [
OrderID, CustomerName, Product, Quantity
1, John Doe, Laptop, 2
2, Jane Smith, Smartphone, 1
3, Ahmed Khan, Desk, 3
4, Maria Garcia, Chair, 1
5, Li Wei, Blender, 2
];Results
-
Load the data and open a sheet. Create a new filter pane and add these fields as dimensions:
-
CustomerName
-
Product
-
Create a KPI object and add the following measure:
-
=GetFieldSelections(CustomerName).
Tip noteIn this example the styling of the KPI has been adjusted to use a responsive layout behavior to make it easier to view the output. For more information about changing the chart layout behavior, see Styling the KPI. -
-
Click Edit sheet to switch to analysis mode, and then select Jane Smith and John Doe from the CustomerName filter.
The GetFieldSelections function returns the values: Jane Smith, John Doe.
You can see the customers selected in the filter pane in the KPI.