Personalization

⌘K
  2. Home
  4. Docs
  6. Personalization
  8. Introduction
  10. Core Templating Concepts

Core Templating Concepts

There are a few basic concepts you need understand to build out truly focused personalized emails within FeedBlitz:

  • Template Tags
  • Order of operations
  • Intrinsic Variables
  • Custom Fields
  • Dynamic Fields: <$Assign$>
  • Conditional Content: <$if$>
  • Manipulating Content: <$eval$>
  • Connected Content: <$BlogConnect$>
  • Template Functions
  • JSON objects

Template Tags

FeedBlitz’s template tags always start with <$ and end with $>. How these tags are interpreted depends on what you put between them. Anything else is considered to be part of your message.

Order of Operations

It can be tempting to think of FeedBlitz’s templating capabilities as a programming language, where each line of the message is processed, top to bottom, character by character. It’s tempting, but in fact it’s much better (and you’ll be more successful) if you think of FeedBlitz’s templating features as a macro, or preprocessor language.

In particular, “simple” substitution of a variable (i.e. outside an <$eval$>, <$if$>, or <$BlogConnect$> tag) may not behave entirely as you expect.

By way of example, say you have the recipient’s name stored in the custom field <$Name$>. When FeedBlitz gets the value for that variable, it is replaced everywhere in your message all at once. If you change the value of that variable using assignment between substitutions, you may be surprised that simple substitutions of <$Name$> don’t reflect the new assignment – it’s because FeedBlitz replaced them as soon as it could.

The order of operations is as follows:

  1. Simple text substitutions via <$fieldname$> tags.
  2. Loading external content via <$BlogConnect$>.
  3. Processing the message top to bottom for remaining <$if$> and <$eval$> tags.

Intrinsic Variables

These are variables that are ones that are per subscriber, per list, per mailing, or system wide. They are available to any and all FeedBlitz clients. They are not the same as Custom Fields, which are variables that you define and populate, and are available to your account only.

Subscriber Intrinsic Fields

  • <$email$>, <$Recipient$>, <$BlogRecipient$> – the recipient’s email address.
  • <$BlogRecipientID$> – the recipient’s ID (aka the subscriber ID) within the FeedBlitz database.
  • <$MD5_R$> – lower case MD5 hash of the lowercased email address.
  • <$SHA1_R$> – as above, but using the SHA1 algorithm.
  • <$SHA256_R$> – as above, but using the SHA256 algorithm.
  • <$UID2$> – Normalized hash, see this link.

List Intrinsic Fields

  • <$BlogListID$> – The FeedBlitz ID of the list this subscriber and mailing are going to.
  • <$BlogOwnerID$> – The FeedBlitz subscriber ID of the list’s owner.
  • <$BlogSiteName$> – The name of the site the list is contained by.

Mailing Intrinsic Fields

  • <$BlogMailingID$> – The unique ID of this mailing
  • <$BlogCycleName$> – The type of this mailing (e.g. “weekly” for a weekly RSS to email campaign).

Note: For transactional mailings, such as test emails and opt-in confirmations, the mailing ID will be associated with a transactional mailing campaign for that day.

Other Intrinsic Fields

  • <$Date$> – The date and time in US Eastern. See shortcodes for formatting attributes.
  • <$DateUTC$> – The date and time in UTC. See shortcodes for formatting attributes.

RSS to Email Shortcodes

For insight into these, see this article.

Custom Fields

Custom Fields (and tags) are data variables that you define within FeedBlitz, and then save data to them for each relevant subscriber. They represent data that’s stored within FeedBlitz.

To substitute a custom field into a template, simply drop it in by name between <$ $> tags. So if you had the following custom fields defined within FeedBlitz – City, State, and Zip – you can insert them into the mailing like this:

  • <$Name$> lives in <$City$>, <$State$> <$Zip$>.

Disambiguating Field Names

