Using decorators in spreadsheets (r9)

Spreadsheets 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. Additional columns can serve as element decorators such as 'weight', 'explain', 'desc', 'condition', among others.

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 column names can then act as decorators. Decorator column headers (e.g., 'collection_header') 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 spreadsheets to lists

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

setlist: 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 spreadsheets

Once a spreadsheet 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 spreadsheets 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.

Additional examples

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

definesheet: survey_id_containing_sheet.miscexamples

image

1. Show images here.
type: checkbox
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])]