Multi-Control Questions and Tables

Note: This object is only available in Classic/Default Template surveys.

Single Questions that require multiple fields (controls) can be created using the Multi-Control Question Object.   Multi-control questions are different than standard Illume questions in that with standard questions, you build how the question will look using the question editor, and doing so automatically creates the columns in the database into which the responses will be stored.  In contrast, with multi-control objects, you must follow a two step process:

1. Define how the question will look using the Multi-Control Question Editor

2. Define the variables into which the data from that question will be saved.  These variables are Preload/Hidden variables.

Both steps must be completed for the multi-control to work.

Types of Single Multi-Control Questions:

• Multiple Text Fields
• Multiple Poplists
• Multiple Individual Check Boxes
• Any combination of the above

Steps to create a Text Field Multi-Control Question

The following steps will describe how to create the following example Question:

Steps:

1. From the Add menu select Multi-Control Question
2. In the General Tab Enter the Unique name of the object.
3. This “Unique Name” will not appear in the Data Dictionary as it is just a label for the object itself.  Later in the design process you will define the variables that go into the data dictionary.

4. Enter a Description if desired
5. Optional –Select Anchor this item when randomized – If this object is in a Collection that is set to randomize its contents, checking this box will hold this item’s position constant.
6. Click on the Configure Tab
7. Click the Add Row Button
8. Click in the Cell that was just created in the Table Layout

9. In Cell Controls, Click the Add Button
10. The Control type allows for the following selections:
11. • Prompt
    • Text Field
    • Pop List
    • Check Box

11. Select Prompt
12. Type or paste the Prompt in the Prompt field

 

13. To place the field underneath the prompt, click the Add Row button.  If you would like the field to the right of the prompt click the Add Column button
14. Click in the Cell that was just created in the Table Layout
15. Click the Add Button
16. Enter the Survey Variable Name for this field – As stated previously, this will require the addition of a Preload/Hidden Variable in the survey with the same name. Do not use spaces.  Write down this name so that you’ll remember it when you create the Preload/Hidden Variable of the same name.
17. If a Label is needed, add it in either the Label Before or Label After field
18. Enter any appropriate CSS style information if used

19. Click on the Display Properties Tab
20. Check the box and enter the desired size of the Text Field

NOTE: If the box is not checked and no size is specified the browser will create a default size field. This only sets the actual size of the visible field.  The number of allowed characters will be set in the Validation tab.

21. Click the Validation tab.  You will NOT select a data type here in the question editor.  Rather the data type you wish to capture in this field will be defined in the Preload/Hidden variable editor.
22. If a response is required, click the Require a Response checkbox
23. To enforce the character length, enter the Minimum and/or Maximum number of characters that can be entered in the field
24. To enforce a numeric range, a Numeric Minimum and Maximum can be entered
25. It is also possible to use Regular Expressions matches to enforce very specific text field entry
26. Add a Custom Error Message if desired

27. Click again in the cell that currently has the Feet variable, and follow the steps from 9-26 again to add the next field Inches.

27. After both of the cells are added Select the Run-If tab to apply logic to this object, if the object should only be shown under certain conditions
28. Click OK when finished

30. From the Survey menu select Preload/Hidden Variables
31. Create a preload variable called HFEET, and another called HINCHES.  Each one should be of Whole Number data type, as that is the type of data you want to capture.
32. Preview the Question

Steps to create a Poplist Multi-Control Question

These steps will be used to create the following question:

Steps:

1. From the menu select Survey/Add Runtime Content…
2. Select Multi-Control Question…
3. In the General Tab Enter the Unique name of the object. This name will not appear in the Dataset or the Data Dictionary.

5. Enter a Description if desired
6. Optional – Select Anchor this item when randomized – If this object is in a Collection that is set to randomize its contents, checking this box will hold this item’s position constant.

6. Click on the Configure Tab
7. Click the Add Row Button
8. Click in the Cell that was just created in the Table Layout

9. In Cell Controls, Click the Add Button
10. The Control type allows for the following selections:

10. • Prompt
    • Text Field
    • Pop List
    • Check Box

11. Select Prompt
12. Enter the Prompt in the Prompt field

 

13. To place the poplist underneath the prompt, click the Add Row button.  If you would like the poplist to the right of the prompt click the Add Column button.

14. Click in the Cell that was just created in the Table Layout
15. Click the Add Button
16. Select the appropriate Control Type for the first variable field – In this example select Poplist
17. (OPTIONAL) Checking the – Define local response options will activate the Response Options tab. This is used to filter the list of response options that exist in the Hidden Variable.

18. Enter the Survey Variable Name for this field – As stated previously, this will require the addition of a Hidden Variable in the survey with the same name. Do not use spaces
19. If a Label is needed, add it in either the Label Before or Label After field
20. Enter any appropriate CSS style information if used

21. Click the Validation tab
22. Check the Require a Response box to make this a required variable
23. Enter a Custom error message if desired

24. Click Add Column for the next Poplist and repeat the steps as many times as needed for each field
25. After all of the cells are added, select the Run-If tab to apply logic to this object
26. Click OK when finished
27. Create the appropriate Hidden Variables
28. Preview the Question

Steps to create a Check Box in a Multi-Control Question

While a single check box type question can be added as a Multi-Control type object, they are easily created as one of the Standard Question types.

To add a Check Box to a question follow these steps:

1. In any Multi-Control Question
2. Click the Add Column Button
3. Click in the Cell to add the Checkbox
4. Click the Add Button
5. Select the appropriate Control Type for the first variable field – In this example select Check Box
6. Enter the Survey Variable Name for this field – As stated previously, this will require the addition of a Hidden Variable in the survey with the same name. Do not use spaces
7. If a Label is needed, add it in either the Label Before or Label After field
8. Enter any appropriate CSS style information if used

9. Click the Validation tab
10. Check the Require a Response box to make this a required variable
11. Enter a Custom error message if desired
12. Click OK when finished

Multi-Control Questions with Different Variable Types

A Multi-Control Question can be any combination of the three control types (Text Field, Pop List, Check Box). Create a Multi-Control Object then follow the steps for each type in the cell you are working with.

 

Cell Column Spanning

To achieve a smooth looking prompt it is possible to Span the prompt across multiple Cells.

 

To achieve this, follow these steps:

1. In the Configure tab of a Multi-Control Question
2. Click on the cell that the Prompt is in
3. Set Cell Column Span to the desired length. NOTE: The Cell Column Span will only be a large as the number of empty columns to the right of the selected cell
4. When finished click OK

Steps:

1. In the Survey highlight the desired Multi-control object
2. Click the Preview Selected Item Icon in the Menu bar

 

Multi-Control Question tables allow for any number and variety of controls within the same table.  Like the Multi-Control question, building a Multi-Control table is a two step process of defining how the table will look through the Multi-Control Question Table Editor, and then defining the Preload/Hidden variables that will store the responses captured in each cell of the table.

Steps to create a Multi-Control Question Table

Steps

1. From within the Survey Designer, select Add/Multi-Control
2. Select Multi-Control Question Table
3. In the General Tab Enter the Unique name of the object. This name will not appear in the data dictionary, but will help you identify the object in the Survey Designer.

4. Enter a Description of the Multi-Control table, such as “This table captures the age and gender for each of 5 family members”
5. Optional – Select Anchor this item when randomized – If this object is in a Collection that is set to randomize its contents, checking this box will hold this item’s position constant
6. Click on the Configure Tab to add all of the Columns and Rows within the table
7. Add any Run-If Logic if appropriate
8. When finished Click OK and add the necessary Hidden Variables

Configure Tab

The Configure Tab for the Multi-Control Question Table editor contains three sub-tabs to set up the specifics of the table. They are:

• General – Used to configure specifics for the entire table, like Table Instructions, Prompt Header, Table Width, Numbering, and Randomization
• Columns – Used to define the number and content of the Columns of the table
• Rows – Used to define the number and content of the Rows in the table

General Tab

1. Enter the appropriate Table Instructions
2. Enter a Prompt Header if desired
3. Enter the Table Width – this is how many pixels wide the table will be set to
4. Enter the appropriate code to have the Rows numbered:
   • Blank equals no sub-numbering
   • {0} will number the rows as a, b, c, etc.
   • {1} will number the rows as 1, 2, 3, etc. in sequence with question numbering
