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.
Learn more about uploading supplement records.
{$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" } ]
$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 array parameter is left empty (query or sort) be sure to leave a placeholder of empty brackets "[]".
$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.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 by either empty brackets "[]" for arrays or the word "null" for integers (empty single quotes should also work for integers).
getSupplementRecords($key, $query, $limit, $sort,$cacheMinutes)
Parameters | Description | Required | Expected | Default |
---|---|---|---|---|
key | A unique key created by the user for a stored supplement. | Required | Valid key | NA |
query | A filter used to limit the data set. Only indexed fields can be queried. | Optional | Array | [] |
limit | A filter that sets a maximum number of records to return. | Optional | Integer | 25 |
sort | Sort the order of the records returned. ASC (ascending), DESC (descending), LM (last modified), CT (created). | Optional | Array | [] |
cacheMinutes | Number of minutes to store the feed data in memory. This optimizes send time if the system doesn't have to request the feed for every individual message. | Optional | Integer | 0 |
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}
Rendering the Data in a Message
After the data is available with the getSupplementRecords method, you can render the data in the message.
Looping 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.
Referencing 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".
Using 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}
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
Comments
0 comments
Please sign in to leave a comment.