Skip to main content

Search

Create options tutorial (r8)

  • Updated

Overview

All closed-end questions and tables require options. Options can be defined from spreadsheets, in standalone lists known as setlists, or locally defined on questions and tables. They can be used again later on subsequent questions once they are defined.

Lists are used more broadly in the code, not just to create response options, but also to create batteries for tables or card sorts, to run blocks, and otherwise allow us to reuse information. Lists are especially useful for blocks and loops due to the ability to create option data. This tutorial covers the most commonly used option and list conventions.

Related reading and resources

The following articles can be used for reference with this training module:

Review

Close-ended questions must define options, and the majority of the questions and tables you've created so far have been close-ended. We already used options in both the Create questions tutorial and the Create tables tutorial.

The type tag determines the functionality of the question, whether text is allowed, numeric input, single selection, etc. How data is stored for a variable/widget depends on the question type or table type. Then, series, lists, or sheets used with the optsfrom tag or options defined locally determine the answer set, which is the information stored for closed-end data types.

The questions you've created with type: radio, type: pulldown, type: checkbox, or type: listbox, from the single and multiple choice sections, and almost all of the tables from "Create tables tutorial," generate close-ended data and have option lists. Questions can define options with series, or by calling one of the lists like SHAPES, PLACE, or COLORS with optsfrom, and similarly tables can reference the rows defined in a previous table with rowsfrom. In a few places you've created locally defined (inline) option lists, for instance at A1 and A2F. You also have called in lists used in previous questions by referencing either the question ID (which carries forward logic), like A2D, or referencing the question's inline options/rows (which use the full option list) like at table B5B.

Lastly, close-ended tables encompass both options (the answer set) and the rows or columns used to ask multiple questions. In summary, it's a table containing a series of questions with corresponding options to choose from. Each row or column generates a data point to store data, and the options are the values stored.

Note: The first example of an open-ended question you came across was the autoother at A2B in the Multiple choice questions section of the "Create questions tutorial." As you may recall, the autoother function adds a text entry box to an "other specify" option. The '97' option itself is part of the closed-end question A2B. When '97' is selected, a response must be typed in, and the captured text is open-ended. The Text entry questions section in the "Create questions tutorial" covers open-ends in greater detail.

Setup

In this section we are going to take a closer look at local options and various ways to work with them. In addition, we will take a closer look at lists, using lists in a variety of ways, including using option data for questions and blocks.

Setup Discussion

Code Review

Tag Review

Options can be defined locally on questions or tables, referred to as inline options. They can also be pulled in from a list with the optsfrom tag, and sequential lists can be defined with the series tag.

Tip! Sheets are another form of a list where option data can be organized in columns, like a typical spreadsheet. Consider using sheets for larger lists, such as an extensive brand list, and for lists with several related elements such as a large ZIP code list with state, region, division, and MSA classifications.

We will not cover this method in this tutorial. See Creating and editing survey spreadsheets and Using spreadsheets in survey programming for more information.

This code is needed for this section:

setlist: PARTS
1. Petals
2. Stamen 
3. Roots
4. Stems
  • setlist
  • list
  • series
  • optsfrom

Lists can be called with any of the *from tags:

  • optsfrom
  • rowsfrom
  • colsfrom
  • targetsfrom
  • cardsfrom
  • ranksfrom

Option Piping video

The following video discusses the various ways in which you can "pipe" or reuse the options used with previous survey questions and tables. Local/inline options, setlists (standalone lists), and condition decorators are covered. We recommend you watch this video before continuing with the tutorial.

Local options

The examples in this section cover various ways to manipulate options at the question level known as inline options.

Questionnaire Content Discussion Details Coded SPL

[Keep C1 & C1A on the same page]
C1. What flower color do you prefer the most?
[Single select] Options: Orange, Red, Yellow

 

C1 calls the COLORS list with optsfrom, as we've done in previous tutorials. Reminder, the COLORS list was created as a standalone list with the set list widget.

This example uses include/exclude, +/-[ids] syntax. This will limit the options pulled in from the COLOR list. To include options, simply list them in [square brackets] just after the list name; i.e., [4,6,8], will include only 'Orange', 'Red', 'Yellow' from COLORS. This syntax must be included before any decorator elements.

Using the include/exclude function actually changes the data structure. If you review the reports for C1, you'll see that only options for the three colors we are including are present. In the the case of C1C (further below), only the first five options are created because we are excluding the last three options.

This is quite different from filtering options with if conditions, or using question references to carry forward selection logic. In those cases, all colors would still have designated data locations, and only the ones meeting the criteria would be displayed for the respondent.

 
C1. What flower color do you prefer the most?
type: radio
optsfrom: COLORS [4,6,8]