If your custom field contains symbols that might otherwise look like Math to FeedBlitz’s templating engine (e.g. “Address-1” which looks like “Subtract one from the value stored in the custom field named ‘Address’ “), use backticks ` to enclose the fieldname when used in the context of a conditional statement or an eval. e.g. `Address-1` is the field called “address-1”

<$FieldValue$>

Alternatively, you can use this syntax to drop in the value of a field:

  • <$FieldValue “fieldname“$>

As in this example:

  • <$FieldValue “Name”$>

This latter syntax allows you to build the field you want to look up in the template itself, dynamically, rather than hard coding it.

<$FieldLookup$>

Sometimes, the data value stored in a custom field might not be very reader-friendly. Say, for example, you have defined the reward tiers custom field <$Tier$> as a multi-value, single select field, with the following values and names:

  • 0 – none
  • 1 – Gold
  • 2 – Platinum
  • 3 – Platinum Executive

If you simply coded your template like this:

  • Congratulations on reaching the <$Tier$> level!

What the recipient receives is “Congratulations on reaching the 2 level!” – so what you code instead is:

  • Congratulations on reaching the <$FieldLookup “Tier”$> level!

Which results in “”Congratulations on reaching the Platinum level!” – much friendlier.

Tags

Tags are included in templates the same way as custom fields: by name. A tag may have only three values: Empty, 0, or 1. Empty and 0 both mean “not tagged”, whereas a subscriber whose tag value is “1” has been tagged.

Dynamic Fields <$Assign$>

Dynamic fields are fields you create within the template itself. These fields are temporary: they only exist while the personalization engine is working on your message. They are created and assigned a value one of three ways:

  • The <$Assign$> statement, e.g. <$Assign foo=”bar”$>
  • With an <$eval$> using the := operator, e.g. <$eval foo:=”bar”$>
  • Within a <$BlogConnect$> tag using the “assign:” attribute.

When the assignment is made, no content is inserted into your message. You can use your newly assigned variable just like any other custom field, which using the above examples is done using: <$foo$>

Note that you can assign into the recipient’s custom field. If you do, results may not be as expected, so test thoroughly! Also note that all assignments only exist for the duration of the personalization pass. If you assign into a custom field from the database in the template, the assigned data is not saved back to FeedBlitz at the end (i.e. the change is discarded).

Conditional Content: <$if$>

Once you have your custom fields, variables, and tags assembled, you can drop them into the content as you wish, or make the content you send depend on those values. This is the function of the <$if$> <$else$> <$endif$> template tags.

  • <$if logical expression$> content to insert if true <$else$> content to insert if false <$endif$>

The “<$else$> content if false ” is optional (i.e. you can write <$if logical expression$> content to insert if true <$endif$>)

When using custom fields in logical expressions, you do not use <$ $> to surround them. In other words:

  • Correct: <$if Name=”Phil”$>Hey, boss!<$endif$>
  • Incorrect: <$if <$Name$>=”Phil”$> .. <$endif$>

You can nest if statements, as in

  • <$if FirstName=”Bugs”$> <$if LastName=”Bunny”$> What’s up, doc?<$endif$><$endif$>

Although that’s a clumsy way to write this particular example! Better would be:

  • <$if FirstName=”Bugs” && LastName=”Bunny”$>What’s up doc?<$endif$>

See the reference section on more information about using the <$if$> statement and building conditional content.

Alternate <$if$> syntax

You can use the following alternative forms if you wish:

  • <$?$> instead of <$if$>
  • <$:$> instead of <$else$>
  • <$/?$> instead of <$endif$>

Manipulating Content: <$eval$>

The eval statement takes templating tags, template functions, custom fields, conditional logic, and emits the results into your message. It can contain conditional logic (via the <$if$> tag), and multiple statements when the semicolon statement separator is used.

For example:

<$eval sport:=”soccer”; alias=”football”; <$if$ sport==alias>These are the same!<$else$> No, they’re not!<$endif$> $>

which will always result in “No,. they’re not!” being added to the email.

Alternate <$eval$> syntax

You can use <$% expression $> instead of <$eval expression $>

Connected Content: <$BlogConnect$>

For organizations with diverse data sources, such as CRM systems, data warehouses, and custom subscriber intelligence solutions, it may be very undesirable to import that data into FeedBlitz as custom fields. Issues can include the challenges of syncing FeedBlitz with corporate back office systems, storing PII on a third party system, data de-duplication headaches, and legal / privacy / compliance issues.

The <$BlogConnect$> tag lets you import external content into your email on demand at email generation time. Although this does require secure access to the underlying remote system, which may create internal audit issues for some, it completely eliminates the headaches of data syncing and potentially saving sensitive data in a third party (i.e. FeedBlitz) system.

Use cases include:

  • Custom content based on preferences or behaviors,
  • Account information, transactional emails, and promotions based on activity.

With <$BlogConnect$>, you can GET from or POST to a custom webhook, using custom variables from the message or data known to FeedBlitz about the subscriber, generating unique content for that recipient. The webhook URL called can include custom fields or shortcodes, so (for example) you can send the MD5 hash of a user’s lower cased email address as a custom content URL parameter.

It’s worth noting that being able to fetch a webhook enables an additional set of use cases: you can use the webhook to update your own internal tracking solutions, based on when the message is generated, what is in it, and to whom it’s sent.

The tag can either insert the results into the email, or assign them to a dynamic variable for the template to access later. See the reference section for how to set up this tag, along with performance requirements and potential scalability issues.

Template Functions

You can use these functions in <$eval$> and <$if$> statements as you tailor the message:

  • String comparison: contains, notcontains, startswith, endswith, notstartswith, notendswith.
  • String manipulation: left, right, mid, find, replace, replacefirst, replacelast, substr, remove, removefirst, removelast, reverse, reversefind, truncate, truncatewords, uppercase, lowercase, titlecase, propercase, sentencecase, length, trim, trimright, trimleft.
  • Math functions: abs, floor, ceil, round, min, max, money, commaformat.
  • Hashing and (de)coding: MD5, SHA1, SHA256, Base64, Base64Decode.
  • Date and time functions: now, dateformat, dateformatutc.
  • JSON array functions and operators: split, join, length, []

Template functions can be used in a functional programming style, or a pipe-like stream style. These are equivalent and both valid template personalization syntax:

  • <$eval MD5(email) $>
  • <$eval email MD5 $>

You can mix and match these approaches to build templating code that you find the most readable and maintainable, as in the following examples which all provide an upper case MD5 hash of a lowercase email address:

  • <$eval uppercase(lowercase(email) MD5) $>
  • <$eval uppercase(MD5(lowercase(email))) $>
  • <$eval MD5(email lowercase) uppercase $>
  • <$eval email lowercase MD5 uppercase$>

JSON objects

If a variable contains valid JSON data, you can dereference that data within the template. Say you had a custom field called “Location” and it contained the following JSON:

  • {“city”: “New York”, “state”: “New York”, “zip”: “10022”}

You get those values inside <$eval$> or <$if$> statements as

  • Location[“city”]
  • Location.city
  • Location[“state”]
  • Location.state
  • etc.

You cannot update a JSON element, however. This won’t work:

  • <$eval Location[“city’]:=”Albany” $>