Skip to main content

Search

Element decorators

  • Updated

Element decorators are defined with curly brackets and text. Decorators follow a list element or question option and serve a multitude of purposes. They may inform the software how to display text or images, alter descriptions in reports, qualify or terminate the respondent, provide an automatic "other" field (autoother), or simply store arbitrary data.

Tip! Decorators can be used as column headers in spreadsheets. Each sheet should include a 'text' column, but SPs may also include decorators such as 'weight', 'explain', 'desc', 'image', or 'condition'. For more information on formatting spreadsheets, see Creating and editing survey spreadsheets.

Common element decorators

The table below lists commonly used decorators and their basic descriptions.

Instruction name Description Common format(s)
anchor

Keeps the option in its ordered position while the other options are randomized. Must be used in concert with either the randomize or order tags; frequently used with "Other" and "Exclusive" options.

{anchor: y}

97. Other {autoother: y} {anchor: y}
autoother

Specifies parameters to modify an autoother text field. The text field can either be triggered by adding multiple, consecutive underscores to an option, e.g., 97. Other ________, or by using the autoother: y decorator, e.g., 97. Other {autoother: y}.

Additional parameters are available to modify the text field's size, placeholder, datatype, etc.

{ autoother size: 10 }

{ autoother placeholder: 'Specify' }

{ autoother: y; placeholder: Specify; size: 10}

 
category

For use with collection headers; specifies which collection (or "category") the element should be included with, allowing for an option to be out of sequence with its parent collection. Specify the collection's option ID as input.

Aliases include collection or parent.

{category: 1} 
collection header

New for r9. When placed next to a list item, the list option becomes a header for a collection of items in the list, much like a category label.

Accepts the alias header.

{ collection header: y }

{ header: y }
comment Places comments after an option that will not be seen by respondents, but will provide better documentation for the survey code. { # COMMENT TEXT }
condition

Specifies a condition that must be met in order for the element to be included in a question's options list. If the statement returns true, the option is rendered/included. If it is false, the option is hidden/not included.

Although the condition decorator can be use in a more traditional sense -- e.g., {condition: anyChecked($QX,1,2)} -- we recommend instead using a simple "if statement" instead as shown in the Common format column.

{ if CONDITION }
desc Specifies a custom description for an option in the reports. { desc: VALUE }
exclusive

For use with multi-select/checkbox questions; specifies that an option cannot be selected with other options. If other options have been previously selected, they will automatically be deselected.

If an option cannot be selected with any other options, set to 'y'; if the option is only exclusive of another option (or set of options), specify the ID(s) of the other option(s).

Exclusive of all other options

{ exclusive: y }

Exclusive of options 4 & 5

{ exclusive: 4,5 }
explain Creates an "i" icon for more information and specifies to display helpful text when a cursor is positioned over the icon.  { explain: text goes here }
goto Specifies a label, question, table, or group to immediately send a respondent to if the option is selected. { goto: LABEL }
image

For use with lists and spreadsheets; specifies an image file to associate with an option. Accepts various file types as input, such as .jpg/.jpeg, .png, and animated .gif files. 

To use with a spreadsheet, add an 'image' column to the sheet, and include the names of all associated image files in this column.

Additional parameters are available to override the images' default display formatting and can be included in separate sets of curly brackets.

{ image: filename.jpg }

To apply additional image formatting parameters, include each parameter in a separate set of curly brackets as shown below.

{image: filename.jpg} {image max height: 200} {image max width: 150} {image placement: below}
option data Specifies an arbitrary data label that can be placed after an option for later use in a list decorator or a block. Option data decorators require double curly brackets. {{ NAME: VALUE }}
qualify

Placed next to an inline list option or setlist option and qualifies respondents who select this option. Conversely, this also terminates respondents that select only non-qualifying options in the list.

This is the opposite of the term decorator.

 { qualify: y}
setvalue Specifies the value that a question will receive if an option is selected.

{ set question: QUESTION value: VALUE }

{ set question: QUESTION value: VALUE condition: CONDITION }

{ set question: QUESTION value: VALUE option: 0 OR 1 }

{ set question: QUESTION value: VALUE option: 0 OR 1 condition: CONDITION }
term

Placed next to an inline list option or setlist option and terminates any respondents who select this option. 

This is the opposite of the qualify decorator.

{ term: y }
text

Applied at the question level to modify or augment the text coming from all elements of a list.

Can also replace the termtext tag when used with termif or qualifyif in a single-line definition, e.g., term if: anyChecked($Q4,1) {text: From the Northeast}

{ text: Item #[id] }

{ text: You say you've tried [text] }
translate Specifies whether an option will be listed in the Excel output used for translations. The default is 'y'; change to 'n' to exclude the option from all translations. You can also specify the applicable languages by listing the language code(s).

{ translate: y }

{ translate: n }

{ translate: ger } 
weight Specifies the weight of the option if used with the selectby tag or with a quota.

{ weight: VALUE }

Related to

Related articles

Comments

0 comments

Please sign in to leave a comment.