Lookup

Use Lookup fields to dynamically populate field options and values with the data from submitted entries. Lookup fields can be used for several types of dynamic field relationships. You may use them to:

• Retrieve submitted values and use them as options in a dropdown, radio, or checkbox field, or for display only.
• Set up cascading field options. This is perfect for country/state/city or year/make/model fields where the available options are filtered by the value selected in a prior field.
• Filter down to a price or final value. Allow the user to select options from Lookup fields which will ultimately display a final price or value in a text/number field.
• Dynamically populate field values. Allow users to select or enter a value in a Lookup field which will populate fields in the form with values from the same entry.

If you want to learn more about the differences between a Dynamic field and a Lookup field, please click here.

Standard field options

A Lookup field has the following standard options:

• Field type
• Required
• Unique
• Read Only
• Field key
• CSS layout classes
• Label position
• Field size
• Dynamic default value
• Visibility
• Conditional logic

Field-specific options

Display lookup fields

Display the value submitted in a Lookup field in a form's confirmation message, email, or View. Just insert [x], where x is the ID or key of the Lookup field.

Set up a single Lookup field

If you would like to add an individual Lookup field to your form so that you can use submitted values as options, follow the directions below.

1. Create a new form or go into an existing form where you would like to add a Lookup field.
2. Add a Lookup field to your form. By default, a Lookup field will display as a dropdown, but you can change Display as to Single line text, Radio button or Checkbox if you would prefer.
   
3. Set up your Lookup field to Get options from: any form/field on your site.
   
4. In the field options, select the Option order that you would like. You can display options in ascending order (A-Z), descending order (Z-A), or set no order.
   
5. If you would like the user to only see values that they submitted, scroll down to Lookup options and select 'Limit options to those created by the current user'.
   
6. If you are you using a Lookup → Dropdown field, enter a value in the Placeholder text setting if you would like placeholder text to appear on the normally blank option.
   
7. Save the form and click Preview. Now the user can select a value from their submitted entries.
   

Set up cascading fields

There are many situations where setting up cascading Lookup fields is useful. One of the most common is a country/state/city scenario. Another common use for this is a vehicle year/make/model scenario. Regardless of the cascading scenario, the directions below can be adapted to apply to your use case.

1. Create a new form. We'll call this the 'Data form' because it will be used to hold all of the year/make/model data, i.e., all of the data that will be retrieved and filtered in the Lookup fields. Add a text field for the Year, a text field for the Make, and a text field for the Model.
2. Import a CSV with all of the year/make/model data into the Data form. If you import a CSV, the CSV headings should match up with the fields in your Data form. If you don't have a CSV to import, you can manually create entries in the Data form.
3. Create a second form. We'll call this the 'End User form' because it will be the form that the end user interacts with.
4. Add a Lookup field for the vehicle year. Set it up to Get options from: Data form → Year field.
   
5. Add a Lookup field for the vehicle make. Set it up to Get options from: Data form → Make field.
   
   Since we want the Make options to change depending on the selected year, set this field up to Watch the 'Year' Lookup field.
   
6. Add a Lookup field for the vehicle model. Set it up to Get options from: Data form → Model field.
   
   Since we want the Model options to change depending on the selected year and make, set this field up to Watch 'Year' Lookup field and the 'Make' Lookup field.
   
7. Save the End User form and click Preview. When you select a Year, the Make options should change. When you select a Make, the Model options will update.
   

Drill down to a final value

There are many instances where it is useful for a user to select options in one or more fields which then spits out a final value that is retrieved by using the options selected in other fields. Lookup fields can be used for this. To help make the instructions below more clear, we will assume the end goal is to create a form where a user selects a State and their age range which then displays a policy price in a Single Line Text field.

1. Create a new form. We'll call this the 'Data form' because it will be used to hold the insurance policy data. Add a field for the State, Age, and add a Single Line Text field for the Price.
2. Import a CSV with all of the insurance policy data into the Data form. If you import a CSV, the CSV headings should match up with the fields in your Data form. If you don't have a CSV to import, you can manually create entries in the Data form.
3. Create a second form. We'll call this the 'End user form' because it will be the form that the end user interacts with.
4. Add a Lookup field for the State. Set it up to Get options from: Data form → State field.
   
5. Add a Lookup field for the Age. Set it up to Get options from: Data form → Age field.
   
   Since we want the Age options to change depending on the selected State, set this field up to Watch the State Lookup field.
   
6. Add a Single Line Text field type for the price. Select Default Value and click the search icon to get the Lookup default value settings.
   
   Set Search in to Data form → Price field.
   
   Since we want the price to change depending on the selected State and Age, set this field up to Watch the State and Age Lookup field.
   
   Typically you should mark this field as 'Read-only' so users cannot change the value. If you would like to make the value appear as floating text rather than a field input, put the frm_total class in the field's CSS Layout Class box.
7. Save the End User form and click Preview. When you select a State and Age, a price should be displayed in the Single Line Text field.
   

