Bringing it all together – interactively configuring the KPI chart

So, how do we bring together the concepts of text areas, document properties, property controls, and custom expressions?

Easy! We are going to use them to provide a configurable KPI chart that allows us to change what is shown on it.

Follow along with this example, as we add a text area, a property control, and wire everything up together:

1. Add a text area to the current page by selecting it from the new visualization pullout:

1. Move the text area above the KPI chart and resize it to a reasonable size by clicking and dragging the divider between it and the KPI chart.
2. Click the pen icon on the top right-hand corner of the text area to edit it. Note that the icons are not visible until you hover over the top right corner of the text area:

1. A new dialog will pop up. Add a drop-down list control to the text area by clicking the Insert Property Control button and choosing Drop-down list:

1. A further dialog will pop up that will allow us to configure the property control. First of all, we need a new Document Property that can be configured by the property control. This Document Property will then control the KPI chart. Click the New... button.

1. A dialog will open. The Document Property must be named. As we already stated, it's important to give meaningful names to Document Properties, so call it KPIChartValueAxis. All the other settings can be left as per the default:

1. Click OK to close the dialog box for the new Document Property.
2. Choose to set the property values by Expressions:

1. Click on the first Display Name field in the table and enter Avg Open. Then, use the carriage return/Enter key on the keyboard to move to/add the next row. Fill in all the values as per the following screenshot:

1. If you click the Add... button instead of using the carriage return key on the keyboard, Spotfire's expression editor will be shown. You can enter the Display name in the box at the bottom of the editor. I haven't asked you to fill in any expressions just yet as it's general good practice to enter the display names ahead of the expressions because it gets you thinking about what you want to show without worrying about how to show it:

1. Now, select the first row in the table and click the Edit... button:

1. You'll notice that available columns, properties, functions, and so on are all shown in the dialog. For now, we will be using the columns and functions part of the expression editor.
   The expression we want to end up with is as follows:
   Avg([Open])

1. On the Functions Category dropdown, choose Statistical functions:

1. Select the Avg function and click Insert Function (or double-click on the Avg function).
2. Now, move to the Available Columns part of the dialog, click the open column, and click Insert Columns.
3. You should now find that the Expression reads as follows:

1. Click OK on the dialog to close it.
2. Now, follow the same steps for each of the other expressions in the drop-down control. They should be as follows (Display Name : Expression):
   • Avg Open: Avg([open])
   • Sum Open: Sum([open])
   • Avg Close: Avg([close])
   • Sum Close: Sum([close])
   • Avg Growth: Avg([close] - [pen])
   • Sum Growth: Sum([close] - [open])

1. Note that in order to enter the minus symbol, you will have to edit the expression directly inline. Spotfire has auto-complete with column names and functions, and so on.
2. You should end up with a list of expressions that looks like this:

1. Click OK on the dialog.
2. Finally, we should add a hint to the user. Place the cursor in front of the drop-down control and enter KPI Chart Value:

Feel free to adjust the text size, font, color, and so on.

1. Close the Text Area editor. Click Yes on the dialog that asks if you want to save changes.

Now that the property control has been configured, it's necessary to set up the KPI chart so that it uses the expressions from the control. We can do that by following these steps:

1. Right-click the KPI and choose KPI Settings....
2. Right-click the Value (y-axis) selector and choose Custom Expression...:

1. Highlight and delete the current expression.
2. Now, we get to use the Available properties for column part of the custom expression editor dialog. Scroll through the list of properties and select KPIChartValueAxis, and then click Insert Properties:

Recall that KPIChartValueAxis is the name of the document property that was created at the time the drop-down property control was created and designed.

1. Take a look at the Resulting expression part of the dialog. This shows the decoded value of the current value of the expression. The expression that's now used for the value axis of the KPI chart is ${KPIChartValueAxis}.

1. Click OK on the Custom Expression editor dialog.
2. Now, try choosing different values on the drop-down control. You should see the KPI chart updates to show whatever is chosen. In the background, Spotfire is substituting the custom expressions that we have designed in the control into the KPI chart value axis.
3. Finally, it's good practice to hide the title bars of text areas (and other visualizations) if they serve no purpose. Hiding the title bars makes the dashboard or analysis much cleaner. To hide a title bar, open the Text Area Properties and uncheck Show title bar:
   

To recap—this example has shown how to provide the ability to change the configuration of a Spotfire visualization on the fly. This enables a nontechnical user or consumer of a Spotfire analysis to customize how they view the analysis without needing a Spotfire Analyst client. In addition, by providing property-control-based configuration of an analysis, you are guiding the end user of the analysis to get the best value out of it.