Create questions tutorial (r9)

Many of the closed-ended examples in this section use this COLORS list as response options.

Like many programmed questions, options are defined by a number (creating the option ID), followed by a period, a space (recommended, but optional), and then the option text.

Lists of options can be defined independently as standalone widgets, or within other widgets (i.e., questions and tables). Various types of option decorators will be introduced throughout these tutorials, which add functionality to an option or group of options.

setlist: COLORS
1. Black
2. Blue
3. Green
4. Orange
5. Purple
6. Red
7. Violet
8. Yellow

A1. Do you like colors?
Yes, No
[Single select]

A1 and A1A are standard radio button questions. By default one and only one answer must be selected.

Add this code to your survey and run it to see the result.

A1. Do you like colors?     
type: radio  
1. Yes
2. No

A1A. What color is a ripe tangerine?
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow
[Single select; split into 2 columns]

A columns formatting tag may be used to split a list of options into multiple columns.

Since this uses the colors from our COLORS list, we can "pull in" our list's elements with the optsfrom tag.

A1A. What color is a ripe tangerine?
type: radio
optsfrom: COLORS
columns: 2

A1B. What color is a ripe banana?
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow
[Single select drop down menu]

A pulldown response box displays a menu of options that emerges when clicked.

The prompt tag defines the text that shows at the top of the selection box. This space is blank by default. An example of a commonly added symbol or visual cue is '>>'.

A1B. What color is a ripe banana?
type: pulldown
prompt: >>
optsfrom: COLORS

A1C. What color is a ripe strawberry?
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow
[Single select with horizontal scale]

A standard question using the hscale tag changes its orientation so the options are arranged horizontally (across) instead of vertically.

The scale tag can also be used to auto-fit options horizontally in some themes.

A1C. What color is a ripe strawberry?
type: radio
hscale: y
optsfrom: COLORS

Once you finish reviewing each survey question, add the widgets to your survey area via the SPL editor. Any time the survey code compiles without any errors, you will be taken to the next screen called the survey compilation page. You can launch Testmode by clicking the Test 2 button from this screen, or you can open the Test Survey applet from the left navigation menu. Review your survey and test your new questions. After testing your survey, be sure to make any necessary corrections. Make this your routine following each section.

Read Test levels and 'testmode' for more information.

Discussion Details

Question variables in the dataset are prepended with a 'Q' by default. However, this prefix can be modified using the leading_q: n tag at the question, group, or survey levels. Adjustments to survey-level settings can be made through the set defaults widget. 

In Excel or SPSS data files, each single-choice question is allocated one column of data storage. For example, question A1A's data will constitute one column in the dataset, containing values of '1' to '8' as a response (or left empty for a non-response). Export survey data in Excel (via the Deliverables applet) to confirm.

A2. Of these, what colors do you like? [Select all that apply]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow
[Allow multiple selection]

A2 and A2A are standard type: checkbox questions.

The instructions tag (alias instruct) is used to differentiate between question text and respondent instruction text. For example, 'Select all that apply' may be displayed to let respondents know how to answer the question.

A2. Of these, what colors do you like?
instructions: Select all that apply
type: checkbox
optsfrom: COLORS

A2A. What 3 colors are most common for apples? [Select exactly 3]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow
[Select 3, show in 4 columns]

A numchecked tag will set the exact number of selections allowed. Once 3 are picked, the rest are grayed out/disabled.

The columns tag can be used to split the list into four columns.

A2A. What 3 colors are most common for apples?
instruct: Select exactly 3
type: checkbox
numchecked: == 3
optsfrom: COLORS
columns: 4

A2B. What colors are grapes? [Select all that apply]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow NEW: Other (specify)
[Multi-select, with 'other specify' option]

An "other specify" option can be added using the autoother decorator. For A2B, this provides a place to type a color that's not already listed. This function allows you to define additional behavioral parameters. For mobile-friendly themes, save space by using a placeholder parameter to put a 'Specify' textual prompt inside the field box.

By placing the "other" option directly on the question after the optsfrom, it will automatically stay at the end even if the options from the list are randomized.

A2B. What colors are grapes?
instruct: Select all that apply
type: checkbox
optsfrom: COLORS
97. Other {autoother: y; placeholder: Specify}

A2C. What colors are in a rainbow? [Select all that apply]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow NEW: None
[Multi-select, with exclusive 'none' option]

An exclusive decorator should be added to prevent survey takers from selecting "none" together with additional options for any multiple-select question.

A2C. What colors are in a rainbow?
instruct: Select all that apply
type: checkbox
optsfrom: COLORS
99. None of these {exclusive: y}

A2D. Are any rooms in your home painted in these colors you like? [Select all that apply]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow NEW: None
[Multi-select, exclusive 'none' option; Show options checked at QA2]

