Overview

Contact variables allow you to access data specific to a contact and render it in a message. Most contact attributes are created by the user (name, age, date of birth, etc.) and some are reserved by the system (email address). You can learn more about creating contact attributes here.

This article discusses:

• Custom contact attribute variables (created by the user)
• List variables (created by the user)
• Reserved contact attribute variables (default in the system)

Custom contact attribute variables

When you create a custom contact attribute in Cordial, you give it a name and key. The key is what you'll use when referencing it in a message with Smarty.

{$contact.attributeKey}

The attribute key is prepended with the name of the data object where it is stored in the system. For contact attributes, the object is called "contact".

{$contact.attributeKey} will output values for

• string attributes
• number attributes
• date attributes

For example, if you create an attribute for a contact's first name and gave it a key of "first", you would write the Smarty like this:

{$contact.first}

Throughout these tutorials we will be using dot notation as it is easier to read and write: {$contact.first} Spaces or math operators (-, *, +, etc.) that are present in attribute key names can cause errors in Smarty. If these are present, use the following syntax instead: {$contact['first name']} or {$contact['first-name']}

In the example below, you can observe how a contact's attributes are stored as JSON objects, how to write the HTML and Smarty, and the rendered output.

• {
      "channels": {
        "email": {
          "address": "fredgarvin@example.com",
          "subscribeStatus": "subscribed",
          "unsubscribedAt": ""
        }
      },
      "address": {
        "street_address": "555 Truss Ave",
        "postal_code": "92108",
        "country": "United States of America",
        "state": "CA",
        "city": "San Diego",
        "tz": "America/Los_Angeles",
        "loc": {
          "lat": "32.7773",
          "lon": "-117.1008"
        },
        "countryISO": "US",
        "auto": false
      },
      "lastName": "Fred",
      "firstName": "Garvin",
      "lists": [
        "Newsletter",
        "Weekly-Specials"
      ]
    }

• Hello {$contact.firstName} {$contact.lastName},
  <br><br>
  Email address: <br>
  {$contact.channels.email.address}<br>
  <br><br>
  Mailing address: <br>
  {$contact.address.street_address} <br>
  {$contact.address.city}, {$contact.address.state} {$contact.address.postal_code}
• Hello Fred Garvin,
  
  Email Address:
  fredgarvin@example.com
  
  Mailing Address:
  555 Truss Ave
  San Diego, CA 92108

Contact attribute examples

Example 1

Assume we want to print the value for an attribute "First Name" (where the key = "fname") in the message body.

Hello {$contact.fname}.

For a contact whose attribute value for first name = Michael, the template will output:

Hello Michael.

Example 2

In some instances, you may only want to print an attribute value if it exists, like in the case of a salutation, e.g. "Hello Michael, versus Hello,". An easy way to conditionally print a value is to use an "if" statement like the following:

Hello{if $contact.fname} {$contact.fname}{/if},

In the case where there is a first name value, it will output:

Hello Michael,

And in the case where there is not, it will simply output:

Hello,

A variation of Example 2 may be that you want to print "Hello Michael," if the name exists or "Hello Friend," if it does not. To do that, simply change the Smarty code to the following:

Hello{if $contact.fname} {$contact.fname}{else} Friend{/if},

In the case where there is a first name value, it will output:

Hello Michael,

And in the case where there is not, it will output:

Hello Friend,

• Learn more about conditional statements.

Geo attributes

Geo attributes are used to store addresses. They consist of a custom key name and a set of reserved fields. While the geo attribute has a custom key name, its set of reserved fields are not customizable.

The geo reserved fields available are:

• street_address
• street_address2
• city
• state
• postal_code
• country
• tz (time zone)
• loc
  • lat (latitude)
  • lon (longitude)

For example, if you created a geo attribute of "Home Address" and gave it a key of "home_address", you would write the Smarty as follows:

Latitude and Longitude will be added automatically by the system when postal code is entered.

Lists

A contact's list association is normally used to create audience rules for message sending, but it can also be used for rendering conditional content in a message.

For example, if you want to render content for a subscriber that is in the "weekly_specials' list, you would write the following Smarty:

{if in_array('weekly_specials', $contact.lists)}
  Content for contacts in the 'weekly_specials' list here.
{/if}

• Learn more about conditional statements.

You can add or remove a contact from a list using Smarty in a message.

Add to a list

{$utils->updateContact(['mylist'=>true])}

For lists, a boolean value is passed without quotes.

Remove from a list

{$utils->updateContact(['mylist'=>false])}

Note, for lists a boolean value is passed without quotes.

• Learn more about using link functions with lists.

Reserved contact attributes

There are also some contact attributes that are reserved as system defined and cannot be changed.

Email address

Email address is a standard contact attribute and is used as the primary key for a contact. It is stored in the email object within the channels object, so in order to render it in a message with Smarty, you would write:

{$contact.channels.email.address}

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