Overview
A Combo Box displays values in a drop-down list. It is often used to enable the user to select a value to pass to other components on the page.
The following diagram shows a simple combo box added to a grid layout, which takes values directly entered into the configuration options:
| Option Values: | The text that you want the combo box to pass to the event it publishes. This can either be a set of values in text format, or you can populate the values from an event. |
| Option Names: | The text that you want the combo box to display in the drop-down. This can either be a set of values in text format, or you can populate the values from an event. |
| Selected Option: | The name of the event that is published when the user selects a value from this combo box. |
Tutorial
Combo boxes are a simple yet powerful way of providing interactivity on your dashboards. You can pass the selected value to other controls on the dashboard by publishing an event through the Selected Option field.
An event is something that causes a change on the page. For example, you could have a combo box that has several different options. Perhaps you want to have a chart that updates when a different selection is made from the combo box.
In this tutorial, we'll look at adding a slightly more advanced combo box than that shown above. This combo box will get a list of currency values from an event, and will display friendly names in the drop-down list. By default, the combo box will display Australian Dollars. To top it off, we'll show another control consuming the published event when a user selects something from the combo box.
Creating a combo box is simple, but requires a little preparation. Let's go through this process, step-by-step.
Step by Step: Creating an Event Controlled Combo Box
Before you start, open a new tab in Explorer and click the “Create a New Page in Studio Mode” thumbnail. Choose the grid layout - you can adjust the rows and columns if you like but it's not important for this exercise.
Step 1. Add the combo box to the page
Drag and drop the Combo Box component onto a grid cell.
Step 2. Configure the control
In this tutorial, we want to populate the combo box from events. The advantage in doing this is that other controls on the page can also subscribe to the same events, thus your charts and tables (for example) can also be linked. Specify the following events:
- Option Values: currency
- Option Names: currencyNames
- Selected Option: selectedOption
You'll notice that the Selected Option event is already filled in with a default event name. You can choose to change this name if you want, but often there's no real need to.
Step 3. Create the events
This is where you start to see some magic happen. You can create an event at any time.
- Click the Event Defaults button on the far right side of the Studio toolbar.
- Create an event called "Currency" with a List of the following values: AUD, GBP, JPY, SGD, THB.
- Create an event called "currencyNames" with a List of the following values: Australian Dollars, Great British Pounds, Japanese Yen, Singapore Dollars, Thai Baht.
- Create an event called "selectedOption" with a Text value of AUD.
In creating these events, we make them available not only to the combo box we are creating here, but also to any other controls we may want to place on the page.
Step 4. Add a Text Label
Combo boxes don't normally do anything by themselves - you use them to drive other components. Let's add a text label and observe it being driven by the combo box.
- Drag and drop a Text Label onto another cell on the page.
- Select the Title check box.
- Leave Underline unselected.
- Add the following content: Selected Currency: {{selectedOption}}
Step 5. All done!
Congratulations! You now have a fully functioning combo box that displays a list of currencies.
- Click the Preview
button on the Studio toolbar to see what your page will look like in run-time. - When the combo box first loads, the currency is presented as in the combo box as Australian Dollars, while the text label shows AUD.
- Watch the selectedOption value change as you choose different things from the combo box.
Don't forget to save your page!