Handling column selections using a property

This is an example of how you can use a document property to control the column selection of an axis from a text area. If you already have defined suitable properties to use, you can connect them to axes directly by right-clicking and selecting Set from Property.

Before you begin

The functionality described here must be authored using the installed client.

About this task

In the bar charts below, the column to color the bar chart by is selected from the text area rather than being configured on the Color by selector in the visualization. The text area contains a property control, here in form of a drop-down list, where a dashboard user can choose which column to color the bar chart by. The ordinary Color by selector is no longer available in the bar chart.

Note: Only string properties can be used on axes. In this context, the property should contain a value that can be interpreted as a column or a column expression. The string value of the property will be interpreted as a column name or a property expression. See Properties in expressions for more information about the syntax for property expressions.

Follow the steps to create this type of analysis.

Before you begin

Some of the functionality described here can only be authored or accessed using the installed Spotfire client.

Procedure

Create or edit a text area.
In edit mode, add the property control to the text area. In this example, we add a drop-down list.
In the Property Control dialog, the items that should be available for selection in the drop-down list are defined. However, the actual property to be controlled does not yet exist. To create it, click New to open the New Property dialog, where you give the property a name and specify its data type. In this example we call it 'SelectColorBy'.
When the property exists and has been selected, define the values the property should be able to have. In this example, the value of the property is either 'Category' or 'Type', as you want to color the bar chart by either of these columns. The settings are made in the lower part of the Property Control dialog. These property values are set through Column selection, and an 'or' expression is used to define the two columns to include.

Tip: You can use any search expression to determine which columns to show in a property control. For example, use datatype:integer to show integer columns only, use datatype:real to show real columns only, use "A or B" to show columns beginning with the letters A or B only, and so on. You can also search for a particular column property. The Select Columns dialog is a shortcut to creating column properties and selecting columns based on these properties. For example, use included.column:true if you have added a custom column property called included.column with the default value false and the value true for those columns you want to be available. See also Searching in Spotfire clients for more information about search expressions.
The last step is to connect the property to the place that should react on the selected property value, in this case the Color by selector in the bar chart. Right-click the selector, choose Set from Property, and select the new property.
Click OK.

Results

The color axis now uses the value from the selected property to determine the column selection.

Using multiple document properties to determine the columns to show on an axis

You can add more than one property to an axis expression, if you want the axis to show multiple values or a hierarchy.

Procedure

Right-click the axis selector for the axis of interest and select Custom Expression from the pop-up menu.
Insert the property of interest into the expression using the text syntax. For example, ${MyProperty}.
For more information about the different syntaxes available for properties, see Properties in expressions.

See Adding or editing a document property for information about how to add a new property. Note that the data type of this type of property must be String.
Add as many properties as you like to the expression.
For a continuous axis with multiple columns based on different properties, separate each property with a comma:
```
 ${MyProperty}, ${MyProperty2}, ${MyProperty3}
```
For a categorical axis, specify how the categories should be handled using NEST or CROSS:
```
<[${MyProperty}] NEST [${MyProperty2}] NEST [${MyProperty3}]>
```
If the string value consists of several words (e.g., "My Value"), then you must use $esc() or put brackets around the property expression to return a column: [${MyProperty}].
If desired, you can edit the expression for more complex calculations. When you are ready, click OK.

Results

The visualization axis uses the default value of the properties as different columns. You can add property controls in a text area, as described in the previous example, for easy update of the property values.