Create options tutorial (r9)

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.

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.

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.

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.

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.

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.

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.

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).

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.

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_r9_intro code, replace C1A from earlier in this section with this crosslist example.

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.

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.

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.