When building an app, you’ll often want to offer users a dropdown Field from which they can select from a list of predefined options. In addition, sometimes you’ll want the options available in the dropdown list to automatically change based on the current value of an entirely different Field. In these situations, you’ll want to use a Complex Combo Field. These Field types can significantly increase the user-friendliness of your app, as they ensure that users will only see options that are currently relevant.
For instance, let’s say you have multiple managers for each department of your company. Using a Complex Combo Field, you can filter your manager Field’s dropdown options based on the value that a requester previously selected for the department Field. This ensures that the user will only see managers for the selected department.
In this tutorial, we’ll explain how to set up Complex Combo Fields.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In the steps below we’ll limit the values available for a manager Field based on the input for a department Field.
1. Create a Combo Field to Filter By
Start by creating a simple Combo Field whose value will determine the dropdown options available in a separate Complex Combo Field.
It’s important to understand the difference between a Combo Field and a Complex Combo Field. A Combo Field is a dropdown Field which always displays the same options in its dropdown list. On the other hand, a Complex Combo Field is also a dropdown Field, but the options in its dropdown list change, conditionally. In this tutorial, we’ll be creating both types of Fields. Our department Field will be a Combo Field, while our manager Field will be a Complex Combo Field.
In this example, we’ll create a department Field and hardcode three values that will be available in its dropdown list: Sales, Legal, HR. As seen in the screenshot below, each value should be separated with a comma.
To include a comma in your combo item, put a backslash in front of it.
E.g., To have an item that reads "Houston, TX", enter: Houston\, TX
Combo items cannot include a colon (:) or backslash (\).
Need help creating new Fields? See “Step 5: Fields” of our Building Your First App tutorial.
2. Create a Complex Combo Field
Next, we’ll create our Complex Combo Field named manager. For this Field, you’ll also select Combo for the Field’s Type.
You might be confused as to why we are selecting Combo as the Field type here. Shouldn’t we select a Field type of Complex Combo? Interestingly enough, there is no Field type of Complex Combo. You configure a Combo Field to be “complex” by using special syntax when defining the Values that should be available in its dropdown list.
Earlier, when we created our department Field, we simply hardcoded values in. As such, those values will always be visible in this Field’s dropdown list. For our manager Field, however, we want the options in its dropdown list to change based on which department was previously selected.
To achieve this, we’ll use special syntax when defining the manager Field’s dropdown options. To do so, insert three discrete pieces of information (each separated by a colon) for each individual dropdown option.
Here’s an example of what you might use for a single dropdown option (note the colons):
[email protected]:John Hopkins:SalesThis example probably doesn’t make a lot of sense, so let’s break it down:
-
[email protected]: This is the value that Onit will save if the user selects this option from the dropdown. What’s especially interesting here is that the values the user sees in the dropdown don't have to be the values that Onit saves. In many cases, you’ll probably find this to be especially helpful. For example, the Complex Combo Field that we’re building in this tutorial wants the user to select a manager, which the app can later use to add a new participant to the transaction. Since you add participants using email addresses (not display names), we’re configuring our Field to save the email address. But since showing email addresses in the dropdown isn't as user-friendly as showing names (e.g., John Hopkins), we’re displaying names while saving email addresses. We get the best of both worlds!
Note that the first part of a Complex Combo Field’s dropdown option doesn’t have to be an email address -- it can be any value you like.
-
John Hopkins: The second piece of information is the display value for our complex combo. This is the value that a user will see in the dropdown list.
-
Sales: The third piece of information is what this value will be filtered by. In this example, if a user selects Sales for their department Field, this value will be included in the manager Field’s dropdown.
Note that this third piece of information only defines the filter value -- it doesn’t specify the separate Field where this filter value will come from. That Field will be defined below.
Tip: Since we're storing different value types here, note that if you need to extract a value from a Complex Combo Field with Liquid, you'll need to specify which value type we want.
To extract the stored value of a Complex Combo, use:
{{ atom | combo_value: 'combo_field_name'}}To extract the display value of a Complex Combo, use:
{{ atom | combo_display: 'combo_field_name' }}Additionally note that if you need to store a different value than is displayed but don't need to filter search results by a separate Field, it is possible to create a Complex Combo with only the first two pieces of information -- that is, only a stored value and a display value.
Now that you understand what a single dropdown option looks like, let’s look at what a whole group of them might look like:
[email protected]:John Hopkins:Sales, [email protected]:Mary Thompson:Sales,[email protected]:Mike Jones:Legal, [email protected]:Derrick Smith:Legal,[email protected]:Jamie White:HRThis configuration offers the user two managers to choose from if they select Sales (John Hopkins and Mary Thompson), different two users if they select Legal (Mike Jones and Derrick Smith), and yet another, different user if they select HR (Jamie White).
The entire block of text above is what you would insert inside of a Complex Combo Field’s Values property.
Finally, we need to map our Complex Combo Field to a separate Field that will provide the filter value for the dropdown options. We’ll select our department Field from the Filter By dropdown. This essentially tells Onit, “Filter the dropdown options that are available in my manager Field based on the current value that is selected in my department Field.”
Setting a Default Value
For most other Field types, you can set an Initial Value for the Field to automatically default to. Setting a default value for a Complex Combo is a little different, but nearly as simple.
In your Values property, find the value you want your Complex Combo to default to when is associated filtered by value is selected. Append :default to this value.
In the example below, we've made John Hopkins our default value when Sales is selected for the department Field, Mike Jones the default when Legal is selected, and Jamie White the default when HR is selected.
[email protected]:John Hopkins:Sales:default, [email protected]:Mary Thompson:Sales, [email protected]:Mike Jones:Legal:default, [email protected]:Derrick Smith:Legal, [email protected]:Jamie White:HR:defaultNote that this default value will not display until a user first selects a value for the department Field.
Try It Out
Congrats! You’ve just created your first Complex Combo. Take it for a test run! The values available for the manager Field should depend upon the value selected for the department Field.
In the screenshot below, Sales selected for department filters our manager Field's values to John Hopkins and Mary Thompson:
On the other hand, when HR is selected for department, our manager Field values are filtered down to just Jamie White:
Displaying Combo Field Values as Form Buttons
Here’s a quick note about a special type of configuration that you employ when working with Onit Combo fields!
When setting up a Combo Field, you have the option to display each combo value as an individual form button. Below is an example of how this configuration will look to end users. In the example below, each of the four blue buttons are actually combo values that have been hard-coded into the Field’s configuration.
To show combo values as form buttons, check the Display as Form Buttons checkbox when configuring the Field in the App’s wizard.
Once checked, the combo values will show as individual buttons on the launch form, as seen in the screenshot below. To select a value simply click the appropriate button.
Showing combo values as form buttons opens the possibilities to new configuration options. Below are a few examples:
- Show/Hide New Fields: Now that each value in a combo Field is rendered as its own button you can tie UI Actions to each individual value. Utilizing the UI Action you could allow users to show or hide new Fields depending on which combo value they select.
- Building New Tabs: As you know the maximum number of tabs allowed in your App configuration is five. However, by using the combo values as buttons you can build your own pseudo ‘tabs’. Accomplish this by utilizing combo Field values to display ‘Next’ and ‘Previous’ buttons that will show or hide a different set of Fields using a UI Action.