C1A. Which part specifically?
[Single select drop down]
Options: [Show Petals, Stamen for each color from C1]

To keep C1 and C1A on the same page, we added the ap: n (autopage) tag to C1A.

Note that C1A and C1B both define options directly on the question, known as local (or inline) options.

C1A uses the dynamicoptions tag. This tag triggers the options to show up conditionally based on the criteria that is met from previous responses.

C1A is using a numbering scheme to identify which color for petals or stamen is selected. This type of numbering can be useful for data processing and organization. It can also be helpful for surveys with more complex logic where a Perl sub-string could be used to look at each position in the ID to figure out the color or part.

Tip! There is usually more than one combination of tags and widgets that will create what you need. The approach you take depends on the survey. For simpler surveys, it's important to avoid unnecessary complexity; the simpler approach is often the best choice. For more complex surveys, it becomes tricky to introduce more complexity if you have not planned for it in advance. Therefore, design your code to accommodate the specific requirements of the survey you are working on.

In the section below, crosslists are used to re-create C1A with the same front-end respondent experience, and the same back-end data storage, but the code is more complex.

 
C1A. Which part specifically?
ap: n
type: pulldown
dynamicoptions: QC1,{4 =>[41,42],6=>[61,62],8=>[81,82]}
41. Orange Petals
42. Orange Stamen
61. Red Petals
62. Red Stamen
81. Yellow Petals
82. Yellow Stamen

C1B. Which [Insert C1 Response] flower is your favorite?
[Single select]
1. California Poppy [Show for Orange]
2. Desert Mallow [Show for Orange]
3. Marigold [Show for Orange or Yellow]
4. Begonia [Show for Red]
5. Laceleaf [Show for Red]
6. Daffodil [Show for Yellow]
7. Sunflower [Show for Yellow]
8. Hibiscus
9. Tiger Lily
97. Other (specify)

C1B is using an if condition decorator to filter the options. C1B also uses closed-ended piping to pipe the option selected from C1 into the question text.

C1B combines answer piping with Perl's lowercase function to make it so the results are lower-cased and blend in with the question text. Without this function, the answer would be piped into the question text as it is, with the first letter of each word capitalized. In certain instances, having capitalized letters mid-sentence may not be ideal. In other cases where you're piping a brand, maintaining the casing could be appropriate and the extra Perl would not be necessary.

The 'lc' in the pipe stands for "lower case"; 'uc' can also be used if you wanted to upper case all the letters.

 
C1B. Which [* lc($QC1_text) *] flower is your favorite?
type: radio
1. California Poppy {if anyChecked($QC1,4)}
2. Desert Mallow {if anyChecked($QC1,4)}
3. Marigold {if anyChecked($QC1,4,8)}
4. Begonia {if anyChecked($QC1,6)}
5. Laceleaf {if anyChecked($QC1,6)}
6. Daffodil {if anyChecked($QC1,8)}
7. Sunflower {if anyChecked($QC1,8)}
8. Hibiscus
9. Tiger Lily
97. Other {autoother: y; placeholder: Specify)}

C1C. Of these, what color do you prefer the least for flowers?
[Single select] Options: Black, Blue, Green, Orange, Purple

C1C also calls the COLORS list with optsfrom, and the exclude syntax is used to omit the last three colors from the COLORS list. To exclude options, list them in [square brackets] like we would for include syntax, and add a '-' (minus sign) to subtract them from the list. For example, i.e., -[6..8] will exclude 'Red', 'Violet', and 'Yellow' from COLORS and show the other five options.

 
C1C. Of these, what color do you prefer the least for flowers?
type: radio
optsfrom: COLORS -[6..8]

C1D. Rate each part of the plant on a scale of 1 to 5.
1 means plain and 5 means stunning
Options: 1=Plain, 5=Stunning
[One per row] Petals, Stamen, Roots, Stems

C1D is using the series function to define sequential numbers for the options. For rating scale tables, the headings tag is needed to let respondents know each end of the scale; in this case, that 1 = "Plain" and 5 = "Stunning".

You've used the series tag in earlier tutorials on B1A and B1B to create common rating scale tables. The series function is also commonly used to create a list of sequential years, sequential ages, or any sequential list of numbers. It even allows you to easily alter displayed text using the text decorator, e.g. "Brand 1," etc.

 
C1D. Rate each part of the plant on a scale of 1 to 5.
type: radio_table
headings: Plain, Stunning
optsfrom: series[1..5]
rowsfrom: PARTS
Training Tutorials
Continue to work in your FLast_r8_intro survey (visit Training tutorials for set up steps) and add the new content from each practice section via the Survey Editor. When the survey compiles successfully, launch Testmode by clicking the Test 2 button from this screen. Review your survey and test your new questions. After testing your survey, be sure to make any necessary corrections. Then, review the data output by viewing a Response report or creating a new export in Deliverables.

Reminder, once you integrate all the new content from this tutorial and test it, publish your survey before moving on to the next tutorial.

List options

The examples in this section use tags associated with setlist widgets, plus many list conventions covered in Lists overview.

Questionnaire Content Discussion Details Coded SPL

C2. Of the following flowers, which ones have you ever grown?
[Select All] Options: SHOW C1B OPTION LIST/pipe other + Rose, Tulip, Daisy, Other, None [EXCLUSIVE]

 

In C2, the instruction uses a combination of options from previous questions and new options. To do this, create a setlist with the optsfrom tag to call in previously defined options from C1B, and add the new options locally, making one comprehensive FLOWERS list.

Tip! We've already combined multiple lists in the Creating tables tutorial at table B5A and B5B.

Here, the 'QC1B.options' used at optsfrom is an example of a derived list. Derived lists pull in all inline options from a previous question or table. Whereas referencing the question ID 'QC1B' would only show the selected options, using 'QC1B.options' will show all original options in the list.

In addition, this question needs to include an exclusive 'None' option, which is defined locally.

 
set list: FLOWERS
optsfrom: QC1B.options
10. Rose
11. Tulip
12. Daisy
96. Other {autoother: y; placeholder: specify}

C2. Of the following flowers, which ones have you ever grown?
type: checkbox
optsfrom: FLOWERS
99. None of these {exclusive: y}

C2A. Do you have any of these flowers in your garden this year?
[Select one per row] Options: Yes, No
SHOW ALL C2 OPTIONS

C2A is a basic single choice table with Yes/No options defined directly on the table. The rowsfrom tag is used with the FLOWERS list to create the "row questions," meaning each defines a unique data point. The Yes/No responses are the actual options for the table. These are the answer choices that will be stored as an answer for each flower row (or question).

 
C2A. Do you have any of these flowers in your garden this year?
type: radio table
1. Yes
2. No
rowsfrom: FLOWERS

C2B. Of the flowers you have this year, which ones will you grow next year?
[Select All] Options: SHOW C2A OPTIONS SELECTED Yes + None [EXCLUSIVE]

C2B is a standard checkbox question and the instruction wants to only pipe in the options with 'yes' from C2A. To do that, the question will use the same flowers list with an if condition decorator that uses an [id] iterator.

C2B is using the [id] iterator to check the table rows at C2A. Imagine the [id] being replaced with each row ID from the FLOWERS list, e.g.'C2AR1', 'C2AR2', etc. Then, any rows with the value '1. Yes' will pipe into C2B.

 
C2B. Of the flowers you have this year, which will you grow next year?
type: checkbox
optsfrom: FLOWERS {if anyChecked($QC2AR[id],1)} 
99. None of these {exclusive: y}

Crosslists

Crosslists are lists built from combining two or more lists, creating a list entry for every potential permutation of options from the source lists. Below we'll discuss how crosslists are created and how the resulting option IDs and option text are denoted in our software. We'll also cover some of the tags that can be applied in conjunction with crosslists.

Questionnaire Content Discussion Details Coded SPL

C1A. Which part specifically?
[Single select drop down]
Options: [Show Petals, Stamen for each color from C1]

 

Above in Local Options, C1A has the parts by color written out as local options directly on the question. This is fine for simple questions like this. As complexity is added, it will make things easier to use some of the more advanced features like crosslists.

It is possible to organize the code differently with crosslists and accomplish the same outcome. This example re-creates C1A, with the same look and feel, and the same data. The crosslist uses the include syntax to call in the same three options from the COLORS list with '[4,6,8]', and the first two options from the flower PARTS list with '[1,2]'.

The option IDs are concatenated, and the ID separator is an underscore by default, (e.g., '4_1'). The crosslistidseparator tag used here overrides the defaults and passes in a blank or null value, which creates the same IDs used on the original C1A above (e.g., '41').

The text is also concatenated, so the text is comma separated by default, (e.g.,"Orange, Petals''). Adding the crosslisttextseparator  as shown removes the comma so the text shows color, a blank space, the part, creating the same option text used in the original question above, (e.g.,"Orange Petals'').

In your FLast_r8_intro code, replace C1A from earlier in this section with this crosslist example.

Note: Crosslists are commonly used for gender by age nested quotas and have many useful applications.

 
setlist: COLOR_PARTS
crosslists: COLORS [4,6,8], PARTS [1,2] 
crosslistidseparator:
crosslisttextseparator:

C1A. Which part specifically?
ap:n
type: pulldown
dynamicoptions: QC1,{4 =>[41,42],6=>[61,62],8=>[81,82]}
optsfrom: COLOR_PARTS

C3. Now we want to get a sense for how and where you encounter flowers. Take a moment to think about a typical day. Where do you typically enjoy flowers?
[Select All] Options: At work inside, At work outside, At home inside, At home outside, Other places

In this example, C3 uses the new crosslist AREAS, which combines places and locations using the crosslists tag to make a new nested list.

The crosslist uses include syntax, with the PLACE list to call in the specific IDs needed, and combines that with the options defined at the SIDE list to create the option set for the question.

Again, the crosslistidseparator  tag is used to remove the default underscore from the option ID. The crosslisttextseparator  tag is used to remove the default comma from the option text.

Tip! The text displayed in the various reports, both on-screen and in exported files, is derived from the question and answer option text. To change this text, use the desc tag for questions or the desc decorator for options.

 
setlist: SIDE 
1. inside 
2. outside 

setlist: AREAS 
crosslists: PLACE [1,2], SIDE
crosslistidseparator: 
crosslisttextseparator: 

C3. Now we want to get a sense for where you encounter flowers. Take a moment to think about a typical day. Where do you typically enjoy flowers?
desc: Where flowers are encountered 
type: checkbox
optsfrom: AREAS
97. Other places

Element decorators

The examples in this section use tags from the setlist widget, plus many list conventions covered in Lists. 

Lists offer a means to reuse information instead of rewriting it each time it's needed. This not only helps minimize the risk of errors but also paves the way for streamlining the survey source code significantly.

Let's take a closer look at how lists let us define data and use elements to modify question defaults. First a quick review of different areas.

An option data decorator, or option data, is added to an option on a list with double curly brackets '{{DTXT: something here}}'. The info added as option data can be used with questions, tables, blocks, and loops.

  • For questions and tables, option data is referenced with square brackets as '[DTXT]', in a similar fashion to '[id]' and '[text]'.
  • For blocks, it is referenced with the block sigil as '%%DTXT%%', similar to using '%%ID%%' and '%%TEXT%%' in blocks.
  • For loops, it's referenced with tildes as '~DTXT~', similar to using '~id~' and '~text~'.

List or element decorators are defined with single curly brackets. There are a handful to choose from, each providing a different function. Let's quickly review some of the more common decorators:

  • {text: } is used to override the option text.
  • {desc: } is used to override the report text.
  • {explain: } is used to add hover text ("tooltips") to your options.
  • An {if } condition is used to add logic.
  • {weight: } is commonly used to add priority to selections for quotas and the selectby tag.
Questionnaire Content Discussion Details Coded SPL

C4. Pick the flowers you want to use.
[Select All] Options: SHOW 12 FLOWERS AS FOLLOWS: Flower [insert number] is a [insert name]

 

Review the element decorators.

C4 creates a statement for each of the 12 options from the FLOWERS list using default option data, the '[id]' and '[text]' iterators (placeholders). This question will have options that read 'Flower 1 is a California Poppy,' 'Flower 2 is a Desert Mallow,' 'Flower 3 is a Marigold' and so on for each one.

 
C4. Pick the flowers you want to use.
type: checkbox
optsfrom: FLOWERS -[96] {text: Flower [id] is a [text]}

C4A. Which tree flowers are you familiar with?
[Select All] Options:
I know about apple tree flowers [show image]
I know about cherry tree flowers [show image]
I know about orange tree flowers [show image]
I know about peach tree flowers [show image]
I know about pear tree flowers [show image]
I know about plum tree flowers [show image]

C4A creates a statement for each option from TREE_FLOWERS; in addition, the image will show under the statement. Here we leverage image tags and decorators to avoid manually writing out the HTML for each image. The size and placement of the image can be managed using additional decorators as detailed in the Image tags article.

The images used here can be found at the bottom of this article.

Note: To upload these images, follow the steps in the Adding images to a survey article.

 
set list: TREE_FLOWERS
1. apple {image: apple.jpg}
2. cherry {image: cherry.jpg}
3. orange {image: orange.jpg}
4. peach {image: peach.jpg}
5. pear {image: pear.jpg}
6. plum {image: plum.jpg}

C4A. Which tree flowers are you familiar with?
type: checkbox
optsfrom: TREE_FLOWERS {text: I know about [text] tree flowers}
option images: y

Previous/Next

Create tables tutorial/Create logic tutorial

Related to

Related articles

Comments

0 comments

Article is closed for comments.