Concatenate

The purpose of a concatenate is to create a variable reference or string composed of different elements, usually with one that is dynamic. Concatenates are streamlined ways of creating references that otherwise would require superfluous variables with no reporting value and/or carry a heavy system resource penalty. This page contains examples of the most common use-cases for concatenates.

Syntax

Basic

A basic concatenate is formatted thus:

{ Element 1 . Element 2 . Element N }

String vs. expressions

The curly braces indicate that the text within is meant to be concatenated. Each element is separated by a period. To render an element as-written, put it inside quotes. To interpolate an expression or variable, leave it bare:

{ "2*2 = " . 2*2 }

This concatenate renders as "2 * 2 = 4".

Within freetext

To create a concatenate within freetext, wrap it in starred brackets, which indicates Perl code:

[* { "This concatenate lives in freetext " . 2*2 . "ever"} *]

Examples

Creating a variable reference with a concatenate

Survey Programmers (SPs) frequently need to pull information out of prior respondent answers for pipes or to build logical conditions for path branching. Sometimes, this is as easy as referencing a prior question:

$Q1_text, $Q1, etc.

In other circumstances, the reference isn't as straight forward. Suppose that the requirements demand that the survey pipes in a prior table response, but only if that response is the highest value as compared to other responses in that table. Consider the following example, where the variable QHIGHKIDAGE stores the highest number entered in T1 by utilizing a concatenate.

setlist: KIDS
1. Kid 1
2. Kid 2
3. Kid 3
 
start table: 1
intro: Please indicate the age of each of your children under the age of 18.
rowsfrom: KIDS
type: text
size: 3
datatype: whole
end table
 
OLDEST. Oldest child
type: radio
selectby: weight
optsfrom: KIDS  {weight: $Q1R[id]}

HIGHKIDAGE. Age of oldest child
type: text
invisible: y
cvalue: ${"Q1R".$QOLDEST}

First, QOLDEST uses a weight input on the selectby to determine which one of the three rows has the highest number in it. The answer to QHIGHKIDAGE will need to be $Q1R"row with highest number". This variable is built right on the cvalue line like so:

1. The dollar sign '$' for the variable that we are creating is outside of the { }.
2. The rest is inside { }, which indicates that we want the app to do some work to build the variable.
3. Inside we put "Q1R" using quotes, because we want to use that exact text.
4. The . means to concatenate (add elements together).
5. Then we have $QOLDEST, which is not in quotes, because we don't want that exact text to be part of the variable; instead we want it to figure out the value of QOLDEST and use that for the variable.

Creating a set_text with a concatenate

To create a variable set text reference, treat the "__" set text sigils as strings:

settext: TEXT1
text: This is a set text
 
[* "__TEXT" . 1*1 . "__" *]

The system will render this text as a reference to the set text TEXT1: __TEXT1__ and so display the contents of that set text.

In the following example, the response option at Q1 is used to drive the set text used on the following page.

1. What industry?
type: radio
1. Farming
2. Social Services
3. Entertainment
 
set text: IND1
text: <<END
Very long option-specific HTML table text 
END

set text: IND2
text: <<END
Very long option-specific HTML table text
END

set text: IND3
text: <<END
Very long option-specific HTML table text
END
 
new page
 
[* "__IND" . $Q1 . "__" *]

Imagine that these set texts contained a lot of data: very long HTML display tables, for example. While it is technically possible to collapse long HTML code into a single line such that it could go inside of an element decorator, doing so is tedious, cumbersome, and makes the code nearly impossible to read or quickly edit. A set text is far better choice for storing table code.

Using fetch_cell with sheets

The fetch_cell tag may be utilized to limit the list of proposed items by using a dynamic reference. Let us propose that there are four potential categories, and each category has specific brands where not every brand is shown for all categories.

In the below example, the sheet 'brandlist' has categories labeled "cat1" through "cat4", filled with 1's and 0's such that a '1' means this brand is eligible for that category, and a '0' means it is not. We can then utilize fetch_cell to concatenate the string 'cat' and the value of $QCATEGORY to look up all brands in the sheet where the 'cat1' column is 1 if $QCATEGORY=1, all brands where the 'cat2' column is 1 if $QCATEGORY=2, and so on, thusly.

Click here to download the 'brandlist' sheet.

set list: BRANDS
order: [*]
optsfrom: mysurvey.brandlist

CATEGORY. Please select your category
type: radio
1. Tools
2. Electronics
3. Recreation
4. Apparel

1. Select your brands
type: checkbox
optsfrom: BRANDS {if (fetch_cell( name=> 'mysurvey.brandlist', row => [id], column => 'cat'.$QCATEGORY )) ==1}

2. Now with customized text
type: radio
optsfrom: BRANDS {if (fetch_cell( name=> 'mysurvey.brandlist', row => [id], column => 'cat'.$QCATEGORY )) ==1}  {text: [* fetch_cell( name=> 'mysurvey.brandlist', row => [id], column => $QCATEGORY.'text' ) *]}

Now let us propose that each brand will actually need to display different text depending on which category is shown. For example, imagine a beverages survey where "Coke" might display if the user is a soda drinker, but "Coke Zero" might display if low-calorie items are preferred in a previous question. In the brandlist sheet, we have a series of columns called "1text", "2text", etc., to have differential text display for each brand depending on the $QCATEGORY value assigned.

In the above example, we are using fetch_cell twice. The first call - the "if statement" - is looking at the values of columns "cat1" through "cat4", depending on the respondent's $QCATEGORY value. So if $QCATEGORY=1, the respondent sees all brands where "cat1" equals '1' in the sheet. The second call - the "text call" - is showing the text in the column "1text" through "4text" depending on which $QCATEGORY value the respondent has. Note that the text call's fetch_cell reference is wrapped in a Perl interpolation wrapper " [* *] ", which will interpolate the fetch_cell call and render the text to the page.

# Do use!
$QCATEGORY.'string'
'string'.$QCATEGORY

# Don't use!
$QCATEGORY.''.'string'
$QCATEGORY.'_string'