Looping Blocks

Overview

A Looping Block is a special type of Content Block that allows you to create sophisticated Campaign content that contains complex personalization, calculations, and formatting.

Looping Blocks are typically used in the following scenarios:

Building dynamic content consisting of one or more values. For example, you could create an order confirmation email message that's personalized with all of the items that the customer purchased.
Building dynamic content containing data gathered from tables other than the Campaign source table, regardless of the relationship between those tables. For example, you could create an order confirmation email message that contains the order number and date (stored on the Order table), the customer's name and address (stored on the Customer table), and product descriptions for each item purchased (stored on the Product table).
Transforming or reformatting data. For example, you could reformat a date field in your Campaign content from the way it's stored in the database ("2015-15-05 02:31:11") into a more reader-friendly format ("May 5, 2015").
Performing calculations on data. For example, you could create an email Campaign that references the consumer's Last Purchase Date by identifying all purchase records associated with a recipient, calculating which of those purchases was the "last" one, and then displaying that date within the email content.
Ranking and ordering data. For example, you could populate a Campaign message with a list of recommended products, sorted by cost.

Like Content Blocks, a Looping Block is created independently of a Campaign, and is reusable across Campaigns.

The platform also supports "Simple Looping," which allows you define a simple data looping structure within a Content Block. For more details on Simple Looping, please see Content Blocks.

The platform supports two different data sources for building Looping Blocks -- a Messaging table or the Engagement Data Platform (EDP).

The platform also supports two different scripting languages -- XSLT and Handlebars. Both configurations are described below.

Access

The Looping Blocks screen is accessible by the following method:

From the Main menu, select Assets > Blocks > Looping Blocks.

Build a Looping Block -- XSLT

This section describes how to build a Looping Block using the XSLT scripting language. This option is available for Looping Blocks built off a Messaging table, or off the EDP database.

Data Model

Creating an effective Looping Block relies on a strong understanding of the your database tables and how they're joined together. A "join" refers to the relationship between tables. Joins have a direction:

One-to-many: This join describes a table where one record can map to multiple records in a joined table.
Many-to-one: This join describes a table where many records map back to a single record in a joined table.

Looping Blocks allow you to create complex, sophisticated personalization in your message content, drawing values from tables in either the one-to-many direction, or in the many-to-one direction. Looping Blocks offer more functionality than Personalization Fields, which are limited to only accessing fields in joined tables in the many-to-one direction.

Components of a Looping Block

A Looping Block consists of two components: an XML document and an XSL style sheet coded in the XLST language.

Note: The terminology for these various documents and languages can be confusing. Technically, the language is "XLST" and the code is stored in an XLS document. However, in general usage, the terms "XLST" and "XLS" are often used interchangeably.

XML is a mark-up language (conceptually similar to HTML) that's used to describe data -- including its attributes, and its relationship to other data -- in a manner that's readable by both machines and humans. An XML document consists of a "tree" with one or more nodes. Each node can represent a table or a join, or a property of that table or join.

As a simple example, the following XML document describes a single individual on the Customer table. The XML describes three properties of this individual (his first name, last name, and address), as well as the values for those properties ("John," "Smith," and "80 Main Street" respectively). This customer has made three purchases, which are linked via a join to the Order table. The XML describes two properties for each of these purchases (the Order ID and the Order Date) and their values.

<customer_table cust_id=326>

<order_to_customer>

</ order_to_customer>

<order_to_customer>

</ order_to_customer>

<order_to_customer>

</ order_to_customer>

</ customer_table>

Within Messaging, the platform creates the XML document for you once you've defined what data you want to use in your message content. You never work directly with the XML document.

XSLT is a style sheet language for XML documents, similar to how a Cascading Style Sheet (CSS) is a style sheet for HTML documents. XSLT is a flexible programming language that can look through the tables of a database, extract the desired values, and output them in a particular format or ranking based on the user’s requirements. In short, XSLT transforms and presents the data that XML has defined.

The XSLT programming language consists of a series of tags called "elements." For the purposes of a Looping Block, you'll mostly use two specific elements:

for-each: This element will "loop through" each node of a specified name.
value-of: This element will output the selected data in a browser.

Continuing the above example, let's say you want to create Campaign content that's personalized with the Order Dates for each order that the consumer has placed. Your XSLT code would use a "for-each" element that references the Customer-to-Order table join. The system would "loop through" the XML document, looking for nodes with this join. When found, the "value-of" element tells the platform which properties to output. In this case, you want the "order_date" property.

<xsl:for-each select="/customer_table/order_to_customer">

<xsl:value-of select="Prop[@prop_name = 'order_date']/@val" />

</xsl:for-each>

Optionally, you could then apply additional XSLT elements that would reformat this date value, or rank the date values from oldest to newest.

Within Messaging, the platform will build sample XSLT code for you based on the options you select from the user interface. However, a strong knowledge of XSLT is highly recommended in order to make the best use of the Looping Block feature.

Build a Looping Block -- Handlebars

This section describes how to build a Looping Block using the Handlebars scripting language. This option is available only for Looping Blocks built off the EDP database.

When creating a Looping Block, you can include Handlebars expressions, built-in helpers, and a selection of global helpers.

Note: For more information on Handlebars, please see the official Handlebars guide.

Expressions

All standard Handlebars expressions are supported, including:

Path expressions: If the selected EDP attribute has JSON in it, a user can traverse the JSON as long as they know the schema. You can use path expressions, using dot-separated paths. For example, if the Person attribute contains the variables First Name and Last Name, a user can reference them as follows:

HTML-escaping: In Handlebars, the values returned by the {{expression}} are HTML-escaped. For example, "&" will render as "&amp". If you don't want Handlebars to escape a value, use the "triple-stash"-- "{{{".

Built-in Helpers

Looping Blocks support built-in helpers, including the following:

#if: This helper will conditionally render a block. If its argument returns false, undefined, null, "", 0, or [], Handlebars will not render the block. In the below example, when passed a "true" value for "author," the Looping Block will display firstName lastName. If "author" is null, undefined, or false, nothing will display.

Optionally, you can add an "else" section to determine what to display if the value is false. The below example will display firstName lastName if the value for "author" is true, or "Unknown Author" if the value for "author" is false.

Unknown Author

#unless: This helper can be used as the inverse of an #if helper. The below example will display the warning message if the value for "author" is false.

WARNING: This entry does not have an author!

#each: This helper will allow you to iterate over an array. Inside the block, you can use "this" to reference the element being iterated over. In the below example, when passed multiple values for "people," the block will display a bulleted list of each value. You can optionally provide an "else" section which will display only when the list is empty.

#with: This helper allows you to specify the data context of the block inside it, without needing to specify the nested syntax. This helper can also be used with block parameters to define known references in the current block. Consider the following example:

{{city.name}}: {{loc.north}} {{loc.east}}

If the above example is passed the following:

{

city: {

name: "San Francisco",

summary: "San Francisco is the cultural center of Northern California",

location: {

north: "37.73,",

east: -122.44,

population: 883305,

}

The block will output "San Francisco: 37.73, -122.44."

Global Helpers

Looping Blocks support a wide range of Global Helpers. For more details on the supported Global Helpers and how to use them, please see Global Helpers.

Custom Helpers

Looping Blocks support custom Helpers that are C# compatible. After coding the custom Helper, please speak to your Client Services team, who will add the custom Helper to your account. Please provide the Helper code, the desired name for the Helper, and a description. This description will be shown in the Helper section of the Looping Blocks screen, so be sure to include all relevant information. Once your Helper has been loaded to your account, it will be accessible from the Looping Blocks screen, beneath the list of Global Helpers.

Features

Create a New Looping Block -- XSLT

Click hereClick here

This topic describes how to create a new Looping Block through the Looping Block screen. In addition, Looping Blocks can be created through the New Item screen (see Create a New Item: Looping Block).

To create a new Looping Block using the XSLT scripting language:

In the Tool Ribbon, click + New Looping Blocks.
A "New Item" pop-up window is displayed. To select the folder where you want to save this new Looping Block, click the folder name in the Navigation Tree on the left side of this pop-up. The "Where?" field is updated with the selected folder name.
In the "Name" field, enter a name for your new Looping Block. This name must be unique within the selected folder.
Select either the messaging or edp toggle.
If you selected edp above, next to "Template Language," select xslt (this option isn't displayed if you selected messaging above, as a Messaging Looping Block will always have XSLT as its template language).
If you selected messaging above, then from the "Data Source" drop-down menu, select the source table for this Looping Block.

Note: You can never modify this source table after the Looping Block is created.

From the "Channel" drop-down menu, select the marketing channel that will utilize this Looping Block. Please note that if you selected edp above, the only supported channel is "Email."
Click Create. The Workspace is refreshed to show a blank Looping Block details screen.
The "Data Source" section is used to define the fields that are needed to personalize the data in this Block. From the "Data Field" menu, select either:

Field on the Source TableField on the Source Table

To add a field on the Block's source table:

Select a field on the Block's source table:

Messaging: If you selected a Messaging table as the data source for the Looping Block, this drop-down menu is populated with all of the fields in that table.
EDP: If you selected EDP as the data source for the Looping Block, this drop-down menu is populated with all the EDP Attributes and Dynamic Attributes that have been enabled for "use in Messaging." Please see the EDP and Loyalty Data Manager Help topic for more details on this process. The drop-down menu is organized with Attributes at the top, and Dynamic Attributes at the bottom in their own section.

The system adds this field to the "Data Source" section, along with the XML Tag for this field.

Note: If adding EDP Dynamic Attributes, the platform automatically adds the prefix "ccda" to the XML Tag. For example: {(cdda_calculate_age)}.This prefix is intended to prevent potential issues where a Dynamic Attribute and a regular Attribute have the same name.

Field on a Joined TableField on a Joined Table

For Looping Blocks built off a Messaging table, you can add fields from a joined table:

At the bottom of the drop-down menu, the menu lists all of the joins between the Block's source table and other tables. Select the desired join. The "Edit XML Join" pop-up window is displayed.
The "Collection tag" field is populated with the default value. Optionally, enter a different value in this field.
The "Item tag" field is populated with the default value. Optionally, enter a different value in this field.
An optional Filter can be selected if you need to narrow the results of the records that the Looping Block will loop through. To use an existing Filter, either begin typing in the Filter name, or click the browse button (magnifying glass icon) to browse for and select it. You can also create a new Filter by clicking the new button (plus-sign icon).
Optionally, in the "Top" field, enter the number of records from the joined table to use for personalization in the Looping Block.
Optionally, from the "Order by" drop-down menu, select a field on which to sort when getting the "Top" records. Also select the sort order: Ascending or Descending.

Note: The Top and Sort options do not define the sort order for the data presented in the message content; this feature applies only when querying for the data.

Click save join details. The system adds this join to the "Data Source" section, along with the XML Tag for this joined table, and a drop-down menu of fields in the joined table.
From the "Data Field" drop-down menu for this join, select a field on the joined table.
The system adds this field to the "Data Source" section, along with the XML Tag for this field.

Repeat the above step as needed to define additional fields, either on the source table, or on some other joined table.
In the Tool Ribbon, click Save. When you save a Looping Block, the system refreshes the sample XSLT code.
In the Function Menu, click "Sample Code" to view the system-generated XSLT code. Make any necessary additions or modifications to this code.
Copy the XSLT code from the Sample Code screen to your clipboard.
In the Function Menu, click "Content" to view the Advanced Editor. The tabs across the top of the Content field indicate which format version of your message you're currently editing. The default version(s) created for this Looping Block depends on the channel you selected when creating the Looping Block. For example, an SMS Text Looping Block will have a "Mobile Text" version by default, but an Email Looping Block will have "HTML" and "Plain Text" versions by default. Paste the XSLT code into the desired version of the Advanced Editor. Repeat this step as needed to paste the XSLT code into other format versions.
Make any necessary additions or modifications to the format versions.
Optionally, you can add links within your Looping Block, and the system will capture and track when customers click these links, allowing you to measure the link performance. URLs can be defined within the Looping Block content using either of the following methods described below. The system will automatically recognize a link in either of these formats as a link intended for tracking within a Campaign. You can view these tracked links from the Campaign details screen, in the "Responses" section.

Add a link as an Attribute element. For example:

<a>

xsl:attribute name="href">

http://www.cheetahdigital.com?user=<xsl:value-of select="Prop[@prop_name = 'trans_amount']/@val" />

</xsl:attribute>

</a>

Add a link as an inline "href" attribute. For example:

<a href="http://www.cheetahdigital.com?name=Corporate website">Cheetah Digital</a>

Optionally, you can assign one or more tags to your Looping Block. To assign a tag, click on the "Add tag" field in the Edit tab of the Tool Ribbon. The system displays a pop-up menu of all the existing tags. You can select one of these tags, or type in a new one and press Enter. You can repeat this process to add more tags. To remove a tag, click the "X" icon next to the tag label.
To save your Looping Block, click Save in the Tool Ribbon.

Create a New Looping Block -- Handlebars

Click hereClick here

To create a new Looping Block using the Handlebars scripting language:

In the Tool Ribbon, click + New Looping Blocks.
A "New Item" pop-up window is displayed. To select the folder where you want to save this new Looping Block, click the folder name in the Navigation Tree on the left side of this pop-up. The "Where?" field is updated with the selected folder name.
In the "Name" field, enter a name for your new Looping Block. This name must be unique within the selected folder.
Select the edp toggle.
Next to "Template Language," select handlebars.
The "Channel" drop-down menu is automatically populated with "Email." EDP Looping Blocks support only the Email Channel.
Click Create. The Workspace is refreshed to show a blank Looping Block details screen.
The "Data Source" section is used to define the fields that are needed to personalize the data in this Block. From the "Data Field" menu, select an EDP Attribute. This drop-down menu is populated with all the EDP Attributes and Dynamic Attributes that have been enabled for "use in Messaging." Please see the EDP and Loyalty Data Manager Help topic for more details on this process.
The system adds this field to the "Data Source" section, along with the Handlebars variable for this field. Repeat the above step as needed to define additional fields.

Note: If adding EDP Dynamic Attributes, the platform automatically adds the prefix "ccda" to the Handlebars variable. For example: {(cdda_calculate_age)}.This prefix is intended to prevent potential issues where a Dynamic Attribute and a regular Attribute have the same name.

The Advanced Editor is displayed within the "Content" section. The tabs across the top of the Advanced Editor indicate which format version of your message you're currently editing. By default, an Email Looping Block will have "HTML" and "Plain Text" versions. Make any necessary additions or modifications to the format versions.
Optionally add Personalization Fields to the Looping Block content using the Personalization Pane along the right-hand side of the screen. The field is added to the Advanced Editor using Handlebars variable formatting.
Optionally, to use a Handlebars global helper, click "Helpers" in the Functional Menu. From the "Global Helpers" drop-down menu, select the desired helper. Global Helpers are displayed first, followed by any custom Helpers defined in your account. The helper code is displayed, along with a description of its purpose.
Optionally, you can assign one or more tags to your Looping Block. To assign a tag, click on the "Add tag" field in the Edit > Tags section of the Tool Ribbon. The system displays a pop-up menu of all the existing tags. You can select one of these tags, or type in a new one and press Enter. You can repeat this process to add more tags. To remove a tag, click the "X" icon next to the tag label.
To save your Looping Block, click Save in the Tool Ribbon.

Copy a Looping Block

Click hereClick here

To copy an existing item to use as the basis for a new item:

Search for the desired item (see Search for an Item for more details).
Click on the item name. The main item screen is displayed and populated with the details of the selected item.
In the Tool Ribbon, click Save As. A "Save as" dialog box is displayed.
Enter a name for the new item.
By default, the new item will be saved in the same folder location as the base item. Optionally, click the magnifying glass icon to browse to and select a different folder location.
Click save a copy. The system creates a copy of the selected item.

View or Edit a Looping Block

Click hereClick here

To view or edit an existing Looping Block:

Search for the desired Looping Block (see Search for an Item for more details on the available search methods).
Click on the Looping Block name. The Looping Block screen is displayed and populated with the details of the selected Looping Block.
Optionally, to view detailed information about the Looping Block, click the Looping Block tab in the Tool Ribbon. The Item Details screen is displayed, showing who created the item, who modified it last, and what the last actions taken on the item were. The direct link URL to the Looping Block is available here, which can be copied to the clipboard using the "Copy Link" icon. This can be used to easily share and also open the Looping Block in a browser. On this screen, click "Related Items" in the Function Menu to see other items in the system that reference or utilize this Dynamic Block. When finished, click the Edit tab in the Tool Ribbon to return to the main edit screen.
Optionally, you can assign one or more tags to your Looping Block. To assign a tag, click on the "Add tag" field in the Edit > Tags section of the Tool Ribbon. The system displays a pop-up menu of all the existing tags. You can select one of these tags, or type in a new one and press Enter. You can repeat this process to add more tags. To remove a tag, click the "X" icon next to the tag label.
Optionally, to rename the Looping Block, click Rename in the Tool Ribbon. A "Rename Item" dialog box is displayed. Enter a new name for the Looping Block, then click save new name.
Make any necessary changes to the fields used within this Looping Block:

- Add a new field needed to personalize the data in this Block. From the "Data Field" menu, select either:
  1. Field on the source tableField on the source table
    1. Select a field on the Block's source table.
      
      The system adds this field to the "Data Source" section, along with the XML Tag for this field.
  1. Field on a joined tableField on a joined table
    1. At the bottom of the drop-down menu, the menu lists all of the joins between the Block's source table and other tables. Select the desired join. The "Edit XML Join" pop-up window is displayed.
      
      The "Collection tag" field is populated with the default value. Optionally, enter a different value in this field.
      
      The "Item tag" field is populated with the default value. Optionally, enter a different value in this field.
      
      An optional Filter can be selected if you need to narrow the results of the records that the Looping Block will loop through. To use an existing Filter, either begin typing in the Filter name, or click the browse button (magnifying glass icon) to browse for and select it. You can also create a new Filter by clicking the new button (plus-sign icon).
      
      Click save join details. The system adds this join to the "Data Source" section, along with the XML Tag for this joined table, and a drop-down menu of fields in the joined table.
      
      From the "Data Field" drop-down menu for this join, select a field on the joined table.
      
      The system adds this field to the "Data Source" section, along with the XML Tag for this field.
- If you need to remove a field or a table join, click the remove button ("X" icon). The row is grayed-out to indicate that it's been marked for deletion. To complete the removal, click Save in the Tool Ribbon.

Note: If you remove an entire table join, you'll also automatically remove all fields on the joined table.

- If you need to edit a joined table, click the edit button (pen icon). The "Edit XML Join" pop-up window is displayed. Make any necessary changes to the join parameters, then click save join details.

In the Tool Ribbon, click Save. When you save a Looping Block, the system refreshes the sample XSLT code.
In the Function Menu, click "Sample Code" to view the system-generated XSL code. Make any necessary additions or modifications to this code.
Copy-and-paste the XSLT code from the Sample Code screen into the Advanced Editor. Repeat this step as needed to paste the XSLT code into other format versions.
Make any necessary additions or modifications to the format versions (See the Advanced Editor for more details).
In the Tool Ribbon, click Save.

Delete a Looping Block

Click hereClick here

To delete an item:

Search for the desired item (see Search for an Item for more details).
Click on the item name. The main item screen is displayed and populated with the details of the selected item.
In the Tool Ribbon, click Delete. A confirmation dialog box is displayed.
Click delete item to confirm the deletion.

Foldered items are moved to the Recycle Bin. Non-foldered items are permanently deleted.

Assign a Looping Block to a Campaign

Click hereClick here

Once you've created your Looping Block, you can use it within one or more Campaigns.

To insert a Looping Block into the Campaign message:

Navigate to the desired Campaign (see Campaigns for more details).
Scroll down to the "Message" section, and click Edit. The Advanced Editor is displayed.
Place your cursor in the main content field. The Personalization Pane appears on the right-hand side of the screen.
In the Personalization Pane, click on the "Content Blocks" group to expand it.
Within the "Content Blocks" group, double-click on "Looping Block" (or, optionally, you can drag "Looping Block" from the Personalization Pane, and drop it into the content field). A "Browse Looping Blocks" dialog box is displayed.
From the "Browse Looping Blocks" pop-up window, you can click on a folder in the directory structure to see a list of all the Looping Blocks stored within that Folder. Or, if you want to search across the entire system, click the double-left arrow icon near the top of the directory structure; the system collapses the directory structure and shows every Looping Block in the system. This pop-up window also allows you to search based on Tags, or by Looping Block name. When you find the desired Looping Block, click on the Looping Block name.

Note: Looping Blocks have to be created using the same source table as the Campaign in order for them to be available as a selection.

In the Clipboard section of the Personalization Pane, the system creates a new Merge Symbol for this Looping Block. A Merge Symbol is a textual representation of the Looping Block, consisting of the Block's name and Object Reference ID enclosed in double-brackets. For example: {[Membership_offer|8687]}.
Place your cursor where you want to insert the Looping Block, then click the Merge Symbol for that Block in the Clipboard. The system inserts the corresponding Merge Symbol at the indicated position.