How to Use Merge Codes (Simple Piping)

Merge Codes Available to All Account Levels. More Complex Piping Available at Professional and Above.

Merge codes are specially formatted text that can be used throughout the application to dynamically show content related to your survey, account, invitation, etc. However, to use merge codes does not require a large amount of studying or practice; 95% of the time you only need to use one thing, the Merge Code Helper:

When editing any question, descriptive text, and Hidden Value action you have the opportunity to use the Merge Code helper by clicking the Insert Merge Code link in the bottom right, bringing up the Select a Merge Code dropdown menu:

By selecting an item from the dropdown menu, the merge code for that particular item will be visible for you to click (insert at your cursor) or copy & paste into the textbox above.

This is the simplest method of working with merge codes as well as a great starting place before making any modifications (rather than writing a merge code from scratch). For advanced users who are looking for more flexibility and options, an amazing world awaits you...

The Basic Structure of a Merge Code

Below is a very commonly formatted merge code which will be used as example to break down all the different parts of a merge code:

[question("option value"), id="2"]

All merge codes follow this similar structure, always starting and ending in square brackets [ ] and containing a section in parenthesis surrounding double quotation marks (" "). Finally, all the major areas of the merge code (covered below) should always be written in all lowercase letters. Let's breakdown each part of the merge code.

Merge Code Category

[question("option value"), id="2"]

The highlighted section above is the beginning of the merge code, immediately following the opening square bracket and ending before the opening parenthesis. This is the merge code category and defines not only the general area that this merge code will represent, but it also defines the possible properties that are available (discussed in the next section). There are 9 different categories:

• question: From questions or actions within the survey itself
• page: Accessing information about that page of the survey; used for page piping
• invite: Data about a specific email campaign invitation or data unique to that invitation
• contact: Data from the specific contact; related to email invitation campaigns
• url: Displaying query string values based on the variable name
• survey: Top level survey information about the specific response or overall survey
• system: Meta data about the respondent or SurveyGizmo's system
• account: Data about your SurveyGizmo account, configured under Account Settings
• template*: Survey and report theme

* The template category will not be covered in this tutorial as it has its own separate tutorial due to its advanced integration, uses, and syntax.

Merge Code Property

[question("option value"), id="2"]

The highlighted section above is the property, found between the double quotation marks within the parenthesis. What can be used as a property is limited to what is made available within the merge code category and like the category, must be all lowercase text. If you think of a category as the city in a mailing address, then the property is the street address.

Merge Code Attributes

[question("option value"), id="2"]

The highlighted section above 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:

id="2"

In the example above, 'id' is the identifier and the value is inside double quotation marks. They are connected by an equals sign.

The following survey invitation link will demonstrate many different merge codes in action:
http://s-a18667-i.sgizmo.com/s3/i-15555813-85409/

Properties Available in Each Category

Within each category there are specific properties available. Each possible property will be listed and their description below.

Question Category

option title

title

[question("option title"), id="2"]

Both are interchangeable and will display the title of the answer given. This is the answer title that is visible to the respondent. You must include the id attribute to specify which question id you are retrieving.

option value

value

[question("option value"), id="2"]

Both are interchangeable and will display the reporting value of the answer given. This is the answer value that is not visible to the respondent and may be set differently than the title. You must include the id attribute to specify which question id you are retrieving.

piped title

[question("piped title")]

This special merge code property is only used within a question or descriptive text that is piped. It will display the answer title of the current iteration of the piped question. This is the answer title that is visible to the respondent. This property does not require any attributes.

piped value

[question("piped value")]

This special merge code property is only used within a question or descriptive text that is piped. It will display the reporting value of the current iteration of the piped question. This is the answer value that is not visible to the respondent and may be set differently than the title. This property does not require any attributes.

answer count

[question("answer count"), id="2"]

Useful with multiple selection questions such as a checkbox question, this property will display the total count of answers that were selected in the question. You must include the id attribute to specify which question id you are retrieving.

question number

[question("question number"), id="2"]

This property will display the question's question number (including period) and can be used in referencing a previous question by number when you have a dynamically numbered survey (logic showing and hiding questions). You must include the id attribute to specify which question id you are retrieving.

Page Category

piped title

[page("piped title")]

This special merge code property is only used within a page that is piped and can be used in any question or descriptive text within that page. It will display the answer title of the current iteration of the piped question. This is the answer title that is visible to the respondent. This property does not require any attributes.

piped value

[page("piped value")]

This special merge code property is only used within a page that is piped and can be used in any question or descriptive text within that page. It will display the reporting value of the current iteration of the piped question. This is the answer value that is not visible to the respondent and may be set differently than the title. This property does not require any attributes.

Invite Category

survey link

[invite("survey link")]

This merge code will display the survey link that is being used in that email campaign. This property does not require any attributes.

messageid

[invite("messageid")]

This merge code will display the unique id given to the specific invitation recipient in an email campaign (this id is appended to the survey link). This property does not require any attributes.

custom 1

custom 2

custom 3

custom 4

custom 5

[invite("custom 1")]

This merge code will display the corresponding custom field number from the invite recipient in an email campaign. This property does not require any attributes.

Contact Category

email

[contact("email")]

This merge code will display the email address of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

first name

[contact("first name")]

This merge code will display the first name of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

last name

[contact("last name")]

This merge code will display the last name of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

organization

[contact("organization")]

This merge code will display the organization of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

department

[contact("department")]

This merge code will display the department of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

home phone

[contact("home phone")]

This merge code will display the home phone of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

work phone

[contact("work phone")]

This merge code will display the work phone of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

fax

[contact("fax")]

This merge code will display the fax number of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

street

[contact("street")]

This merge code will display the street name of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

suite

[contact("suite")]

This merge code will display the suite number of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

city

[contact("city")]

This merge code will display the city of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

state

region

[contact("state")]

Both are interchangeable and will display the state or region of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

zip

postal

[contact("zip")]

Both are interchangeable and will display the zip/postal code of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

country

[contact("country")]

This merge code will display the country of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

job title

[contact("job title")]

This merge code will display the job title of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

website

[contact("website")]

This merge code will display the website of a contact and recipient of an email invitation through an email campaign. This property does not require any attributes.

URL Category

The property for the URL category is not a set value like other categories, but rather dependent on the variable being sent through the query string to the survey. The below example would pull the value of the test variable:

Sample Query String: ?test=val

Sample Merge Code: [url("test")]

If the query string variable was TEST, the above merge could would still work properly as it ignores the case of the query string variable. However, the merge code must always use lowercase property names!

Survey Category

response id

session id

[survey("response id")]

Both are interchangeable and will display the response/session id of the current survey response. This property does not require any attributes.

edit link

[survey("edit link")]

This merge code will display the unique edit link to edit the current survey response. This property does not require any attributes.

title

[survey("title")]

This merge code will display the survey title of the current survey. This property does not require any attributes.

close date

[survey("close date")]

This merge code will display the date the current survey link with close. If no date is set, it will display the current date. This property does not require any attributes.

language

[survey("language")]

This merge code will display the language being used for the current survey response. This property does not require any attributes.

total pages

[survey("total pages")]

This merge code will display the total number of pages in the current survey. This property does not require any attributes.

total questions

[survey("total questions")]

This merge code will display the total number of questions in the current survey. This property does not require any attributes.

time taken

[survey("time taken")]

This merge code will display the total amount of the time the respondent has taken to reach the page where this merge code is present, displayed in seconds. This property does not require any attributes.

total responses

[survey("total responses")]

This merge code will display the total number of completed or partial responses for the current survey. This property does not require any attributes.

id

[survey("id")]

This merge code will display the SurveyGizmo assigned survey id for the current survey (useful for API interaction). This property does not require any attributes.

basic page count

[survey("basic page count")]

This merge code will display the number of pages visited by the respondent so far, including the current page. This includes counting each iteration of a page that is page piped. Finally, it will not count navigation to pages you have already visited.

For instance, if you start on page 1, get jumped to page 3, hit 'previous page' and return to page 1, change an answer and get jumped to the Thank You page, you will have a total of 3 if the Thank You page has this merge code.

System Category

time

[system("time")]

This merge code will display the current time in the US Eastern timezone. This property does not require any attributes.

date

[system("date")]

This merge code will display the current date (in the US Eastern timezone). The default format is MM/DD/YYYY but can be altered with the format attribute (covered in the attributes section). However, this property does not require any attributes.

ip

[system("ip")]

This merge code will display the IP address of the respondent in the current survey response, if available. This property does not require any attributes.

browser

user agent

[system("browser")]

Both are interchangeable and will display the browser type/user agent string of the respondent in the current survey response, if available. This property does not require any attributes.

country

[system("country")]

This merge code will display the country of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

state

[system("state")]

This merge code will display the state of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

region

[system("region")]

This merge code will display the region of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

city

[system("city")]

This merge code will display the city of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

zip

postal

[system("postal")]

Both are interchangeable and will display the zip/postal code of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

longitude

long

[system("longitude")]

Both are interchangeable and will display the longitude of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

latitude

lat

[system("latitude")]

Both are interchangeable and will display the latitude of the respondent in the current survey response based on the geolocation data retrieved from their IP address, if available. This property does not require any attributes.

Account Category

email

[account("email")]

This merge code will display the email address of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

organization

[account("organization")]

This merge code will display the organization of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

street

[account("street")]

This merge code will display the street address of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

suite

[account("suite")]

This merge code will display the suite address of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

city

[account("city")]

This merge code will display the city address of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

region

[account("region")]

This merge code will display the region of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

zip

postal

[account("postal")]

Both are interchangeable and will display the zip/postal code of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

country

[account("country")]

This merge code will display the country of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

public phone

[account("public phone")]

This merge code will display the public phone number of the SurveyGizmo account holder, based on the primary Account Information. This property does not require any attributes.

Attributes Available

