Version Notice: This article covers features debuted in our r9/IS Pro platform.
Spreadsheets are frequently used as data sources that are hosted in the platform and can function like lists. Each sheet should include an 'id' and 'text' column, but Survey Programmers (SPs) may also include element decorators such as 'weight', 'explain', 'desc', 'condition', among others. SPs should note that these are considered "reserved terms," and will require specific inputs if used as headers in a survey sheet. To see a detailed list of IntelliSurvey's element decorators and examples of how to apply them, read Element decorators.
Tip! Option data decorators use named decorators to define custom data which can also be used as sheet column headings. For information, see Option data decorators.
Comparing spreadsheets to lists
When creating a spreadsheet, it's helpful to think of sheets as similar to setlists. Each row of the sheet is an item in the list, and each defined column is a data point for each row. The following setlist and sheet are equivalent to each other:
| SPL | Sheet equivalent | |||||||||||||||||||||||||||
setlist: colors
10. Primary {collection header: y}
11. Red
|
|
The first column must be labeled 'id', and each row must have a unique value in the 'id' column. The column labels must also be unique. The second column should be labeled 'text' to serve as the option text for each item. Additional column names can then act as decorators.
Note: 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.
Referencing decorators from spreadsheets
Decorator data (both element decorators and option data decorators) stored in spreadsheets can be referenced 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.
Next, depending on the decorator, additional steps may be needed to use the data from the spreadsheet in a survey question. For example, decorators that describe ordering and organization such as collection_header and randomize automatically organize and order the options in the survey with no further action needed. All conditions and translation instructions are automatically applied as well. However, for decorators like image, you need to include image: y in the survey code to enable images for each relevant question. Specific examples for referencing decorators from spreadsheets in survey code are shown below.
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
When the image decorator is included in a sheet, the image decorator or option images tag should also be present at all relevant questions turn the image display "on."
| Sheet | SPL needed | ||||||||||||
|
1. Show images here. |
condition
A list of conditions defined in a sheet are automatically applied to the survey. Notice, the 'if' is not needed. Below is an example of how to include condition syntax in a sheet. Perl, and other more complex programming syntax is also supported.
| Sheet | ||||||||||||
|
translate
By default, items in a sheet are not translated unless the translate decorator provides additional instructions. The translate decorator can support 'y'/'n' inputs as well as language codes, just like the translate tag.
| Sheet | ||||||||||||||||||
|
Collection headers and order
In addition to spreadsheets supporting collection headers, decorators that define order placement and randomization can also be used. In the example below, the 'collection_header' column is present, flagging that 'Mass Merchandisers', 'Pet Stores', and 'Brick and Mortar's website' are headers. Then, within each collection, the 'order' and 'alphabetize' columns define the organization of the items within each collection. The Mass Merchandisers group will fully randomize items 11 and 12. Meanwhile, the Pet Store collection will keep options 21 and 22 together, but will randomize their order, and those two options will be randomly presented among the four options in the group. Lastly, the Brick and Mortar's website collection will be displayed in alphabetical order.
| Sheet | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Tip! Sheets will automatically organize all content in incrementing, sequential order based on their value in the 'id' column. Take this into consideration when numbering your collection headers so that they remain visually organized as the first item in their respective group.
Option data
Option data decorators can also be used as sheet column headings, and the information stored in those columns can be utilized in the same way as when option data is placed inline with the option in the survey code.
Let's look at the example sheet below. To display the teams' "short" name, use the text decorator at the listcall, and use square brackets to pull in the data found in the 'SHORT' column. To apply a condition, such as only show the teams flagged for 'WC', use an "if statement" with square brackets to only filter in where WC = '1'.
| Sheet | SPL needed | ||||||||||||||||||||||||||||||
|
21. Which of the following teams have animals in their names? |
Tip! Remember to wrap square brackets with parentheses, for example '([WC])', if your spreadsheet has blanks in the column being referenced.
Comments
0 comments
Please sign in to leave a comment.