A Data Lookup is a drop-down field within a form that references an external data source (called a Lookup table), allowing the mobile user to select and load data into the form quickly. Click here to learn about Lookup tables.
For instance, in the animated image below, the user selects three items from data lookups. After each selection, the item description and cost automatically populate the form by referencing the external data source and filling in the form automatically.
By using lookup conditions, you can instruct the form to filter data so that drilling down to the correct record is easy for the user. In the animated image below, the user first selects the Cold Storage equipment type, which filters down the potential refrigerants to four types. The user then selects the Unitary AC equipment type, which filters down the potential refrigerants to only two types.
Caption text: The caption is used in most cases to ask the question. In others it may be a column heading. This is a required field. Please keep in mind that captions will wrap when form elements do not fit within the width of the screen. It is important to consider how your captions will be displayed. Captions on a larger screen might look perfect, but on a smaller device, they may be forced to wrap several times. In this situation, a smaller caption should be used.
Hint: Provides additional information to the mobile form user on how a question (i.e., Caption text) should be answered. The Hint font size is smaller than the Caption font size.
Additional HTML styling can be applied on hints and captions.
Data name: Because this is a required field, doForms will default the Data name to match the Caption or Label. If these are blank, doForms will generate a generic Data name name with a sequential number (such as "untitled10"). Since it is used throughout the system, it is recommended that you enter a descriptive Data name that is easily identifiable. Nondescript Data names are difficult to find and select at a later time (e.g., when performing a calculation).
Default value: This is what the Data Lookup field will initially display when a user opens the form. The user will be able to erase this value. Leave blank to have no value initially appear.
Data source: Select an existing external data source (using the Lookup data tab or the Manage lookup data option ). Click here to learn about Creating and managing lookup data sources.
Lookup field: This is the column name in your data source that will be presented to the user as a drop-down list in the mobile form.
Lookup conditions: Allows the user to filter the data source and show a secondary data set, based on what the user chooses from a primary data set.
For example, you want the mobile form user to choose the city that they live closest to. Your data source is an Excel spreadsheet that contains the 300 largest cities in the United States, split into two columns: STATE and CITY. The following image shows the beginning of the spreadsheet:
You want the mobile form to present two drop-down lists, as follows:
- The user selects a state from the first drop-down list.
- The user selects a city from the second drop-down list. However, this second list has been automatically filtered so it only displays cities located in the state that the user selected from the first drop-down list.
The following animated image shows the user selecting Alabama (primary data selected from first drop-down list), and then selecting Mobile (secondary data selected based on primary data selection).
This is accomplished by including in your form two data lookup fields (State and City) that refer to the STATE and CITY columns located within an existing Excel spreadsheet. However, the City data lookup field contains a Lookup condition that forces it to only show data based on what the user chose in the State data lookup field.
The following two images show the settings for the two data lookup tools that have been added to the mobile form. The first image shows the settings for the State data lookup tool (highlighted in green, below). Note that the Data source is an existing Excel spreadsheet called Largest 300 cities in US. The Lookup field is STATE, which refers to the STATE column in that spreadsheet.
The next image shows the settings for the City data lookup tool (highlighted in green, below). Note that it uses the same Data source as the first data lookup (Largest 300 cities in US). The Lookup field is CITY, which refers to the CITY column in the spreadsheet. This data lookup tool contains a Lookup condition (highlighted in red, below). The Lookup condition field is STATE, which refers to where (in the spreadsheet) doForms will look for secondary data (i.e., the City names). The Condition answer is State_chosen_by_user, which refers to the field within the mobile form that satisfies the primary data.
Evaluate blank (null) condition values: This option can be used to control how lookup conditions work in the special case when the lookup is being used as a data source for a checklist in a table container. CHECK this option if you DO NOT want to include blank (null) values in the checklist. UNCHECK this option if you DO want to include blank (null) values in the checklist.
Destination Fields: Destination Fields allow you to easily populate fields in your form from fields (called table fields) in your data source. The image below shows a source spreadsheet with ADDRESS, CITY, ST, and ZIP table fields:
Suppose your mobile form included a data lookup field with the ADDRESS column as the Lookup field. Once the form user chose an address, you want the form to populate with the City, State, and Zip for that chosen address. You would use Destination Fields to do this. Simply add a text field to your form and name it City. Then add two more text fields, named State and Zip Code. Then go back and create three Destination Fields and map them to the newly created text fields. Your City text field would map to the CITY table field. The State text field would map to the ST table field. And the Zip Code text field would map to the ZIP table field.
Advanced Options: The following special properties control the look and behavior of data lookups:
- Limit to list: Determines if the user is restricted to only selecting an answer from the list provided, or if the user can enter their own answer by typing it in the field.
- Sort lookup list alpha-numerically: Sorts your drop-down list numerically (by digit) and then alphabetically. Because numbers are sorted by digit, note that numbers 1 through 10 would sort in the following manner: 1,10,2,3,4,5,6,7,8,9. To have them sort truly numerically, you would need to number them as follows: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10.
Type: Specifies if the lookup value is String (e.g., alpha, numeric, and special characters accepted) or Number (e.g., only numeric characters accepted).
Length: Sets the Minimum and Maximum values that the mobile user may enter into the field.
Dropdown text: How the lookup data appears for selection.
- Wrap text: Determines if each answer choice in the drop-down will wrap onto multiple lines, or they will each be constrained to a single line (showing only as much text as will fit).
- Text size: Determine the size of the answer choice text in the drop-down.
Keyboard icon: Displays a keyboard icon within the lookup field in the form, which, when clicked, opens a on-screen keyboard.
Open keyboard on click: Opens an on-screen keyboard when the user clicks the field in the form (if the Type of the lookup value is set the String, then an alphanumeric keyboard will appear; if it is set to Number, then a numeric keyboard will appear). If you have a large data source and you would like your user to start typing to filter the results, then displaying a keyboard makes sense. If you are giving them a simple drop-down list to scroll through, then there is no reason to show the keyboard. The reason we differentiate between portrait and landscape is because on small devices in landscape there might not be enough room to show both the keyboard and the dropdown list.
Restrict Data On: These parameters allow users to either enable or disable the loading of datasets within a data lookup field in a form. These settings help:
- Decrease load times (for web portal users) of forms with data lookups containing large datasets. By restricting access to web app users, you stop the web app from trying to populate drop-downs, which could become time-consuming (and can dramatically decrease the initial load time of the form) depending on the size of the file.
- Limit access to datasets within mobile forms. By restricting access to mobile users, you stop the system from sending the dataset to mobile devices. This feature was designed to allow a dispatcher to select a customer (from a drop-down) for a work order without the system automatically distributing the company's customer master file out to mobile devices.
Select one or more of the following Restrict Data On settings:
- View Data Edit: Restricts the loading of the data lookup dataset when a web portal user edits a submitted form through the View data tab.
- View Data New: Restricts the loading of the data lookup dataset when a web portal user creates a new form through the View data tab.
- Dispatch Edit: Restricts the loading of the data lookup dataset when a web portal user edits a submitted form through the Dispatch tab.
- Dispatch New: Restricts the loading of the data lookup dataset when a web portal user creates a new dispatch through the Dispatch tab.
- Mobile: Restricts the loading of the data lookup dataset when a mobile user accesses the form.
- Web app: Restricts the loading of the data lookup dataset when a web client user accesses the form.
Barcode button: This allows you to set the lookup field to a barcode that the user scans with their smartphone or tablet. Therefore, instead of having the user select from a drop-down list, they scan a barcode (which compares itself to the data source, and then sets the destination fields to the matched record in the data source).
NFC button: This allows you to set the lookup field to an NFC tag that the user reads with their smartphone or tablet (Android only). Therefore, instead of having the user select from a drop-down list, they read an NFC tag (which compares itself to the data source, and then sets the destination fields to the matched record in the data source).
Choose-one destination fields: Choose-one questions have two ways of describing each answer option: "Answer as displayed to the user" and "Underlying_value." If a destination field for a lookup is a choose-one question type, then you will need to specify which of these to use to determine which answer option to select.
For example, suppose your form has a destination field that is a choose-one question with the following answer options:
There are two answer options, YES/1 and NO/0, which correspond to the radio buttons in the choose-one question.
If your lookup table contained YES/NO answers, you would uncheck this option so the YES or NO values are used to determine which answer option to select. So if the lookup value is YES, then the YES/1 answer option is selected in the choose-one destination question. Conversely, if the lookup value is NO, then the NO/0 answer option is selected in the choose-one destination question.
But suppose your lookup table contained 1/0 answers. In this case, you would check this option so that the 1/0 values are used to determine which answer option to select. So if the lookup value is 1, then the YES/1 answer option is selected in the choose-one destination question. Conversely, if the lookup value is 0, then the NO/0 answer option is selected is the choose-one destination question.
Use as input for conditional lookups only: Check this option to improve speed if this tool is only being used to support conditional lookups later in your form. Uncheck if you want full lookup functionality.
Wild-card search (Android & iOS Only): Allows the user to use a partial value to search the contents of the lookup list for matching items.
Appearance: doForms allows you to set a default set of appearance parameters. This eliminates the need for you to have to set colors and other parameters each time you add an element to your form. You can however override the default settings for any tool by simply picking the Custom option. You can also edit the default by clicking on the edit defaults option.
See Styling your form for more details.
Justification: Allows you to apply text justification settings to certain elements of the tool. Choose the appropriate radio button for the Caption, Hint, and/or Answer fields as follows:
- L: Left-justifies the text.
- C: Center-justifies the text.
- R: Right-justifies the text.
Remove Space: When selected the space Above or Below the tool is Removed. When styling the form this help provide continuity with the layout.
Read only: These settings allow you to control which users can enter data into or edit this field. The settings are as follows:
- View data edit: Restricts a web portal user from editing this field when editing a submitted form through the 'View data' tab.
- View data new: Restricts a web portal user from entering data into this field when creating a new form through the 'View data' tab.
- Dispatch edit: Restricts a web portal user from editing this field when editing a submitted form through the 'Dispatch' tab.
- Dispatch new: Restricts a web portal user from entering data into this field when creating a new dispatch through the 'Dispatch' tab.
- Mobile: Restricts a mobile user from entering data into this field when creating a form.
- Web App: Restricts a web app user from entering data into this field when creating a form.
- Form Links: Restricts a web portal user from editing this field when editing a form that was sent using a form link
Required: These settings allow you to control which users are required to enter data into this field. The settings are as follows:
- View data edit: Requires a web portal user to enter data into this field if editing and saving a submitted form through the 'View data' tab
- View data new: Requires a web portal user to enter data into this field when creating a new form through the 'View data' tab.
- Dispatch edit: Requires a web portal user to enter data into this field if editing and saving a submitted form through the 'Dispatch' tab.
- Dispatch new: Requires a web portal user to enter data into this field when creating a new dispatch through the 'Dispatch' tab.
- Mobile: Requires a mobile user to enter data into this field when creating a form.
- Web App: Requires a web app user to enter data into this field when creating a form.
- Form Links: Restricts a user from submitting a form link without answering this this field.
Only display this question if
This is a very powerful option as it allows you to hide form elements, only exposing them if the answer to a question in your form meets the criteria you have set. Being able to hide fields unless they are needed makes form more user friendly. For example, if you have a Choose One question with the answers Yes and No, then you can say "Only display this form element if" the answer to the Choose One is "equal" to "Yes." You can combine criteria with other criteria, thus creating complex criteria for showing/hiding form elements.
This option allows you to navigate the user to a specific location in the form based on how they answer the current question.