In this tutorial, we will discuss some advanced customizations for merge codes, including formatting and transforming data in merge codes and replacing strings within merge codes. Let's begin by learning a little more about how merge codes work.
The Basic Structure of a Merge Code
Below is a very common Merge Code which will be used as example to discuss the various parts of a Merge Code:
[question("option value"), id="2"]All Merge Codes follow this similar structure. Merge Codes always start and end in brackets [ ] and contain a section in parentheses surrounding double quotation marks. Finally, all the major areas of the Merge Code (covered below) should always be written in all lowercase letters.
Important Note on Styling Merge Codes
As mentioned above, merge codes have the following default format:
[question("option value"), id="2"]At times, you may need to customize the look & feel of a merge code, or perhaps link the merge code to a url. Both of these actions introduce HTML code around the merge code (behind the scenes).
When HTML is introduced into a merge code, Alchemer will convert any double quotes in the merge code to single quotes (on Save) to maintain the merge code functionality and avoid potentially compromising the HTML behind the scenes.
The result will convert the above merge code to the below merge code (note that double quotes have been replaced with single quotes):
[question('option value'), id='2']This single-quote version of the merge code will function correctly - no need to try to convert it back to the default!
Now, let's break down each part of the Merge Code:
Merge Code Category
The bolded text below immediately following the opening bracket and ending before the opening parenthesis is the Merge Code category and defines the available properties (discussed in the next section).
[question("option value"), id="2"]There are 9 different categories:
- Question: Dynamically pull and display data from questions or actions.
- Quiz: Quiz score merge codes dynamically pull and display about how the respondent did.
- Page: Access information about a specific page of the survey.
- Invite: Pull data about a specific email or sms campaign invitation or data unique to that invitation.
- Contact: Pull contact data from the specific contact; these work for either email invitation contacts, sms invitation contacts, or contacts within an account contact list.
- URL: Pull and displaying query string values.
- Survey: Pull data about a specific response or overall survey.
- System: Pull metadata about a survey response or from the Alchemer system
- Account: Pull Data about your Alchemer account.
Merge Code Property
The bolded text below is the property, found between the double quotation marks within the parenthesis. Available properties are determined by the Merge Code category and like the category, they must be all lowercase. If you think of a category as the city in a mailing address, then the property is the street address.
[question("option value"), id="2"]Merge Code Attributes
The bolded text below is an attribute of the Merge Code and is matched to the specific property. If the property is the street address of a mailing address, the attributes are the house/apartment/suite number. However, unlike the category and property, you can have none or multiple attributes, all separated by commas in the latter case. Attributes are always paired as an identifier and its value. In the example above, id is the identifier and the value is inside double quotes. They are connected by an equals sign.
[question("option value"), id="2"]The id attribute is the most common Merge Code attribute. It indicates the element that you are pulling data from. This is most often the question ID.
Other Attributes
- format - format a date in Merge Code - applies to [system("date")] merge code only. Does not apply to data collected via the Date question type.
- stringformat - format a data string in a Merge Code.
- numberformat - round to a specified number of decimal places
- delimiter - specify the delimiter for multi-value questions
- finaldelimiter - specify the last delimiter for multi-value questions
- questiondelimiter - specify the delimiter for sub-questions
See the Format and Transform Data in Merge Codes section of this tutorial below to learn more.
- questionpipe
- pagepipe
To learn more go to Merge Codes for Pulling Data from Piped Questions.
Formatting and Transforming Data in Merge Codes
There are several merge code attributes that allow you to format and/or transform data within merge codes. Including case, format, stringformat, numberformat, delimiter and more. Below we cover each attribute and demonstrate how to use it to format or transform data.
default
The default attribute, in bold text below, can be used to populate an answer when a question value isn't present.
[question("value"),id="3",default="anything"]case
The case attribute, in bold text below, can be used to take the string pulled by the Merge Code and format the casing.
[question("value"),id="3",case="lower"]The casing options are:
- lower - all alphabetic characters are converted to lowercase
- upper - all alphabetic characters are converted to uppercase
- proper - all alphabetic characters are converted to titlecase
format
The format attribute, in bold text below, is used to transform the date data being pulled by the Merge Code into different formats. This attribute applies to the [system("date")] merge code only. It does not apply to data collected via the Date question type.
[system("date"),format="Y-m-d H:i:s"]
[system("date"),format="Y-m-d"]Depending on how you'd like to format the date, you'll need to use different format characters. The format attribute uses basic PHP format parameters. The default format for dates in Alchemer is MM/DD/YYYY but can be altered with the format attribute. If the date 11-06-2012 is being pulled by the Merge Code, then the following characters will format as follows:
- M - The written version of the Month: Nov
- m - The number of the month: 11
- D - The day of the week it falls on: Tue
- days return in three character format
- d - The number of the date: 06
- Y - The full four digits of the year: 2012
- y: The last two digits of the year: 12
- H: 24-hour format of an hour with leading zeros (Eastern Time): 12
- h: 12-hour format of an hour with leading zeros (Eastern time): 01
- i: The two digit minute with leading zero: 25
- s: The two digit second with leading zero: 06
These are case sensitive. To learn more about what other format characters output, please visit PHP.net
Examples:
- [system("date"),format="M d Y"] will output: Nov 06 2012
- [system("date"),format="Y/d/m"] will output: 2012/06/11
stringformat
The stringformat attribute, in bold text below, allows you to format a string of data being pulled by a Merge Code.
[question("value"), id="3",stringformat="%010s"]The above example will take the value entered in question id 3 and will output a 10 character string with zero-padding.
Some other useful string formats:
- %s - standard string format
- %s more text - Add text to precede or follow a string
- %.10s - cut off after 10 characters
This attribute uses the PHP sprintf function. This is only the surface of what you can do with this function, to learn more visit PHP.net.
numberformat
The numberformat attribute, in bold text below, allows you to format the number of decimals for the number being pulled by a Merge Code. Numbers will be rounded to the specified decimal.
[question("value") id="3",numberformat="2"]urlencode
The urlencode attribute, in bold text below, will urlencode the data in the merge code. This is useful to anyone that needs to include a URL in an email based on a response.
[question("value"), id="3",urlencode="true"]delimiter
The delimiter attribute, in bold text below, allows you to specify the delimiter for piped values pulled by a Merge Code.
[question("value"), id="3",delimiter=";"]Example:
Output the answer from a Multi Select question (such as a checkbox) as a list by setting the delimiter attribute equal to "<li>": [question("value"), id="3", delimiter="<li>"].
If a respondent answers options A and B, the output will be:
- A
- B
Note: When using the <li> delimiter option in a question title or text element, you'll need to turn off the HTML editor and wrap your merge code in the HTML for a bulleted list (see below) in order for this to work.
<ul>
<li>[question("value"), id="2", delimiter="</li>
<li>"]
</ul>- The <li> delimiter merge code can only be added to a brand new element (question title, text element).
- Any edits to the <li> delimiter merge code after the initial Save will result in the merge code and associated HTML being cleaned. This will effectively break the merge code. If you need to make edits, you will need to create a brand new element and paste the edited merge code there.
Example:
Output the answer from a Multi Select question semi-colon separated or use another character if you wish! Set the delimiter attribute equal to ";": [question("value"), id="3", delimiter=";"].
If a person answers options A and B, the output will be:
A;B
finaldelimiter
The finaldelimiter attribute, in bold text below, allows you to specify the delimiter between the last two piped values pulled by a Merge Code.
[question("value"), id="3",finaldelimiter=" or, "]Example:
The above Merge Code will pipe the answers from a Multi Select question (which are delimited with a comma by default) and add an " or, " before the last piped value.
If a respondent selects all options a through e the output will be:
a, b, c, d, or, e
questiondelimiter
The question delimiter attribute, in bold text below, can be used to specify the delimiter between sub-questions when using the Merge Code for the overall question. For example, Custom Groups, Contact Forms, and Table questions.
[question("value"),id="3",questiondelimiter=";"]Example:
The above Merge Code will pipe the answers from a List of Textboxes (which are delimited by a comma by default) and separate the values with semicolons.
Replacing Strings within Merge Codes
When using Merge Codes to pull answers from previous questions to use later in your survey, you can find and replace strings of text.
Here is an example:
[question("option value"), id="3", replace="string to find", with="string to replace"]Let's say you want to refer to a previous answer but in a different format or tense. In the below example survey, the respondent answers "I live in the US". That's what we call the 'string to find'.
The ID in the above merge code is the question ID. Question IDs can be enabled under the View Settings link in the upper right of the survey Build tab.
- To do so, click View Settings and check the Question IDs option.
- Once enabled, question ID numbers will be visible directly on the Build tab below each question.
- In the subsequent question, we'd like to refer to this answer using the merge code. To do so, we replace the phrase "I live in the US" with just "in the US" to complete the sentence:[question("option value"), id="2", replace="I live in the US", with="in the US"]
Test it out in this survey:
http://survey.alchemer.com/s3/1307950/replace
If you have multiple string values in a previous question that you want to transform in a follow up question, you will need a merge code for each option.
For example, in the following question we ask respondents what state they live in:
We will then want to transform CO to Colorado and AZ to Arizona in a follow-up question. To do so, we need to format the merge codes as follows:
[question("option value"), id="4", option="10001", replace="CO", with="Colorado"][question("option value"), id="4", option="10002", replace="AZ", with="Arizona"]
Note that each answer option that will be replaced requires its own dedicated merge code. The answer option is specified in the merge code via the option="10001" parameter. You can use the merge code helper in the follow-up question to automatically reference specific answer options.
To learn more visit our Merge Codes Tutorial!
