• {$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"
      }
    ]

• (0) Honda Pilot
  $33000
  Mileage: 100000
  View details
  
  (1) Ford Explorer
  $34000
  Mileage: 39000
  View details
  
  (2) Toyota Prius
  $27000
  Mileage: 66000
  View details
  
  (3) Tesla Model S
  $130000
  Mileage: 56000
  View details
  
  (4) Nissan Versa
  $16000
  Mileage: 94000
  View details
  
  (5) Toyota Camary
  $29000
  Mileage: 310000
  View details
  
  (6) Honda Accord
  $24000
  Mileage: 49000
  View details

If an integer parameter is left empty (limit or cacheMinutes) be sure to leave a placeholder of the word "null" or an error will result. Empty single quotes is also a valid entry.
If an array parameter is left empty (query or sort) be sure to leave a placeholder of empty brackets "[]".

Tip

We're using the $array_position function to return the position of a supplement record in the rendered array. Helpful when debugging and for referencing a specific array index. Should be left out of the final campaign message renders.

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)

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 here.

You can retrieve the supplement key two 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.

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.

Set the query

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

Only indexed fields within supplements can be used for query filters. Email and cID become indexed by default when the supplement is used as a contact attribute.

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 $33,000.

{$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]]]}

Return records 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'}]]

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}

If the limit parameter is left blank, 25 will be used as a default for the number of records a call returns.

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']}

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".

The first item of an array is referenced by "0", the second is "1", the third is "2", etc.

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.

• {$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"
      }
    ]

• Special offer for you, Fred! 

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're 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.

• {$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}

• Cars from your favorites collection:

  Honda Pilot
  $33000
  Mileage: 100000
  View details
  
  Ford Explorer
  $34000
  Mileage: 39000
  View details
  
  Toyota Prius
  $27000
  Mileage: 66000
  View details