Overview

Using Smarty variables, you can dynamically render personalized content in a message. This content is pulled from data objects stored either within Cordial or external sources.

When using Smarty to render message content, you have access to Cordial-specific data objects, the values of which can be exposed using variables. Available data objects include:

• Contact: contains data related to a contact.
• Message: contains data related to a message.
• Account: contains data related to the account.

When writing Smarty, the object names are appended with variable keys in order to render the correct value from the data object.

For example, if you created a key called first within the contact object, it would be referenced as:

{$contact.first}

It's important that you don't override these object names by setting new variables within a message with the same name. For example, if you set a variable in a message called contact with this code: {$contact = 'moose'} Then all subsequent variables referencing that object in the system would fail to render in the message.

Reserved and custom variables

Variables are related to data values based on their key name within their respective object. Some key names are reserved by the system and some are created by the user.

Examples of reserved variables in Cordial that you can render in a message:

• System variables
• Account variables
• Product variables
• Order variables

Examples of variables created by the user that you can render in a message:

• Contact attributes (including lists)
• Event variables
• Supplement variables
• External variables (used for API sending)

Smarty variables that are used in a message will be replaced by the stored data values and shown when a message is rendered either at send time or in message preview.

An example of Smarty syntax for a simple variable replacement:

Notice the name of the variable (first) is prepended with the object name (contact).

Variable scope

Variable scope determines where in the message template passed variables can be accessed. In Smarty, you can use the scope='' attribute to limit the scope of variables. The principles of variable scope are mainly applicable to application development, but in some cases they may be relevant to using Smarty variables for message personalization.

We dedicated this section to call out the potential pitfalls of global variables, and to highlight parent scope as an effective option for the majority of message personalization use cases.

You may find a large number of variable scope names on the internet, but their application is not the same when used for message sending and rendering. Please avoid using such popular scope options as root, global, and montyPython.

Aside from user defined variables, those reserved by the system can also have a global scope. Add to that the complexities of advanced Smarty utility use cases—and it becomes all too easy to unintentionally override variable names and values. And with such a wide application of variables, the global scope can become polluted, leading to unintentional name collisions that could cause message rendering issues.

Message preview typically renders message content in a controlled context and does not represent message behavior indicative of rendering for multiple contacts at the same time. Message preview is not a reliable way to test for potential issues related to global variables.

As a rule of thumb, we recommend declaring variables at the parent scope. Looking at our HTML content include overview and examples, you can see that assigning variables found within the include to the parent scope of the including template is sufficient for making those variables accessible at the message level.

In the next article, you can learn about system variables.