Follow

Template Designer Documentation

WhatCounts email templates are reusable templates that are intended to be used as a base for multiple emails. That means they should be built with the ability to handle a variable number of products and leave extension points to allow setting email specific text. This documentation will cover the syntax necessary to build these templates.
 

Template Syntax 

WhatCount's email templates are based on the Jinja2 templating language. This means it is possible to build sophisticated logic into templates to handle a wide variety of use cases. We'll cover the basics here, but for more detail, you can always consult the Jinja2 Template Designer Documentation.

Variables 

In WhatCounts templates, variables are accessed with syntax inside double curly braces, like

Screen_Shot_2018-02-09_at_3.11.52_PM.png

When accessing an item from a list of items, standard square brace array syntax is used, and the list starts at 0:

Screen_Shot_2018-02-09_at_3.12.52_PM.png

You can also use the square brace syntax to access a subproperty of an object. Alternatively, you can use the equivalent object.property syntax:

Screen_Shot_2018-02-09_at_3.13.44_PM.png

if statements

You can use if statements in WhatCounts templates with the {% if x %} syntax:

Screen_Shot_2018-02-09_at_3.15.46_PM.png

if statements can be used as checks to see if a value exists, whether it is equal to a certain value, and they can be combined with filters (described below) to check things like the length of a list of items.  A full set of comparisons is supported.

Screen_Shot_2018-02-09_at_3.17.15_PM.png

There is more information about if statements in the Jinja Template Designer Docs.

for loops

WhatCounts templates are provided with 2 lists of product data, products and secondary_products. Because these lists can be of different length for different email sends, it is useful to be able to loop over them and handle them one at a time. The syntax for looping over a list of products looks like this:

Screen_Shot_2018-02-09_at_3.21.00_PM.png

In addition to the for loop basics, there are many advanced loop variables you can use to (for instance) treat the first and last items in a loop differently. Those are all described in the Jinja Template Designers Documentation.

 

filters

Sometimes you need to transform or modify your data before displaying or comparing it. WhatCounts templates provide filters for that purpose. Filters are simply transformations performed on a variable, and use a pipe character syntax like this:

Screen_Shot_2018-02-09_at_3.22.29_PM.png

You can see a full list of the built-in filters in the Jinja Template Designers Documentation. WhatCounts also provides a custom filter add_tracking_codes, which is important to use on all template links. It appends links with personalized URL parameters on each send, to allow revenue and click tracking.

Screen_Shot_2018-02-09_at_3.25.16_PM.png

WhatCounts Provided Variables

There are a number of variables that you can use in WhatCounts Templates to provide extension points for templates. When some of these variables are used in a template, users who are building email campaigns based on the template will be given access to controls to set them as needed for the variable. These variables fall into a few main buckets:

We'll go through these one by one here but you can also use the autocomplete feature in the template editor to see what variables are available.

Content Variables

Content variables provide hooks for various types of email specific content to be loaded into the templates. The most important of these are the product variables that let users fill the template in with product recommendation logic, but you can also use them to provide email specific text fields, videos, header images, and call-to-action controls.

Variable Description
products A list of the primary product recommendations for an email. There may be between 0 and 6 products recommended for a given email, so make sure to write support for all of those product counts and not assume that emails will always have the same number of products. Note: Even if you're using static recommendations in all of your emails, we will not recommend out-of-stock or discontinued products, or show duplicate products in the primary and secondary product lists, so the actual number of recommended products may vary.

Products contain the following subproperties: title, link, and image link. You would access the title of the first product in the list like this:

{{products[0].title}}
secondary_products A list of the secondary product recommendations for an email. There may be between 0 and 3 secondary products recommended for a given email, so make sure to write support for all of those product counts and not assume that emails will always have the same number of products. Note: Even if you're using static recommendations in all of your emails, we will not recommend out-of-stock or discontinued products, or show duplicate products in the primary and secondary product lists, so the actual number of recommended products may vary.

Products contain the following subproperties: title, link, and image link. You would access the title of the first product in the list like this:

