Get Supplements (getSupplementRecords method)

Overview

The data stored within a supplement can be referenced and used within any message body.

Our example

For our example we'll be using supplement data consisting of a list of automobiles.

Using the tabs below you can view the HTML and Smarty used in the message, the supplement data being referenced (in JSON format) and the rendered output that will display when a message is sent or previewed.

{$supplement_records.key = 'automobiles'}
{$supplement_records.query = []}
{$supplement_records.limit = 25}
{$supplement_records.sort = []}
{$supplement_records.cacheMinutes = 25}

{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key, $supplement_records.query, $supplement_records.limit, $supplement_records.sort, $supplement_records.cacheMinutes)}

{foreach $supplement_records.data as $array_position => $car}  
<strong>({$array_position}) {$car.brand|capitalize} {$car.model|capitalize}</strong><br>
${$car.price}<br>
Mileage: {$car.mileage}<br><br>
{/foreach}

[
    {
      "model": "pilot",
      "brand": "honda",
      "price": 33000,
      "mileage": 100000,
      "id": "01"
    },
    {
      "model": "explorer",
      "brand": "ford",
      "price": 34000,
      "mileage": 39000,
      "id": "02"
    },
    {
      "model": "prius",
      "brand": "toyota",
      "price": 27000,
      "mileage": 66000,
      "id": "03"
    },
    {
      "model": "model s",
      "brand": "tesla",
      "price": 130000,
      "mileage": 56000,
      "id": "04"
    },
    {
      "model": "versa",
      "brand": "nissan",
      "price": 16000,
      "mileage": 94000,
      "id": "05"
    },
    {
      "model": "camary",
      "brand": "toyota",
      "price": 29000,
      "mileage": 310000,
      "id": "06"
    },
    {
      "model": "accord",
      "brand": "honda",
      "price": 24000,
      "mileage": 49000,
      "id": "07"
    }
  ]

The getSupplementRecords method

In order to access supplement data within a message, use the getSupplementRecords method, a custom extension of Smarty provided by Cordial.

The getSupplementRecords method has 5 parameters: key, query, limit, sort, and cacheMinutes. They must be written in this order and separated by commas. Only "key" is required. If you would like to leave a preceding parameter blank, it must be populated either by empty brackets "[]" for arrays or the word "null" for integers (empty single quotes should also work for integers).

getSupplementRecords($key, $query, $limit, $sort,$cacheMinutes)

How to set the key

A unique key is created with each new supplement and is used to identify the supplement in the database. Learn how to create a supplement.

You can retrieve the supplement key 2 ways:

• Via the UI by navigating to Data › Supplement Data
• Via the API by using the GET <path>/supplements call. View the interactive API documentation.

Here is an example using the supplement "automobiles":

{$supplement_records.key = 'automobiles'}
{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key)}

In the example above, a variable "supplement_records.data" is assigned to the resulting data set returned from the supplement with the key of "automobiles". The getSupplementRecords method will get the data from "automobiles" for each message that is rendered per contact.

How to set the query

In some cases, you may want to get specific records from the supplement. You can achieve this by adding query filters.

Return records filtered by a specified value.

['key'=>'value']

The following example will return records where the brand is toyota:

{$supplement_records.query = ['brand'=>'toyota']}

Return records filtered by multiple specified values.

['key'=>'value', 'key2'=>'value2']

The following example will return records where the brand is toyota AND the price is 33000.

{$supplement_records.query = ['brand'=>'toyota','price'=>'33000']}

Return records filtered by multiple specified values of the same key.

['key'=>['in' => [value1,value2]]]

The following example will return records where the brand is toyota OR honda.

{$supplement_records.query = ['brand'=>['in' => [toyota,honda]]]}

The following example will return records that are not in the specified array.

{$supplement_records.query = ['brand'=>['notIn' => [toyota,honda]]]}

Return records filtered by values that are contained in an array.

[key => ['array_contains' => 'value']])}

The following example will return records where the color black is contained in the array with the key of colors:

{$supplement_records.query = ['colors'=>['array_contains' => 'black']]}

Return records filtered by a contact's attribute.

['key'=>{$variable}]

Example:

{$supplement_records.query = ['automobiles'=>['brand'=>{$contact.favCarBrand}]}

Return records filtered by comparison operators.

Use a comparison operator to filter results ("lt" = less than, "gt" = greater than, "gte" = greater than or equal to).

["key"=>['lt'=>number]]
["key"=>['gt'=>number]]
["key"=>['gte'=>number]]

Example:

{$supplement_records.query = ['price'=>['lt'=>30000]]}
{$supplement_records.query = ['price'=>['gt'=>20000]]}
{$supplement_records.query = ['price'=>['gte'=>50000]]}

Return records filtered by values between two numbers.

['key'=>['between'=>['start'=>number,'end'=>number]]]

Example:

{$supplement_records.query = ['price'=>['between'=>['start'=>10000,'end'=>50000]]]}

Return records filtered by the current date/time.

['key'=>['eq'=>{$smarty.now|date_format}]]

Return records filtered by values between two dates.

['key'=>['lt'=>{$smarty.now|date_format}],'key'=>['gt'=>{'date_format'}]]

Example:

['date'=>['lt'=>{$smarty.now|date_format:'%Y-%m-%dT%H:%M:%S+0000'}],'date'=>['gt'=>{'2020-10-10T22:21:18+0000'}]]

How to set the limit

Use the limit filter to limit the number of records returned.

Example without a query filter and a limit of 5 records:

{$supplement_records.key = 'automobiles'}
{$supplement_records.query = []}
{$supplement_records.limit = 5}

Example with a query filter and a limit of 7 records:

{$supplement_records.key = 'automobiles'}
{$supplement_records.query = ['brand'=>'toyota']}
{$supplement_records.limit = 7}

How to sort the data

Sort results by price in ascending order.

{$supplement_records.sort = ['column'=>'price','direction'=>'ASC']}

Sort results by price in descending order.

{$supplement_records.sort = ['column'=>'price','direction'=>'DESC']}

Sort results by last modified in descending order.

{$supplement_records.sort = ['column'=>'lm','direction'=>'DESC']}

Sort results by date created in descending order.

{$supplement_records.sort = ['column'=>'ct','direction'=>'DESC']}

How to set the cacheMinutes

A cache can be set in memory for the data so the system doesn't have to retrieve data directly from the database for every individual message. Retrieving data from the cache instead optimizes the time it takes to compile and send messages.

You can specify the number of minutes that data is stored in memory with this parameter. The length of time data should be cached depends on how often your supplement data changes. If, for example, your supplement data doesn't change much within a short period of time, you could set cacheMinutes at 20 minutes.

{$supplement_records.key = 'automobiles'}
{$supplement_records.query = []}
{$supplement_records.limit = null}
{$supplement_records.sort = []}
{$supplement_records.cacheMinutes = 20}

Render the data in a message

After the data is available with the getSupplementRecords method, you can render the data in the message.

Loop through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.

Example:

{$supplement_records.key = 'automobiles'}
{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key)}

{foreach $supplement_records.data as $car} 
<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
${$car.price}<br> 
Mileage: {$car.mileage}<br> 
<a href="http://example.com/cars/{$carObject.id}">View details</a><br><br>
{/foreach}

Learn more about using the {foreach} statement.

Reference an index of the array

If you don't need to loop through all of the data in the array, you can render a specific value by referencing its index within the rendered array.

Example:

{$supplement_records.key = 'automobiles'}
{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key)}

{$supplement_records.data[0].brand}

Alternate syntax:

{$supplement_records.key = 'automobiles'}
{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key)}

{$supplement_records.data.0.brand}

This example will look in the first record of the data array and render the value for "brand".

Use Smarty variables in supplements

Smarty variables stored within supplements will not render in a message due to the way Smarty is processed. As a workaround, you can create a placeholder in the supplement data and then use the Smarty replace function to replace the placeholder with the desired variable.

Example:

{$supplement_records.key = 'message_content'}

{$content.0.subject = $content.0.subject|replace:'%first_name%':$contact.first_name}
{$content.0.subject}

[
    {
      "subject": "Special offer for you %first_name%!",
      "ct": "2017-10-10T22:21:18+0000",
      "lm": "2017-10-10T22:21:18+0000",
      "id": "1"
    }
  ]

Query and render contact attribute supplements

Contact specific supplement data can be rendered for individual contacts at message send time. Contact attribute enabled supplements can be queried by cID using the {$contact.id} Smarty variable. Contact attribute supplement records are given the cID of a corresponding contact, regardless of the contact identifier initially used to add the record.

Query records specific to a contact using cID:

{$supplement_records.query = ['cID'=>{$contact.id}]}

In this example, we are querying the favorite automobiles contact attribute supplement and rendering the results in a message. Use the limit parameter to specify the maximum number of records to render.

Example:

{$supplement_records.key = 'fav_automobiles'}
{$supplement_records.query = ['cID'=>{$contact.id}]}
{$supplement_records.limit = 3}
{$supplement_records.sort = []}
{$supplement_records.cacheMinutes = 20}

{$supplement_records.data = $utils->getSupplementRecords($supplement_records.key, $supplement_records.query, $supplement_records.limit, $supplement_records.sort, $supplement_records.cacheMinutes)}

<h3>Cars from your favorites collection:</h3>
{foreach $supplement_records.data as $car}  
<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
${$car.price}<br>
Mileage: {$car.mileage}<br><br>
{/foreach}