The Autosuggest element is a Dynamic Question type that allows you to upload a set of answers that will automatically be suggested to participants as they type a response into an open-ended text box.
Autosuggest questions may contain one or more text boxes and suggested answers are controlled using a set of preconfigured filters.
1: Creating the Answer File
Before you can add an Autosuggest element to a survey, you must first create the file containing the answers you would like to be suggested to participants.
The answer file must contain a list of all the answers you would like to suggest, along with a unique identifier for each of those answers. Answer files can be created using a simple text editor and can be uploaded directly from the element, or via the file manager or the Upload/Replace Files API endpoint.
Learn more about creating an Autosuggest answer list.
2: Adding the Element
Once you have uploaded your answer list, you can add the Autosuggest element using the Survey Editor or by editing the survey XML.
2.1: Via the Survey Editor
To add an Autosuggest element using the Survey Editor, first click the "+ Element" button to add a new survey element. Then click "Open End" under Question Types and select the "Autosuggest" element. Then click "Add".
In the staging area, enter the question text and instructions as you would like them to appear in the survey. In the Answer Source File menu, use the tab options to upload a new file or select an existing file from the system files manager.
Once you have selected a file, click “Continue” to upload the file to the element.
If your upload is successful, you will see a confirmation screen. Click “Close” to continue. If the upload is not successful, you may need to adjust your file contents or layout before trying again.
2.1.1: Uploading Your Answer File
Next, click “Add source file” to select the answer file to use in the element.
There are three option boxes you can choose from:
- Include “No Match” virtual question
- Previous version: If a participant entered an answer that had no match in the source file, then “No Match” would be recorded in the participant data.
- Updated version: In addition to the pre-existing functionality, this is the new option shown in the “Source File Settings” modal.
Note: Check this box (or add the attribute autosuggest:noMatchVirtual="1" via XML Editor) to add a virtual question visible in reporting apps like Crosstabs.
-
- This virtual question will track “No match” submitted answers the same way the Autosuggest question tracks matching answers, with a count and (in Crosstabs) a link that can open a modal to display the non-matching answers.
-
- Survey Editor’s stage area for the Autosuggest element will show an indicator when this setting is enabled in the “Source File Settings” section.
- Append all file data
- A new option is now shown in the “Source File Settings” modal, titled Append all file data.
Note: Check this box (or adding autosuggest:appendFileData="1" via XML Editor) to add virtual questions to the report: each additional column in the source data file (every column other than the user-selected Answer ID and Answer Value columns), will have its own virtual question.
-
- The virtual questions will be visible in reporting apps like Crosstabs.
- Exclude selections between rows
- A new option is now shown in the “Source File Settings” modal, titled Exclude selections between rows.
Note: For Autosuggest questions that have more than one row, check this box (or adding autosuggest:excludeRowSelections="1" via XML Editor) to prevent answers typed into one row from appearing in the dropdown menus for other rows.
- This will be enabled by default.
- Additional validation will be in place to prevent duplicate responses within a multi-row Autosuggest question.
- Survey Editor’s stage area for the Autosuggest element will show an indicator when the setting is enabled in the “Source File Settings” section.
Note: All three of the new toggle settings will also be shown in the “Update Styling” modal.
2.1.2: Including Answers Selected In
Include Answers Selected In:
- A new option is shown in the “Source File Settings” modal, titled Include Answers Selected In. Autosuggest questions selected in the dropdown menu will exclusively determine which answers are “autosuggested” to participants. For
Example: If the participant submits the answer Benadryl in q1 Autosuggest, and Allegra in q2… then q3 has Include Answers Selected in enabled for q1 and q2, only Benadryl and Allegra will be autosuggested to participants in q3.
-
- In this case, if q3's source file contains Benadryl and Allegra (as q1 and q2's source files do), then the participant’s answer will be recorded as a match, per autosuggested usual functionality.
- Questions selected in this dropdown will also appear on the Survey Editor stage.
- This option is also accessible via XML Editor, by adding the attribute
autosuggest:includeFrom=("")to the Autosuggest element. Specify the desired question’s labels as comma-separated values to include the answers from those questions.
Example: Including answers from q1 and q2, add autosuggest:includeFrom=("q1,q2")
Note: This is the exact opposite of Exclude Answers Selected In, where questions selected for one will be unavailable in the other.
Meta functionality
- Accessible via XML Editor and <exec> elements, this provides access to various file data that correspond to selected autosuggest answers. Some advanced survey programming knowledge is required to make use of meta functionality for autosuggest.
2.1.3: Configuring File Settings
Next, you must map the required columns in the file to the fields in the element and configure the settings for any additional filters you have added. Click “Edit settings” to customize your answer file and map its answer columns.
The two collapsible sections in the Source File Settings are: Column Mapping and Optional Filters. The Column Mapping section contains the primary settings and some optional filters.
The following options are available:
Primary Settings
Primary settings are filters that are required in order for the element to function correctly.
- Column containing answers: Select which column in the file contains the answers to be displayed to participants in the survey. This is a required field.
- Column containing unique ID: Select which column in the file contains the unique ID values for the displayed answers (e.g., WID, PID, etc.). This is a required field.
Optional Filters
Optional filters are not required for the element to function correctly and can be added in any configuration. When added, optional filters will affect all participants.
- Language code: Select which column contains the country or language code for the displayed answers. This is an optional field that can be used to customize the survey experience by participant language.
- Exclude answers selected in: If you have more than one Autosuggest question in the same survey, you can specify another Autosuggest question to be used as a filter. If specified, all answers submitted by the participant from that question will be excluded.
- The specified question must be completed before the current question and be separated from it by at least one page break.
- If multiple rows exist, all rows will be considered for both questions. For example, if Q2 is filtered by Q1, then all the answers submitted in Q1 will be excluded from the suggested answers for rows in Q2.
- The only questions available for selection will be Autosuggest questions located on previous pages in the survey. This means that there must be at least one page break (<suspend/>) between e.g., q1 Autosuggest and q2 Autosuggest, in order for q1 to appear as an option in the Include / Exclude Answers Selected In dropdown menus for q2.
Note: While this filter will hide the rows from the previous element, it will not prevent them from being submitted in the current element.
Note: The Autosuggest element respects response options flagged with the noanswer attribute.
- Column containing filter(s): Select which column in the file contains tags repeated in multiple answer values.
- Filter value(s): Enter values for the tags you would like to use to filter answers. To enter a tag value, type the value into the field and hit the “Enter” key. Values from the file will automatically be suggested as you type. You can remove any tag value by clicking the “x” next to that value in the list.
- If desired, you can use an asterisk (*) when adding filters to allow for partial matches (e.g., adding “*group” will match “red-group”, “no group”, and “group”). Multiple asterisks are supported for a single filter (e.g., “*ab*” will match “table”, “grab”, and “able”; “*a*e*” will match “orange”).
- Multiple pipe-separated values are also supported in the answer file (e.g., “group3|group 3|category_3” will match “category_3”, “group*”, or “*3” filter values).
Note: Up to four custom filters can be added. If no custom filters are specified, all values from the answer file will be available.
Warning: Misspelling tags could result in a null value. You will want to be sure to verify that the values you have entered here are spelled correctly prior to running your survey.
If needed, click “Add additional filter” to specify additional filters and values.
2.1.4: Editing File Settings
Once you have configured your answer file, a summary of its settings appears within the element. Click “Edit settings” to make changes.
You can also choose to replace the current answer file by clicking “Select new source”.
Note: If you replace an answer file, you will need to reconfigure your file settings before continuing.
2.2: Via the XML
The Autosuggest style sits on top of a <text> question. To add an Autosuggest question via the survey XML, first create the base <text> question in the desired location.
Then copy and paste the following code block as the body of that question:
<text
label="q2"
uses="autosuggest.2"
autosuggest:filename="myAnswerSourceFile.txt"
autosuggest:uniqueKey="uniqueKey"
autosuggest:answerKey="answerKey">
<title>New Autosuggest Question</title>
<col label="c1">Key</col>
<col label="c2">Answer</col>
</text>
2.2.1: Required Attributes
The following attributes must be applied in order for the Autosuggest style to work:
uses="autosuggest.2": The question style being applied to the base element (the value after the period indicates the style’s version number).autosuggest:filename: Specifies which file to use as an answer source (uploaded in step 1 above).
Note: Version autosuggest.2 supports the attributes autosuggest:characterLimit and autosuggest:characterLimitText.
When a participant submits a response that matches a value from your answer file, the survey data will be updated with both the participant’s input and a unique key linking that input to the matching value in your answer file.
autosuggest:uniqueKey: Specifies which of the answer file’s columns contains your unique answer keys.autosuggest:answerKey: Specifies which column to use for suggesting answers as the participant types.
Note: The column headers in your answer file will not be shown to participants and can be titled anything you choose. The text you specify, however, will appear in certain reports, such as Crosstabs.
2.2.2: Optional Attributes
The attributes listed below are optional and can be used to filter how answers are displayed to participants. Only the responses you specify are suggested to participants as they type.
|
|
For multi-language surveys, specifies which column contains the survey languages for filtering answers (should be added as |
|
|
Specifies a survey variable to use as a filter. |
|
|
Specifies the column containing the filter values. |
|
|
Specifies which values to filter by, using the column specified in |
|
|
Applies a second filter. |
|
|
Specifies which values to filter by, using the column specified in |
|
|
Applies a third filter |
|
|
Specifies which values to filter by, using the column specified in |
|
|
Applies a fourth filter |
|
|
Specifies which values to filter by, using the column specified in |
|
|
Applies the "One Row at a Time" question style. |
|
|
Specifies how many characters survey participants must enter in order to see autosuggestions in the dropdown list. For example, The default Note: |
|
|
Tells participants how many characters they must enter to see the autosuggestion dropdown list. For example, The default text displayed is “Enter at least 3 characters”. Note: |
|
|
Adds to the report a virtual question for every additional column in the source file beyond the unique key and the answer key.
Note: |
|
|
Enabled by default. Prevents duplicate answers within a single Autosuggest question.
Note: |
|
|
Takes a comma-separated list of question labels, and uses the answers submitted in those previous Autosuggest questions as the autosuggestion answers in the question to which it is applied.
Note: |
|
|
Includes in the report a virtual question that records non-matching answers for that Autosuggest question.
Note: |
Note: Up to four custom filters can be added. If no custom filters are specified, all values from the answer file will be available.
Note: If a typo exists in the values you have specified for filter1Values, it will not affect the question’s behavior. You will want to be sure to verify that the values you have entered here are spelled correctly prior to running your survey.
3: Testing Your Setup
Once you have finished setting up your Autosuggest question, you can verify your configuration by testing through the survey as a participant.
Learn More: Testing an Online Survey
4: Additional Considerations and Limitations
The following considerations and limitations apply when working with Autosuggest questions.
4.1: Filtering Rules
When added, custom filters will affect all participants. Additionally, the following rules apply:
- Only those answers which have the values specified for a filter will be shown if that filter is applied.
- Filters should only be applied to non-answer columns. Applying filters to the answer column can result in errors for participants.
- If a typo exists in the values you have specified for a filter, it will not affect the question’s behavior and you will not receive any warning messages.
- When two filters are applied, they are joined by “and” logic; in other words, answers must meet the criteria from both filters to appear in the survey.
- Multiple values for a single filter are joined by “or” logic; in other words, specifying “red,blue” will show all answers which include "red” or “blue” in that column.
- To include answers which have no value in a specific column, a comma must be added to the beginning or end of the value list (e.g.,
filter1="red,blue,"or=",red").
4.2: Troubleshooting Issues
Follow the steps below to resolve any issues you experience during implementation.
- “I see the following error:”
If this appears while you are making changes to your Autosuggest element, it may have been caused by one of the following actions:
- Uploading a new file which is missing some of the column headers you specified for the previous file.
- Deleting an Autosuggest element that was being used as a filter for another Autosuggest element.
- Resetting a column filter to “No Selection” when its filter values still exist.
- Moving an Autosuggest element to the same page as, or a page ahead of, its specified question filter.
Try changing the configuration and then refresh your browser window.
- “I tried to upload an answer source file, but it failed and displayed an error.”
Make sure your answer file meets the listed requirements. If it does, make sure that the following criteria is also being met:
- Your file does not contain spreadsheet formulae (e.g., including “=FORMULA("string",True,0)” will cause an error).
- Your file’s extension matches its type (e.g., an Excel spreadsheet called txt will cause an error).
- “I tried to launch my survey and saw the following error:”
This message indicates that the Autosuggest element is not configured properly. Check that the following conditions are true:
- You have added a valid answer file.
- You have mapped the required columns (“Answer” and “Unique ID” are required).
- Any optional filters you have applied are configured properly.
If you have verified that all Autosuggest elements are configured properly, try refreshing the browser page before re-attempting to launch your survey. You may also try deleting your Autosuggest element(s) and re-building them from scratch.
4.3: Restricting Response Length
By default, there are no limitations on the length of the values participants can enter for Autosuggest rows. If you would like to restrict the length of participant responses, you must use a custom <validate> function.
To add this function to an Autosuggest element, first locate the element within your survey XML. Then copy and paste the following code snippet directly into the element:
<validate>
minLength = 3
maxLength = 10
errorMessage = "Your answer must be between {min} and {max} length. Your answer was {current}."
for qRow in this.rows:
valueLength = len(qRow[1].val)
if valueLength lt minLength or valueLength gt maxLength:
error(errorMessage.format(min=minLength, max=maxLength, current=valueLength), row=qRow)
</validate>
Finally, update the following variables to match whatever values you desire, and save to apply your changes.
minLength: The minimum number of characters you require for a response to be considered valid.maxLength,: The maximum number of characters you require for a response to be considered valid.errorMessage: The text you would like to display within the question when participants enter an invalid response. If desired, you may keep the{min}and{max}variables in order to pipe in your minimum and maximum length values. The{current}variable will pipe in the character count for the participant's original response value.