Skip to main content

Search

Blocks

  • Updated

Blocks allow programmers to define content that can be reused, or "looped," throughout a survey, with references similar to a mail merge. They’re typically used to ask the same set of questions for multiple items in a predefined list.

1. Which of the following brands are you aware of?
type: checkbox
1. Coke
2. Pepsi
3. RC Cola
4. TAB
99. None of these {exclusive: y}

block: <<BLK_Q2

2_%%ID%%. How did you first hear about %%TEXT%%?
type: textbox

BLK_Q2
list: Q1-[99]

Tip! For simpler content and question structures, consider using loops for a more efficient setup.

Details

  • To create a block, create the content and add in the substitutions as needed. Surround the content with the block widget and heredoc. Then, use the list tag to specify the list (or spreadsheet) of elements for which the question(s) will be repeated. Derived lists and question label shorthand are also supported.
  • To perform content substitutions, reference the option data by surrounding them in double percent symbols ('%%'). Option IDs can be referenced as '%%ID%%' and option text can be referenced as '%%TEXT%%'. 
  • To use option data decorators in blocks, surround the label with '%%'. For example, an option data decorator with the label 'SHORT' would be programmed as '%%SHORT%%' within a question, option, or row text.
  • All content in the group will repeat for each item in the list unless restricted by condition logic.
  • The list tag accepts inclusion/exclusion syntax, and condition decorators can be included inline as needed (e.g., list: LIST_NAME -[99] {if anyChecked($Q10R[id],1)}

Additional tags

Use the following tags to modify the default behavior and presentation of blocks.

Tag Description

autopage

(alias ap)

 For use with questions inside a block. Including autopage: n will remove page breaks between questions within each block iteration, but there will still be a page break after each iteration of the block. Accepts 'y' and 'n' inputs.
bare bare: y removes HTML markup surrounding blocks. Accepts 'y' and 'n' inputs.
freeform

freeform: y permits certain types of advanced substitutions which otherwise may not parse. Accepts 'y' and 'n' inputs.

Including freeform: y prevents the creation of the rollup (summary) variable for reports and can modify the expected data output. It should be used only as a final resort after trying rollup: n.
inline

inline: y overrides any in-block page breaks, showing all question iterations on the same page. Accepts 'y' and 'n' inputs.

%% renderif

(alias %% if)

Controls the rendering of block content based on a specified condition.

To apply within a block, use %% render if followed by the condition. For nested blocks with a sigil, replace '%' with the sigil (e.g., xx render if).
rollup

rollup: n explicitly stops the build of the rollup (summary) variable. This is useful when questions within the block vary in list options or question types.

Try rollup: n before freeform: y to see if the block will parse and function as expected.
sigil Substitutes a different character for '%' symbol to identify substitutions. This is required for nested blocks (blocks within blocks).

Additional examples

Creating nested blocks

Blocks within other blocks ("nested" blocks) are powerful tools which require the definition of custom sigils on the inner block. In the example below, Q6 is in a nested block (Q6BLK) within the Q5BLK and uses the sigil 'xx' in place of the '%%' used in the Q5BLK. Notice, the sigil is defined on the nested block's closing heredoc at 'BLK_Q6'.

Note that heredocs (e.g., block: <<BLK_Q6) cannot contain block substitutions.

Placing an 'order' decorator on the 'list' tag

The list tag behaves similarly to listcall tags like optsfrom. To include ordering instructions, add an order decorator enclosed in square brackets ('[ ]') after the list name. Then, specify the order as needed.

setlist: 20LIST
1. Apple
2. Toyota
3. Coca-Cola

block: <<END

20_%%ID%%. Use one word to describe %%TEXT%%.
type: text
size: 12

END
list: 20LIST [order: [*]]

Using option data in blocks

Option data can be piped into blocks just like option text and IDs. Simply specify the option data label as '%%OPTION_LABEL%%'. Here the option decorator 'ALT' is applied to each list element. This decorator is then referenced in the block by wrapping the decorator name with the double %.

Conditioning blocks with '%% render if'

The %% render if tag lets you set conditions to skip specific iterations within a block. When applied, these iterations are not built, so the questions are neither displayed to respondents nor included in reports or exports.

Varying the number of list options with 'rollup: n'

In the example below, each item in the PRODUCTS list has unique options for the follow-up block question QPROD_%%ID%%_RATING. Depending on the respondent’s selections in Q1, different options appear for each product. When iterations of questions within a block vary in a way that alters the reporting output for any iteration, such as this example, rollup: n should be applied. This ensures the block parses correctly by avoiding incompatible summary data in the reports.

Tip! If a block prevents your survey from parsing (being built), try the following:

  1. Try adding rollup: n to the block.
  2. If rollup: n doesn't work, try freeform: y.
  3. If freeform: y doesn't work, please contact Support for assistance.

Related to

Related articles

Comments

0 comments

Please sign in to leave a comment.