In most cases, the question category will make the most use of attributes. However, where logical, many attributes can be used in many categories and properties. Below is a list of attributes and their usage, including a common example merge code format. Remember, multiple attributes can be used together if separated by commas.

id

[question("option title"), id="2"]

The id identifier is used for a particular question id will be accessed by the property, specified as a numeric value. Rows in a table, for instance, all have their own unique question id which can be used to get the results from only a single row of a table.

option

[question("option value"), id="2", option="10004"]

The option identifier is used for a particular question's answer id, specified as a numeric value. To use the option attribute, you must specify an id attribute as well. In a List of Textboxes, the option attribute allows you to access a particular row in the list (as each 'row' is actually an option id rather than a unique question id such as with tables). Note: If the answer was not selected or filled out (in the case of an open textfield or 'row' in a List of Textboxes), the merge code will not return anything.

delimiter

[question("option value"), id="2", delimiter=";"]

The delimiter identifier is used to choose the separating mark in a list of multiple answers specified by the id attribute. The id attribute is required when using delimiter attribute. By default, if no delimiter is specified, a comma ( , ) is used to separate each answer, for instance in a checkbox question. The delimiter can be any text or html, such as using the HTML
tag as the delimiter. NOTE:The questiondelimiter attribute should be used if the id specified is a table question (not a specific row).

questiondelimiter

[question("option value"), id="2", questiondelimiter="; "]

The questiondelimiter identifier is used to choose the separating mark for rows within a table, specified by the id attribute. The id attribute is required when using questiondelimiter attribute. By default, if no questiondelimiter is specified, an HTML break (
) is used to separate each row, for instance in a table of checkbox questions. NOTE:The questiondelimiter attribute can be combined with the delimeter attribute to change the formatting between rows as well as between multiple answers within a particular row.

numberformat

[question("option value"), id="2", numberformat="2"]

The numberformat identifier is used to determine the number of decimal places, specified as 0 or positive numeric value. To use the numberformat attribute, you must specify an id attribute as well. If the numeric value is larger than the number of decimal places in the answer, zeros will be used. If the numeric value has less than the number of decimal places in the answer, rounding will occur: 158.16 with numberformat="1" will result in 158.2. This is best used on open answer question types.

stringformat

[question("option value"), id="2", stringformat="%d sheep"]

ADVANCED USERS ONLY The stringformat identifier has its own language and is extremely powerful. It is based on the PHP sprintf() function and you can see examples of it in this PHP sprintf function tutorial. This is best used on open answer question types.

case

[question("option value"), id="2", case="upper"]

The case identifier is used to choose the case of the text in the question, specified by the id attribute. There are three possible values for the case attribute:

• upper - Change the answer to all uppercase
• lower - Change the answer to all lowercase
• proper - Change the answer to all proper case (first letter of first word in sentence)

An id attribute must be specified.

default

[question("option value"), id="2", default="Yes"]

The default identifier is used to set a default output to display if the merge code would display nothing. The value should represent the exact text that should be displayed by default. NOTE: If you default attribute's value includes double quotation marks, they need to be escaped by placing a backslash prior to the double quotation mark: default="Bob said, "Giddy Up!""

displaytitle

[question("option value"), id="2", displaytitle="true"]

The displaytitle identifier is used to display the question's title, specified by the id attribute. The value should be set as "true" if it is used. An id attribute is required to use the displaytitle attribute.

optiontitle

[question("option value"), id="2", option="10004", optiontitle="true"]

The optiontitle identifier is used to display both the title and reporting value of a specific question's answer, specified by the id attribute and option attribute, respectively. The value should be set as "true" if it is used. An id attribute and option attribute are required to use the optiontitle attribute.

replace

[question("option value"), id="2", replace="yes", with="no"]

The replace identifier is used to specify text that should be replaced and must be used in conjunction with the with attribute. There can only be one replace attribute in a single merge code (multiple instances will ignore all but the last instance of replace).

with

[question("option value"), id="2", replace="yes", with="no"]

The replace identifier is used to specify text that should go in place of the text specified in the replace attribute. There can only be one with attribute in a single merge code (multiple instances will ignore all but the last instance of with).

urlencode

[question("option value"), id="2", urlencode="true"]

The urlencode identifier is used to translate the text into a format that can be placed directly into a URL. This can be used to build a query string and link dynamically and properly formatted. The value should be set as "true" if it is used.

urldecode

[question("option value"), id="2", urldecode="true"]

The urldecode identifier is used to translate the text from a URL format into normal text. This will reverse the urlencode attribute. The value should be set as "true" if it is used.

 

------

**Uncommon Version 2 Merge Codes**:

[%%CURRENT_TIME%%]

This merge code will display the current time in the US Eastern timezone. This property does not require any attributes.

[%%CURRENT_DATE%%]

This merge code will display the current date (in the US Eastern timezone). The default format is MM/DD/YYYY but can be altered with the format attribute (covered in the attributes section). However, this property does not require any attributes.

[%%CURRENT_TIMESTAMP%%]

This will act as a timestamp that does the above two date and time merge codes together.