To display previously selected options, we can simply reference the variable where they were selected. For example, A2D references A2 with 'optsfrom: QA2'. Referencing a question like this carries logic forward, so that only the colors selected in A2 are piped in (displayed) at A2D.

Placing an if condition on the options is another way to limit what should be shown based on previous responses. See A2D_ALT for an example. Both questions would render the same result on screen and in the data output.

A2D. Are any rooms in your home painted in these colors you like?
instruct: Select all that apply
type: checkbox
optsfrom: QA2
99. None {exclusive: y}

#Alternative method for limiting responses to be shown
A2D_ALT. Are any rooms in your home painted in these colors you like?
instruct: Select all that apply
type: checkbox
optsfrom: COLORS {if anyChecked($QA2,[id])}
99. None {exclusive: y}

A2E. Are any rooms in your home painted any of these colors? [Select all that apply]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow NEW: None
[Multi-select, exclusive 'none' option; Show options not checked at QA2D]

When an if condition is present, it overrides any "background" logic being carried forward. Here, A2E will show the colors not picked at A2D. Since this new condition doesn't specify whether the option must also be selected at QA2, all original options from QA2 are included, resulting in the functional equivalence to using the COLORS list.

We'll cover the if condition method more later.

A2E. Are any rooms in your home painted any of these colors?
instruct: Select all that apply
type: checkbox
optsfrom: QA2 {if noneChecked($QA2D,[id])}
99. None {exclusive: y}

A2F. What color decor accents do you prefer?
[Hold ctrl, scroll or click to pick up to 4]
Black, Blue, Green, Orange, Purple, Red, Violet, Yellow NEW: White, Brown, Grey
[Multi-select, with new local options. Only allow up to 4 colors]

A type: listbox question allows multiple option selection in a scrollable list. Instead of a checkbox next to each option, this type of question lists the options in a box where respondents can Ctrl-click to select multiple options.

The size tag is used to make the list box longer.

The maxchecked tag is also used to limit the selections to 4.

A2F. What color decor accents do you prefer?
instruct: Hold ctrl, scroll or click to select up to 4
type: listbox
size: 11
maxchecked: 4
optsfrom: COLORS
9. White
10. Brown
11. Grey

Discussion Details

Although Response reports are largely similar to a deliverable export, there are some notable differences. Response reports display the data for checkbox questions in a single column. If more than one option was checked, the options are presented as a comma-separated list.

Exports display the data for checkbox questions in a multi-column format, where each option has its own column. Each column has a value of '1' (selected) or '0' (not selected). The column headers have the option number appended to the question number, such as 'QA2.1' for QA2, option 1.

Additionally, exports have a second tab called "Questions" which map the question and option IDs to the values displayed in the column headers; Response reports do not have this tab. You can review this in more detail in the article Creating a new export.

Multiple choice questions generate one data location per option, resulting in each answer option having its own column in an Excel export.

The COLORS list contains eight options. Consequently, eight variables are created to store the data for a multiple choice question using the COLORS list, and an Excel export will have eight columns to store the data.

For instance, QA2.1 is the storage for the color 'Black' on QA2. If a respondent selects 'Black' at this question, there will be a '1' in the data location QA2.1. If 'Black' is not selected, there will be a '0' in this location.

QA2.2 is storage for the color 'Blue' on QA2. If a respondent selects 'Blue' at this question, there will be a '1' in the data location QA2.2. If 'Blue' is not selected, there will be a '0' in this location.

This pattern continues for each color on the list for QA2, resulting in eight locations in total.

The same conventions apply to A2A — eight data locations, QA2A.1 through QA2A.8, are created (one for each color), each containing a '1' for checked and a '0' for not checked.

The rest of the questions in this section store data in the same fashion. This is the standard output format for multiple choice data.

At A2B, the addition of the "other" option adds QA2B.97, storing a '1' when checked and a '0' when not checked.

The autoother function adds two locations, QA2B.97 for checked or not, and QA2B_97_OTH to store the textual response required when checked.

A2B ends up with 10 data locations, eight for the colors and two for autoother.

A2C includes an extra option, '99. None of these', making 9 locations for this one. Data for the "none" option is stored in QA2C.99.

The exclusive tag makes it so all other color locations for this question (QA2C.1 through QA2C.8) would contain a '0' if the QA2C.99 location contains a '1'.

A2D and A2E produce the same data output even though the options render conditionally for respondents.

A full data structure is generated for every question to provide storage for any combination of responses. Logical conditions used to pipe options don't typically impact the data structure, only how questions render for the survey taker.

A2F is a listbox question. It generates standard output format for multiple choice data.

This question has additional options for 'White', 'Brown', and 'Grey' added locally to the question, making a total of 11 columns in the dataset.

A3. What color is your hair?
[PROVIDE TEXT BOX] Enter natural color

type: text questions allow a typed response.

The maxlen tag defines the maximum number of characters that can be typed.

The placeholder tag can be used to display a textual prompt inside the entry box that disappears once typing begins.

A3. What color is your hair?
type: text
maxlen: 20
#size: 20
placeholder: Natural color

A3A. What is the most common color you dye your hair?
[Enter color or select 'I do not dye my hair']
Preferred hair dye color:______ / I do not dye my hair [EXCLUSIVE]

Use the prefix tag to place text in front of the text entry field box. For providing a dynamic opt-out response alternative, use the declinetoanswer (dta) tag.

A3A. What is the most common color you dye your hair?
instruct: Enter a color or select 'I do not dye my hair'
type: text
prefix: Preferred hair dye color:
maxlen: 20
dta: 99. I do not dye my hair

A3B. How many times a day do you wash your hair?
[Enter a number 0 to 5]
[FORCE NUMBER] __ time(s) per day

datatype: whole adds conditional formatting to an answer field, which elicits an error message if a (positive) whole number is not entered. Either a type: text or type: number/integer can be used to create this question.  

A postfix tag can be used to place text after the text-entry box.

The range tag sets an allowable response range. If a number outside the range is entered, an error message is triggered.

# 'type: text' method
A3B. How many times a day do you wash your hair?
instruct: Enter a number 0 to 5
type: text
datatype: whole
range: 0-5
postfix: time(s) per day

# 'type: number' or 'type: integer' method
A3B. How many times a day do you wash your hair?
instruct: Enter a number 0 to 5
type: number
#type: integer
datatype: whole
range: 0-5
postfix: time(s) per day

A3C. For classification, what is your ZIP code?
[ZIP FORMAT] ZIP code:

ZIP codes may be used to derive state, region, and other geographic data.

It's easy to add US geographic classifications to your dataset with the uszip5 question type. By specifying type: uszip5, respondents are forced to provide a response in the ZIP code format, triggering additional hidden ZIP-related variables.

A3C. For classification, what is your ZIP code?
type: uszip5
prefix: ZIP code:

A3D. Where can we email our hair care instructions?
[EMAIL FORMAT] [Enter your email]

Survey questions may solicit information such as a person's name, email address, phone number, and other personal details. This type of data, known as personally identifying information (PII), is subject to specific protocols and guidelines. For the purposes of this exercise, let's assume that you have obtained permission to collect a respondent's email address and phone number.

You may use datatype: email for email address input. The built-in validation requires both an '@' symbol and a '.' somewhere thereafter, in amongst other alphanumeric characters.

A3D. Where can we email your hair care instructions?
type: text
datatype: email
maxlen: 50
size: 50

A3E. Best number to reach you?
[PHONE FORMAT] Phone number...

Use datatype: phone to force a response in the form of a US phone number.

The phone datatype defaults to allow multiple formats such as dashes, dots, parentheses, spaces or no spaces, as long as a full 7 to 10 digit number is entered.

A3E. Best number to reach you?
type: text
datatype: phone
placeholder: Phone number...

A3F. What is/was the date of your appointment?
[DATE FORMAT] [Enter or select date] __________

Using type: date will generate an interactive calendar from which a respondent can select a date.

This question type uses a date-picker control to limit responses. Additional tags may be used to restrict responses to a specific time period or days of the week.

A3F. What is/was the date of your appointment?
type: date

A3G. Please explain how you wash your hair in full detail.
[Please type in a response]

A textbox question, or type: textbox, is used for longer open-ended responses or essay style answers. The textrows and textcols tags can be added to change the size of the box.

As in a type: text question, a placeholder tag can be used to display a textual prompt inside the text box.

A3G. Please explain how you wash your hair in full detail.
instruct: Please type in a response
type: textbox

For the "decline to answer" feature at QA3A, a QA3A_DTA variable location is created for the DTA field, which will have a value of '99' when selected and is left blank when not selected.

By default, the dta tag will generate a new variable in the dataset, listed after the question.  

In terms of the data at A3C, because it's a uszip5 question type, the result is a field with 5-digit numeric responses. The six additional associated geographic classification questions are all single-select, closed-ended variables that appear in the dataset just after the ZIP question. They would be labeled as QA3C_STATE, QA3C_REGION, QA3C_DIVISION, etc.

In the dataset, the email datatype retains the data exactly as it was input by the respondent, however email and phone are two datatypes for which data is automatically encrypted.

Although the phone datatype at A3E allows for various formatting options upon entry, the data is stored in the XXX-XXX-XXXX format, where the X's represent the digits.

A value entered at a datatype: date question will appear in the dataset in a YYYY-MM-DD format. Date questions always store data in this format.