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 currently relevant options.
For instance, you have multiple managers for each company's department. Using a Complex Combo Field, you can filter the dropdown options for your manager Field based on the value 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.
Understanding the difference between a Combo Field and a Complex Combo Field is essential. A Combo Field is a dropdown Field that always displays the same options in its list. On the other hand, a Complex Combo Field is also a dropdown Field, but the options in its list change conditionally. In this tutorial, we’ll create 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, and HR. The screenshot below shows that each value should be separated by a comma.
To include a comma in your combo item, put a backslash in front of it.
For example: 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 about why we select Combo as the Field type here. Shouldn’t we choose 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.
When we created our department Field earlier, we simply hardcoded values. As such, those values will always be visible in its dropdown list. For our manager Field, however, we want the options in its dropdown list to change based on which department was previously selected.
We’ll use special syntax when defining the manager Field’s dropdown options to achieve this. To do so, insert three discrete pieces of information (each separated by a colon) for each 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 those that Onit saves. In many cases, you’ll probably find this to be especially helpful. For example, the Complex Combo Field we’re building in this tutorial wants the user to select a manager, which the app can use later 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, which the user will see in the dropdown list.
-
Sales: The third piece of information is how this value will be filtered. 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 from which this filter value will come. That Field will be described below.
Tip: Since we're storing different value types here, please remember 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), two different users if they choose 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 a Complex Combo Field’s Values property.
Finally, we need to map our Complex Combo Field to a separate Field to provide the filter value for the dropdown options. We’ll select our department Field from the Filter By dropdown, which tells Onit to “Filter the dropdown options available in my manager Field based on the current value 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 configuration you employ when working with Onit Combo fields!
When setting up a Combo Field, you can display each combo value by using an individual form button. Below is an example of how this configuration will look to end users. In the example, each of the four blue buttons represents a combo value that has 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 possibility of creating new configuration options. Below are a few examples:
- Show/Hide New Fields: Now that each value in a combo Field is rendered as its button, you can tie UI Actions to each 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, you can build your own pseudo "tabs" by using the combo values as buttons. 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.