Property Controls & Custom Expressions: Use an Input Field with a Custom Expression

In this post you’ll learn how to use the Input Field property control in TIBCO Spotfire. With just a few simple steps, you’ll be able to utilize input boxes to create dynamic charts that are sure to impress your audience.

[ninja-popup ID=1306] Click Here to download the Spotfire file shown in the screenshots[/ninja-popup]

The Input Field is a Spotfire Property Control that let’s you input a custom value into a box and then use that value somewhere else in Spotfire, such as in a custom expression. This value can be any type of data (number, text string, date, etc.) and can be used like any other property in Spotfire.

In the example below, we’ll use the Input Field in a Custom Expression to limit the data shown in a visualization.

This follows the last blog post: How to Create Rolling Time Periods in Spotfire. In that post, I showed how to use a custom expression to create a lookback period – only data from a specific period of time was displayed (e.g. the last 3 months). This can be really useful, but there are a few drawbacks of hard-coding the time period:

1. It’s cumbersome (takes several clicks) to modify the custom expression, especially if you’re frequently doing it
2. Not everyone knows how or is comfortable modifying a data-limiting expression
3. This expression can’t be modified in the web player (Spotfire Consumer license)

The alternative to hard coding the time frame is to use an Input Field to control the only part of the expression that will change – the Date range, which is often referred to as the lookback or rolling time period. This provides the benefit of flexibility – instead of creating multiple visualizations with different time periods, you only need one visualization linked to a customizable property control as shown in the image above.

Steps to create a new Input Field

1. Insert a new text area. Property controls (Input Field, Drop Down, Slider, etc.) are all inserted and controlled in Text Areas.

2. Click “Edit text area”

3. Click the Insert Property Control icon in the toolbar, and select “Input Field”. This opens the Property Control window. Next we’ll create a new Property Control.

4. Click New in the box that popped up in step 3

5. Type in a name for the New Property. This can be whatever you want, but cannot contain spaces or special characters.
6. Select Integer for the Data Type
7. Write a brief description about the property control (optional)
8. Input a starting value in the box. This can be any number you want, but must be an integer (since we selected Integer for the data type). I typed in the number 2.
9. Click OK to create the new property control, and OK to insert the input field into the text area.

The new input field is now in the text area, with the starting value from Step 8. The input field is not interactive until the text area is saved and closed.

Customizing the Text Area
Now that we’ve inserted the input field, we can type a description in the text area to explain how to use the input field.

This input box is going to be used to control the “lookback period”, so I typed “Show data for the last 2 Months Only”, where the number 2 is represented by the Input Field.

I also increased the font size of the text area to 14

To modify the input field size and font, right click on it and select “Format Control”. I adjusted the width of my box to 40.

Save and close the text area to start using the input field.

Now the input field is interactive, and the text clearly prompts the user how to use the field. However, this property control still doesn’t control anything because we haven’t assigned it to a visualization – that’s covered in the next section.

Use the custom input from your Input Field in a Custom Expression
Now we’ll use the value from the input field in a custom expression. In the last blog post I showed how to write an expression to only show data for the last 3 months (check out that post for an explanation of the expression functions). Now all we need to do is replace the number 3 (which represents 3 months) in that Data Limiting expression with the Property Control created above.

1. Open the visualization properties

2. Click on Data and scroll down to the Limit Data Using Expression section. Click Edit to modify the Expression

3. This expression was used in the last blog post to show data for the last 3 months only.

Delete the Number 3 and in its place insert the new property created above. Scroll through the “Available Properties in the middle section of the custom expression window to find the property created earlier. Click on it, then click “Insert Properties”. The final expression looks like this:

[Date] > Max(DateAdd(‘mm’, -${p.NumberOfMonths}, [Date]))

4. Click OK, then Close. The chart should now update to only show data for the last 2 months (or whatever value is in your input box):

Modify the Expression using the Input Field

Now that the property control is written into the custom expression, you can change the value by typing into the box in the text area. For example, to show data for the last 6 months, type 6 into the input box:

Recap
In this post I showed how to use the Input Field Property Control as part of a Custom Expression to limit the data shown in a visualization. To quickly recap, there are 4 main steps:

1. Insert a Text Area (or edit an existing one)
2. Create a new Input Field Property Control inside the text area
3. Use that Property Control as a variable in a custom expression
4. Type values in the Input Field to change the expression & update a chart

Questions / Comments
If you have any questions or comments, or if there’s something you’d like featured on this blog, feel free to email me at kyle@datafuel.co or leave a comment below.

Don’t forget to download the Spotfire file shown in the screenshots – [ninja-popup ID=1306] Click Here [/ninja-popup]