{{secondary_products[0].title}}
{{canspam_text}} Inserts CAN-SPAM information into the template. Required in every template for compliance reasons.
{{title}} A variable for allowing users to set an email-specific heading for the body copy section.
{{body_text}} The primary body copy for an email.
{{button_text}} The text for each product link button in an email.
{{use_cta}} The boolean value that determines whether a user wants to include a CTA (call-to-action) button in the template.
{{cta_text}} The text of an optional CTA button. If you include this without {{use_cta}}, you should provide a fallback value using the default filter like this:

{{cta_text|default('take a look at this')}}
{{cta_url}} The destination URL for an optional call to action button. If you include this without {{use_cta}}, you should provide a fallback value using the default filter like this:

{{cta_url|default('http://mysite.com')}}
{{use_go_to_cart}} A boolean value that determines whether a user wants to include a go-to-cart button in the template. Will be False for non-Cart Recovery campaign emails.
{{cart_text}} The text of an optional go to cart button. If you include this without {{use_go_to_cart}}, you should provide a fallback value using the default filter like this:

{{cart_text|default('Go To Cart')}}
{{cart_url}} The destination URL for an optional go-to-cart button. If you include this without {{use_cart}}, you should provide a fallback value using the default filter like this:

{{cart_url|default('http://mysite.com/cart')}}
{{include_video}} An optional boolean value that determines whether a user wants to include a video in the template. Videos are just still images with a dynamic link to a video that can be edited on an email by email basis.
{{video_text}} The caption text of an optional video. If you include this without {{include_video}}, you may want to  provide a fallback value using the default filter like this:

{{video_text|default('Check this out!')}}
{{video_url}} The url of an optional video.  If you include this without {{include_video}}, you may want to  provide a fallback value using the default filter like this:

{{video_url|default('http://vimeo.com/companyvideo')}}
{{video_image}} The URL of an optional video placeholder image. If you include this without {{include_video}}, you may want to provide a fallback value using the default filter like this:

{{video_image|default('http://mysite/images/placeholder.png')}}
{{footer_text}} A variable for allowing users to set email specific footer copy.
{{main_img}} An optional "hero image" URL for allowing variable hero images in an email.
{{preheader_text}} A variable for allowing users to set email specific pre-header copy.
{{secondary_copy}} A variable for allowing users to set email specific copy for the secondary products area.
{{secondary_title}} A variable for allowing users to set an email specific section title.
 

Personalization Variables

Personalization variables aren't set by the user, but instead will be filled with customer-specific content when the email is sent. These are also exposed as merge tags for users who are filling in email-specific text fields.

Variable Description
{{First_Name}} The first name of the customer receiving the email, if available. Consider using the default filter with this merge tag if you do not have name information for your entire contact list.
{{Last_Name}} The last name of the customer receiving the email, if available. Consider using the default filter with this merge tag if you do not have name information for your entire contact list.
{{Full_Name}} The full name of the customer receiving the email, if available. Consider using the default filter with this merge tag if you do not have name information for your entire contact list.
{{Coupon_Code}} A coupon code that may be set for an email. Because coupon codes may not be included in all emails, consider adding an if statement around coupon code blocks, or falling back to a default in order to avoid showing an empty coupon field.
{{Last_Product_Purchased_Title}} The title of the highest-priced product from the customer's last order.

You can also use custom fields in emails:

  • For order- and customer-level fields, the syntax is WCCF_<Field_Name>, which will look like {{WCCF_CustomerBirthday}} in emails for a field named CustomerBirthday.
  • For product-level fields, the field is available as a subproperty of a specific product, like {{products[0].WCCF_ProductBrand}}.

Stylistic Variables

Finally, WhatCounts provides several stylistic variables that allow setting background and text colors on an email-specific level, but these are generally not useful for client-created templates. We recommend instead that you code your brand guideline colors into your templates and change them at the template level if they need to be updated, so that you don't need to update every email from each of your campaigns for a brand-level stylistic change.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk