Looping Blocks

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 Cheetah Digital 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 via 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 Cheetah Digital 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.

Copy

<customer_table cust_id=326>
                 <prop name="name_first" val="John" />
                 <prop name="name_last" val="Smith" />
                 <prop name="address" val="80 Main Street" />
                 <order_to_customer>
                 <prop prop_name="order_id" val="138" />
                 <prop prop_name="order_date" val="8-5-2014" />
                 </ order_to_customer>
                 <order_to_customer>
                 <prop prop_name="order_id" val="965" />
                 <prop prop_name="order_date" val="10-1-2014" />
                 </ order_to_customer>
                 <order_to_customer>
                 <prop prop_name="order_id" val="419" />
                 <prop prop_name="order_date" val="5-5-2015" />
                 </ order_to_customer>
            </ customer_table>

Within Cheetah Digital, 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.

Copy

<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 Cheetah Digital, 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:

Copy

{{person.firstname}} {{person.lastname}}

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.

Copy

{{#if author}}
                {{firstName}} {{lastName}}
            {{/if}}

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.

Copy

{{#if author}}
                {{firstName}} {{lastName}}
                {{else}} 
                Unknown Author
            {{/if}}

#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.

Copy

{{#unless author}}
                WARNING: This entry does not have an author!
            {{/unless}}

#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.

Copy

{{#each people}}
                  <li>{{this}}</li>
            {{/each}}

#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:

Copy

{{#with city as | city |}}
                  {{#with city.location as | loc |}}
                    {{city.name}}: {{loc.north}} {{loc.east}}
                  {{/with}}
            {{/with}}

If the above example is passed the following:

Copy

{
                  city: {
                    name: "San Francisco",
                    summary: "San Francisco is the <b>cultural center</b> of <b>Northern California</b>",
                    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.

Create a new Looping Block -- XSLT

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 Cheetah Digital or EDP toggle.
If you selected EDP above, next to Template Language, select XSLT (this option isn't displayed if you selected Cheetah Digital above, as a Cheetah Digital Looping Block will always have XSLT as its template language).
If you selected Cheetah Digital 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 Table

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

Select a field on the Block's source table:
- Cheetah Digital: If you selected a Cheetah Digital 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 Cheetah Digital. 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 Table

For Looping Blocks built off a Cheetah Digital 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:

Copy

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

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

Copy

<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

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

Copy a Looping Block

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

View or edit a Looping Block

To view or edit an existing Looping Block:

Delete a Looping Block

To delete an item:

Assign a Looping Block to a campaign

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: