Using decorators in sheets

Sheets are commonly used as data sources within the platform and can function like lists. Each sheet must include at least an 'id' and a 'text' column.

Details

• The first column must be labeled 'id', and each row must have a unique value in the 'id' column.
• The second column should be labeled 'text' to serve as the option text for each item.
• Additional columns can function as element decorators such as 'weight', 'explain', 'desc', 'condition', and 'autoother'. Decorator column headers are "reserved terms" and require specific inputs if used as headers in a survey sheet.
• Spaces are not allowed in column header names. Use an underscore when needed. For example, the decorator 'collection header' can be written as 'collection_header' instead.
• All column labels must be unique.

Comparing sheets to lists

When creating a sheet, it's helpful to think of a sheets as similar to a set list. Each row represents an item in the list, and each column provides data points for the row. The following set list and sheet are equivalent to each other:

set list: colors
10. Primary   {collection header: y}
11. Red
12. Yellow
13. Blue
20. Secondary {collection header: y}
21. Orange
22. Purple
23. Green

Referencing decorators from sheets

Once a sheet is defined, decorator data can be used in survey programming.

First, define the sheet and invoke the sheet on the listcall (e.g., optsfrom) as explained in Using sheets in survey programming. Depending on the decorator, additional steps may be needed.

• Automatically applied decorators: Decorators like collection_header and randomize manage option ordering and organization automatically. Conditions and translation instructions are also applied without additional steps.
• Explicitly referenced decorators: For decorators like image, explicitly include image: y in the survey code to enable images for each relevant question.
• The autoother decorator functions like a combination of these two scenarios. To create an autoother text field, add a 'y' for the option in the "autoother" column. Any additional autoother parameters should be added locally as tags to individual questions or globally to the set defaults widget.

Additional examples

For the following examples, assume the local survey sheet 'miscexamples' has been defined in the survey source.

definesheet: survey_id_containing_sheet.miscexamples

autoother

1. Which shoe brands have you purchased for running in the past year?
type: checkbox
optsfrom: miscexamples
autoother placeholder: Specify
autoother size: 12

image

1. Which type of apple is your favorite?
type: radio
optsfrom: miscexamples {images: y}

condition

translate

Collection headers and order

Option data

21. Which of the following teams have animals in their names?
type: checkbox
optsfrom: miscexamples {text: [SHORT]}

22. Of the following West Coast teams, which would you like to see play?
type: checkbox
optsfrom: miscexamples [if ([WC])]