Populate fields with values from a selected entry

If you would like to automatically populate fields based on a selected entry, follow the directions below.

1. Go into edit the form that you want to autofill.
2. Add a Lookup field. Set it up to Get options from: a form/field. It's acceptable to set it up to get options from the current form.
   
3. Open the field options for a field that you want to autofill. Select Default Value and click the search icon to get the Lookup default value settings.
   
   Set Search in to the same form that the Lookup field is getting its options from.
   
   In the Watch Lookup Fields option, add the Lookup field from Step 2.
   
4. Repeat the previous step for each field that you want to autofill.
5. Save the form and click Preview. When you select an entry in the Lookup field, the fields that are 'watching' it should automatically populate.
   

Compatible field types

The following field types can be populated automatically by watching a Lookup field:

• Single Line Text
• Email Address
• Website/URL
• Image URL
• Time
• User ID
• Number
• Phone Number
• Date
• Dropdown
• Hidden

This option will be added to additional field types in future releases.

Populate fields by searching entered values

There may be situations where you would like a user to enter a first and last name, for example, and then other form fields automatically populate. Or you may want users to enter an ID number and fields automatically populate with data for that ID number. If you would like to automatically populate fields based on the values entered in one or more fields, follow the directions below.

1. Go into edit the form that you want to autofill.
2. Add a Lookup → Single Line Text field.
   
   Set it up to Search in: the form/field that you would like to search for a first name.
   
3. Add a second Lookup → Single Line Text field. Set it up to Search in: the same form as step 2, but a different field. This will be the field for the user to enter a last name.
   
   Skip this step if a second lookup field is not needed.
4. Add other non-Lookup fields to your form. Open the field options for a field that you want to autofill. Select Default Value and click the search icon to get the Lookup default value settings. Set Search in to the same form that the Lookup fields are searching values from.
   
   In the Watch Lookup Fields option, add the Lookup field from Step 2 and the Lookup field from Step 3.
   
5. Repeat the previous step for each field that you want to autofill.
6. Save the form and click Preview. When you type in a first and last name in the Lookup fields, the other fields that are 'watching' it should automatically populate if a match is found for the entered first and last name.
   

Add custom coupon codes

If you have a form that calculates a total amount due and you would like to allow users to enter a coupon code which automatically deducts the correct discount amount from the total, you can use Lookup fields to accomplish this.

1. Create a form to hold your coupon codes and discount amounts. We'll call this the 'Coupon Code Entry' form.
2. Add a Single Line Text field and label it 'Coupon Code'.
3. Add a Number field and label it 'Discount Amount'.
4. Submit an entry for each coupon code and discount amount that you would like. For example, you could create 10% discount for Black Friday by entering "BlackFriday2016" in the Coupon Code field and .10 in the Discount Amount field.
5. Go into an existing form, or create a new form, where users will enter the coupon codes and purchase an item.
6. Add a Lookup → Single Line Text field. Label the field 'Coupon code'. Set it up to search values from the 'Coupon Code Entry' form → 'Coupon Code' field.
7. Hit Update.
8. Add a Number field to the form. Title it 'Discount Amount'. In this field's options, select Default Value and click the search icon to get the Lookup default value settings. Set it up to get values from the 'Coupon Code Entry' form → 'Discount Amount' field. Set it up to watch the Coupon Code Lookup field.
9. Go into the field that calculates the total amount due. Include something like this:
   [x]-([x]*[y])
   Replace x with the ID of the field that determines the amount due and replace y with the ID of the Discount Amount field. If x is not a field, but is a hard-coded value, just replace [x] with 100, for example.
10. You're finished! Now when a user enters a coupon code, it will automatically discount the total if the coupon code is valid. If it is not a valid coupon code, the total will not be altered.

Copy value to a Lookup field

If you would like to copy a value from a non-Lookup field to a Lookup field, you may use the code below. This is especially useful in cases where the first field cannot be a Lookup (e.g. a field whose value is the result of a Field Calculation instead of a simple selection). You may add this code to your form's Settings > Customize HTML in the Before Fields section.
If you would like to copy a value from a non-Lookup field to a Lookup field, you may use the code below. This is especially useful in cases where the first field cannot be a Lookup (e.g. a field whose value is the result of a Field Calculation instead of a simple selection). You may add this code to your form's Settings > Customize HTML in the Before Fields section.

<script>    
jQuery(document).ready(function($){
    $('#field_nkqtr').change(function(){ 
        var sourceField = $('#field_nkqtr').val();
        $('#field_br4j1').val(sourceField);
        $('#field_br4j1').trigger({ type:'change', originalEvent:'custom' });
    });
});
</script>

Replace 'nkqtr' with the field key of your source field, and 'br4j1' with the field key of the destination Lookup.

Related developer hooks

• Change the comparison operator for Lookup fields with the frm_set_comparison_type_for_lookup hook.