Smarty Framework for Personalized Transactional Messages

Description

Why Smarty?

Personalized content in transactional messages is essential for them to be effective. Order confirmations and invoices require the list of itEmpower purchased and shipping notifications require tracking numbers. Since transactional messages are sent to individuals who many times are not members of your email marketing database, the existing personalization method wouldn't work, since it involves stored values within your Empower Enterprise account. Mapp's transactional messaging system utilizes a scripting language that is based upon Smarty v2.0 template/presentation framework using values passed through the XML API method call.

Using the Smarty framework has a number of advantages including:

• Open source – Smarty is well-known among web developers and there are many examples and re-useable code our there.
• Caching – Smarty provides fine-grained caching features for caching all or parts of a rendered web page. This is especially helpful for transactional messages in which speed is of the essence to create and send the email to the individual.
• Programmable – Smarty includes a simple syntax for control branching and looping of content – again, very beneficial for transactional messages where purchase information is typically presented in table format.

Basic Smarty tags work very similarly to how personalization tags currently in the system, with the biggest difference being syntax. A Smarty variable is preceded by a dollar sign and then surrounded by curly brackets: {$variable_name}. Also, be sure that the variable name is in all lower case e.g. {$firstname}.

Having this tag in the template doesn't populate itself, however. It needs information to fill in, provided at the time of sending. Smarty tags need to correspond to the values being passed to the system via the API – specifically either the transactional.sendTransaction or the transactional.sendTest methods.

The general syntax for passing Smarty tag values in the XML message of the transactional.sendTransaction or the transactional.sendTest method is as follows:

For this transactional message, the sent message inserts Value Populated in every location where {$variable_name} exists in the original template – including even the subject line. Templates can also include tags for the standard fields in the body of the transactional.sendTransaction or transactional.sendTest method call. In this example, {$email} in the template would populate with 'jsmith@example.com' in the sent email.

XML has the capacity to embed variables in an array. Smarty tags have the capacity to reference paths to a variable by using a period delimiter: {$arrayName.variableName}. For example, customers commonly have different shipping and billing addresses. The XML for a transactional.sendTransaction method call could be structured as follows:

When the transactional message is created, the system will insert "Jane Smith" in every location where {$shipping.name} appears, and "1234 Elm St." in every location where {$billing.street} appears.

 

Transient Data for Smarty Personalization

By definition, transactional messages can be sent to subscribers and non-subscribers alike. For this reason, personalization using standard fields and custom fields from a contact record are not available for use within a transactional message, even when sending to a subscriber.

All personalized information displayed within a transactional message (e.g. first name, list of itEmpower purchased, etc.) must be provided entirely within the Transactional.sendTransaction or the Transactional.sendTest method calls. The Smarty framework extracts the personalized information from the API method call and makes the appropriate substitution into the transactional message template just before the email is sent to the recipient.

 

Conditional Logic

Smarty provides simple coding syntax for conditional logic. {if} statements allow sections of a template to perform an action under certain conditions. Every {if} statement requires a closing {/if}, with all information between the two being executed when the condition is true. The Smarty Online Reference Guide includes more specifics on using the {if} statement.

As one example, addresses occasionally need a second line for suite or apartment number:

Unfortunately in this scenario, any address that doesn't require an address2 will have an additional line space between the street address and city information. Using an {if} can instruct the template to only insert the extra line space if address2 exists as follows:

Iterative Looping

Smarty also enables web designers to loop through data structures and present them on screen. {foreach} statements instructs the template to iterate a section of HTML and insert personalization multiple times. This comes in handy in cases where a single purchase confirmation email needs to list a number of itEmpower in the order. These statements loop through an array passed through in the API method call. Required attributes for the {foreach} statement are from and item where:
from: the array being looped through.
item: the name of the current element being applied
name: the label used to distinguish between each {foreach} loop so that they are distinct within the message template

The Smarty Online Reference Guide includes more specifics on using the {foreach} statement.

Here's how the message template would implement the {foreach} loop to list out itEmpower purchased in an order:

The XML message containing the actual data would look like the following:

In this example, from=$order.purchase references all three 'purchase' arrays inside the 'order' array and therefore will iterate on these three purchases; item=line causes the current 'purchase' array it's working on to temporarily be named 'line' and allows you to reference each element as $line.elementName;
name=itemlist references the name of the '{foreach} loop. You need a different 'name' value for every {foreach} loop. Name value must be one string and can contain text and numbers.

 

Putting It All Together

Now that you have an overview of how Smarty works within Mapp's Transactional Messaging platform, here's an example that puts it all together.

The screen shot below shows a typical transactional message: a purchase order confirmation. Note the presence of the {if} tags to display address information only if it's available, and the {foreach} tag which is used to iteratively display the itEmpower of the purchase.

The full XML message that is POSTed calling the transactional.sendTransaction method looks like this:

With the actual email as follows:

---