5. Decide if the Table Rows are Randomized and, if so, in what way using the drop-down

 

Columns Tab

Depending on the Control Type selected there will be different tabs and configuration choices.  See Control Types in Multi-Control Question Tables for configuration details

Each column will have a single Control Type with corresponding Preload/Hidden Variables to store the data.  Therefore if you have a 3 X 3 question table (3 columns, 3 rows), then you will need to create 9 Preload/Hidden variables to store the values in each of the 9 cells.

Rows Tab

There are three types of Rows available in a Multi-Control Question Table:

• Prompts
• Prompts with Text Fields
• Row Headers See – Row Types in Question Tables

Run-If Tab

Run-If logic for a Multi-Control Question Table follows the same principles as the Show-If logic for Standard Questions and Question Tables.

 

The section describes how to include syntax in your multicontrol table to control the conditions under which the table rows are shown.  It is NOT possible to insert show-if logic on question table columns.  Show-if is only supported on rows of a question table.

The syntax below can be entered while on the Rows tab of the multicontrol editor, in the show-if field. Example: GENDER _eq_ 1.  This syntax would cause the row to show if Gender equals 1.

Row Elements

Attribute Name	Required	Values
showIf	No	This is a simple ShowIf expression of the form:”variable” “op” “value”, where “variable” is the name of a survey variable, “op” is an operator as listed below, and “value” is the value of the variable”op” is any of the following operators:‘_eq_’ is equals‘_ne_’ is not equals ‘_lt_’ is less than ‘_gt_’ is greater than ‘_lteq_’ is less than or equals ‘_gteq_’ is greater than or equals ‘_ans_’ is answered ‘_nans_’ is not answered “value” is a required value except if the _ans_ or _nans_ operators are used.

NOTE:  For show-if logic based on check box items, the appropriate format is GENDER_eq_True rather than GENDER_eq_1

If the show-if conditions for a row are based on more than one variable, it is not possible to concatenate this syntax for two variables.  Rather, you must create a calculation that outputs to true under your conditions, and then use that calculation in your show-if logic.

For example, let’s say a row is to show if Gender = 1 and if Age=18.  You need to create a calculation (we’ll name that calculation “GENAGE_CALC”)  such as

(({Value:GENDER}=1)&&({Value:AGE}==18))?1:0

This calculation will output a “1” if the two conditions are met.  Next, in the show-if field of the multicontrol table editor, you would insert:

GENAGE_CALC_eq_1

 

 

 

There are six different controls types that can be used in a Multi-Control Question Tables.  Five of the Controls are used to define a question field and one is used to insert a space between columns.

The Control Types are:

• Empty
• Text Field
• Radio Group
• Pop List
• Check Box
• Check All That Apply

After following the beginning steps to create a Multi-Control Question Table the Survey Programmer will select the Control Types for the Columns within the table.

Example Table:  In this table, the first two columns are Text Fields.  In between the first two columns and the 3rd is an Empty control type. The next 5 columns are part of a Radio Group, with a Column Header of “Guardian Type”.  The 8th column is a Pop List, the 9th column is a Check Box, and the final 3 columns are Check All That Apply with a Column Header of “Previous Childhood Illnesses”.

NOTE: For all Column Headings Piping can be used

Text Field Control Type

Steps

1. Locate the Table Column section in the Columns Tab of the Multi-Control Editor
2. Click on the General Tab
3. Enter a Column Heading to identify the type of information you are requesting in this column
4. Select Text Field in the Control Type drop-down
5. Enter the Variable Prefix for this control.  Every variable in this column will have the same prefix.  For example, in this column we are asking for each child’s name.  Each field that captures a child’s first name will start with CFN_.  The name of the first child will be stored in a Preload/Hidden variable called CFN_1.  The name of the second child will be in a Preload/Hidden Variable called CFN_2, and so on.  Thus the survey designer must define the variable prefix, and then each field down the column will get a numeric sequential suffix starting with “1”.
6. Enter any Show-If logic if desired – See Question Table Syntax for Show-If Operators

7. Click on the Display Properties Tab
8. Enter a Column Width in pixels.  Setting a column width ensures all columns are of equal width.
9. Enter a Label either Before or After the field if appropriate
10. To set the Field Size check the box and enter the desired size – This is the display size of the field, not how many characters are allowed (that is handled on the Validation tab).

11. Click on the Validation Tab
12. Check the box to make this control Required if appropriate
13. If the field will have specific bounds for Minimum and/or Maximum number of characters, check appropriate boxes and enter the max/min values. The default for a Text Field is 255 characters
14. Add a Regular Expression match if needed – See Regular Expression Examples
15. Add a Custom Error Message if desired
16. Click the Add Column Button

17. The Column will show in the list above the Table Column Configuration Field

18. To add another Control, go back to the general tab and repeat for another Text Field Control or follow the steps below for the other types of controls.

Radio Group Control Type

Steps

1. Locate the Table Column section in the Columns Tab of the Mult-Control Editor
2. Click on the General Tab
3. Enter a Column Heading
4. Select Radio Group in the Control Type drop-down
5. Enter the Variable Prefix for this control.  As with Text control type, the user defines a variable prefix for each of the cells in this column.
6. The  Define local response options:  Users have the option of defining the scale for the radio group options within the multi-control editor, or within the Preload/Hidden variables created later to store the response to the radio group selection.  It is generally recommended to NOT check “Define local response options” and instead create the scale in the Preload/Hidden variables, as doing so will provide for more flexibility in querying your data in the data manager.

7. Enter any Show-If logic if desired – See Question Table Syntax for Show-If Operators

8. Click on the Display Properties Tab
9. Enter the desired Column Width in pixels
10. Click on the Validation Tab
11. Check to make this a required column if desired.
12. Enter a custom error message if desired.

13. Click on the Randomize Tab
14. Check if the Options should be Randomized and the Method for the Randomization
15. Click the Add Column Button

Pop List Control Type

The Pop List Control Type follows the same steps as the Radio Group Control Type, except that the control type of Pop List is chosen instead of Radio Group.

Creating the Corresponding Preload/Hidden Variables

A Preload/Hidden variable must be created to capture the value for each cell in the multi-control table.  For control type of poplist and radio button, if you did not check “Define local response options”, you will need to define the scale on the Scale tab of the Preload/Hidden variable editor.  For larger tables, it is most efficient to create a single preload variable with the correct scale defined, and then using cntrl+c to Copy the Preload/Hidden variable, and then cntrol+ V to paste, and then just edit the name and the description.

The names of your Preload/Hidden variables need to match the prefixes you defined in the table editor.  Thus if column one’s prefix is CFN_, and the table has 5 rows, you will need to create 5 Preload/Hidden variables named CFN_1, CFN_2, CFN_3, CFN_4, and CFN_5.

Check Box Control Type

Steps

1. In the Table Column configuration field in the Columns Tab of the Mult-Control Editor
2. Click on the General Tab
3. Enter the Column Heading if it is appropriate – Piping can be used
4. Select Check Box in the Control Type drop-down
5. Enter the Variable Prefix for this control
6. Enter any Show-If logic if desired
7. Click on the Display Properties Tab
8. Enter the desired Column Width
9. Click on the Validation Tab
10. Check the box to make it Required
11. Add a Custom Error Message if desired
12. Click the Add Column Button

Check All That Apply Control Type

Steps

1. In the Table Column configuration field in the Columns Tab of the Multi-Control Editor
2. Click on the General Tab
3. Enter the Column Heading – Piping can be used
4. Select Check All That Apply in the Control Type drop-down
5. Enter the Variable Prefix for this control
6. NOTE: A Hidden Variable must be created for each of the checkbox responses in a Check All question, for each row in the table.  For example, if you have two checkbox responses (e.g. Attended, Graduated) and two rows in the table (e.g. “1. High School”, “2. College Undergraduate”), you will need to create four variables (e.g. ATTEND_1, GRAD_1, ATTEND_2, GRAD_2).

7. Enter any Show-If logic if desired
8. Click on the Display Properties Tab
9. Enter the desired Column Width

10. Click on the Validation Tab
11. Select Min Checked and Max Checked to set limits
12. Add a Custom Error Message if desired
13. Click on the Randomize Tab
14. Check if the Options should be Randomized and the Method and Arguments for the Randomization
15. Click the Add Column Button

To Define Local Responses

1. Open the Runtime Content Object
2. Go to Configure / Columns /General
3. Check the – Define local response options – check box.  This will activate the Response Options tab.
4. Click on the Response Options Tab
5. In the Name Field enter the Column Name for the Check box – This will be part of the header in the dataset – The Names must be exactly the same as those created in the Hidden Variable.
6. In the Heading Field enter the visible response option – This may be different from those used in the Hidden Variable and supersede those in the Hidden Variable
7. Click Add
8. Repeat for all response options

 

Empty Column Control Type

Steps

1. In the Table Column configuration field in the Columns Tab of the Multi-Control Editor
2. Click on the General Tab
3. Enter the Column Heading if it is appropriate – Piping can be used
4. Click on the Display Properties Tab
5. Enter the desired Column Width
6. Enter any CSS Style information for both the Cell or Heading
7. Click Add Column
8. The Space will show as an X in the Variable Prefix column. If there is a Header for the Space it will show under Column Heading.
9. The space can be moved to any desired location in the list by clicking and dragging

There are three Row types that can be used in a Multi-Control Question Table.

Row Types

• Row Prompt
• Row Prompt With Text Field
• Row Header

Example:  In the example below, “Child 1, Child 2, Child 3” are Row Prompts, “Not living int he Home but counted” is a Row Header, and “Location of Child” is a Row Prompt with Text Field

Creating a Row Header

A row header creates a row in the table that is purely for labeling the rows below it, but does not actually collect any data.

Steps

1. In the Rows Tab of the Mult-Control Table Editor
2. Select the Row Header type in the drop-down
3. Enter the Header – Piping may be used
4. Enter any Show-If Logic (see the page on question table syntax)
5. Enter any CSS Styles used for the Header
6. Click Add Row

Creating Row Prompts

A row prompt is used to label a row that will collect data.

Steps

1. In the Rows Tab of the Mult-Control Editor
2. Select the Row Prompt type in the drop-down
3. Enter the Prompt – Piping may be used
4. Enter any Show-If Logic (see the page on question table syntax)
5. Click Add Row

 

Creating Row Prompts With Text Field

Steps

1. In the Rows Tab of the Mult-Control Editor click on the General Tab
2. Select the Row Prompt With Text Field type in the drop-down
3. Enter the Prompt – Piping may be used
4. Enter any Show-If Logic
5. Click on the Text Field Tab
6. Enter the Preload/Hidden Variable Name that will be used for the Text Field.  The survey variable you enter here is not a prefix, but rather the full data dictionary name of the preload/hidden variable that will be used to store the response entered into this text field.
7. Add a Label Before or After if desired
8. Decide on the Text Field Size and Maximum Characters
9. Click Add Row
10. Create a Preload/Hidden variable name and give it the name entered in the Survey Variable text box.

Multi-control questions and question tables are unique from standard questions in that users must not only define the display through the question editor, but must also define Preload/Hidden variables for each field within the multi-control object.

1. From the Survey menu select Preload/Hidden Variables
2. Click Add
3. The Unique name should match the Variable names or Prefixes used in the Control Type Configuration

• If creating a Single Question or Text Field Row Prompt, the Hidden Variables should have the same name as the Survey Variable name used for the cell or field.
• If creating a Question Table, the Variable Prefix and the number of rows will determine the Variable Name. (e.g. prefix=”Q_” and there are 3 rows). This will require the creation of 3 Hidden Variables (Q_1, Q_2, Q_3), which correspond to the number of rows that are in the table.

6. Select the Value Type as either Single-Value or Multi-Value(Check All).  If creating a Single-Value type, select the Data Type as well for the field.
7. Keep the Default Value as None
8. Enter a Prompt Description of the field.  It is important to use a meaningful description, as this description will be in your data dictionary
9. Click OK
10. Repeat Steps 1-9 for each field in the Multi-Control Question/Question Table

 

If a Check All Question is being used then Click on the Scale tab and Name and Display Text for each response.

The Multi-control Object uses a Run-if statement to determine whether the multi-control object should be shown, and under what conditions.  This functions in the same manner as show-if logic as applied to standard questions.  If the object should only run under certain conditions, the “Only run if” option is selected.  You must then select the variable or variables that determine whether the object should be shown, and the conditions under which it should be shown.