Using Properties in the Analysis

Properties can control one or many settings by being applied in custom expressions. For example, a document property can be used to specify a column name. This property can then be used to define what is shown on one or more visualization axes, either directly or as a part of a custom expression. By using a property instead of simply placing the column name directly on the axes, you only need to change a single value (the property value) in order to change all axes where the property is used. Adding a property control that can change the property value further simplifies the update process.

Since the property controls are available in Spotfire Web Player, this also gives the Web Player users a possibility to change the axes of visualizations. Property expressions can also be used to define a line or a curve. If a property used in expressions is updated, the property will be updated in all currently used locations.

To use a document property to control column selection on an axis:

Create one or more visualizations.
Right-click on the axis selector for the axis of interest and select Set from Property... from the pop-up menu.

Response: The Set from Property dialog is displayed.
In the Select the property to use list, click to select the property of interest.

Comment: If you have not previously created a property, click New... to define a new property. Note that this type of property can only be of the data type String.
Click OK.

Response: The visualization axis uses the default value of the property.

To use a document property as a part of a multiple columns custom expression:

When properties are added to a custom expression using the Insert Properties button they are by default inserted as text. However, you may need to manually edit the expression syntax. For more information about the different syntaxes see Properties in Expressions.

Create one or more visualizations.
Right-click on the axis selector for the axis of interest and select Custom Expression... from the pop-up menu.

Response: The Custom Expression dialog is displayed.
In the list of Available properties, right-click on the property of interest.

Comment: If you have not previously created a property, you can right-click in the Available properties list and select New > Document Property... to define a new property. Note that the data type of this type of property must be String.

Response: A pop-up menu is displayed.
Select Insert as Text from the pop-up menu.

Response: The property is added to the expression using the text syntax. For example, ${MyProperty}.
You can add more properties to the expression by repeating the steps above. To interpret each property as one column, you also need to separate the properties with a comma:
${MyProperty}, ${MyProperty2}, ${MyProperty3}
If desired, you can edit the expression for more complex calculations. For just a simple property-controlled multiple columns axis, click OK.

Response: The visualization axis uses the default value of the properties.

To add a drop-down list that changes a property holding a column name:

Create a text area where you want the control to reside.
Click on the Toggle Edit Mode button, , in the text area title bar.

Comment: You can also right-click and select Edit Text Area from the pop-up menu.
Type some descriptive text in the text area regarding what the control will do.

Comment: This can be important to help other users of the analysis file understand what will happen when they change the selection of the control.
Click on the Insert Property Control button, , and select the Drop-down list option.

Response: The Property Control dialog is displayed.
Click to select the property of interest in the Select property list.

Comment: Use the search field if you cannot find your property. You can also specify a new property by clicking New....
Select Set property value through: Column selection.

Comment: This will create a drop-down list control where you can choose from a number of columns in the data table.

Response: The Settings part of the dialog will show the settings needed for the Column selection option.
If more than one data table is available in the analysis, select the Data table to work on.

Response: The columns from the selected data table are shown in the Selectable columns list.
If you do not want all columns to be available in your drop-down list, type a search expression that displays only the columns of interest.

Comment: 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, etc. 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 TIBCO Spotfire for more information about valid search expressions.

Response: Only the columns matching the search expression will be visible in the Property Control dialog, and, therefore, only those columns will be available in the resulting drop-down list.
Click OK.

Response: The drop-down list is added to the text area.

Column selection allows you to choose from a list of columns. There are also several other definitions available: Unique values in column allows you to choose from the unique values available in a specified column. Expressions can be any type of custom expression. Fixed values uses a list of predefined values. Numerical range is used to set a range of numbers from min to max, each step increased by a specified interval.

To use a property expression to define a curve:

A property can either be a string expression in itself, or it can be used as a variable in a custom expression. This step instruction assumes that the property contains a string which is an expression.

In the visualization where you want to add the curve, right-click and select Properties.

Response: The Visualization Properties dialog is displayed.
Click Lines & Curves.
Click Add and select Curve Draw.

Comment: Properties can also be used when defining straight lines or in the expressions for curves from data table.

Response: The Curve Draw dialog is displayed.
Call the property containing the expression in the Curve expression field using the Text syntax: For example, ${CurveExpression} .

Comment: The document property curve.expression could in this example hold a value such as "2+3*x". The expression could also contain other properties. For example, "2+DocumentProperty("ExpressionConstant")*x". Note that the syntax for calling a property differs when calling it to retrieve the value of the property. See Properties in Expressions for more information regarding the different syntaxes.
Click OK.

Response: The curve is shown in the visualization.

To add an input field which updates a document property:

Create a text area where you want the input field to reside.
Click on the Toggle Edit Mode button, , in the text area title bar.

Comment: You can also right-click and select Edit Text Area from the pop-up menu.

Response: The text area becomes possible to edit.
Type some descriptive text in the text area regarding what the control will do.

Comment: This can be important to help other users of the analysis file understand what will happen when they change the text in the input field.
Click on the Insert Property Control button, , and select the Input field option.

Response: The Property Control dialog is displayed.
Click to select the property of interest in the Select property list.

Comment: Use the search field if you cannot find your property. You can also specify a new property by clicking New....
Click OK.

Response: The input field is added to the text area.

Comment: You need to exit the edit mode to use the input field.

Comment: This type of input field works well together with a button or a link that performs some type of action. For example, a button that updates a visualization title as described in Using Scripts in the Text Area.