How can we help?

Get products (getProducts method)

Overview

The data stored within the products collection can be referenced and used within any message body.

Our example

For our example, we'll be using hypothetical product data. In order to test in your system, you'll need to add your own product data via the API.

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

  • {$products=$utils->getProducts()}
    {foreach $products as $product}
    <strong>{$product.productName|capitalize}</strong> - ${$product.price}<br><br>
    {foreach $product.variants as $variant}
    Color: {$variant.attr.color}<br>
    Size: {$variant.attr.size}<br>
    Sku: {$variant.sku}<br><br>
    {/foreach}
    {/foreach}
  • [
      {
          "productID": "1172",
          "productName": "skirt",
          "price": 19.99,
          "variants": [
            {
              "sku": "111",
              "attr": {
                "color": "blue",
                "size": "small"
              }
            },
              {
              "sku": "112",
              "attr": {
                "color": "blue",
                "size": "medium"
              }
            }
          ]
        },
      {
          "productID": "1173",
          "productName": "shorts",
          "price": 29.99,
          "variants": [
            {
              "sku": "221",
              "attr": {
                "color": "green",
                "size": "small"
              }
            },
            {
              "sku": "222",
              "attr": {
                "color": "green",
                "size": "medium"
              }
            }
          ]
        },
      {
          "productID": "1174",
          "productName": "pants",
          "price": 39.99,
          "variants": [
            {
              "sku": "331",
              "attr": {
                "color": "blue",
                "size": "small"
              }
            },
              {
              "sku": "332",
              "attr": {
                "color": "blue",
                "size": "medium"
              }
            }
          ]
       }
      ]
  • Skirt - $19.99

    Color: blue
    Size: small
    Sku: 111

    Color: blue
    Size: medium
    Sku: 112

    Shorts - $29.99

    Color: green
    Size: small
    Sku: 221

    Color: green
    Size: medium
    Sku: 222

    Pants - $39.99

    Color: blue
    Size: small
    Sku: 331

    Color: blue
    Size: medium
    Sku: 332

The getProducts method

In order to access product data within a message, use the getProducts method, which is a custom extension of Smarty provided by Cordial.

The getProducts method has 4 optional parameters: query, limit, sort and cacheMinutes. They must be written in this order and separated by commas. 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).

getProducts($query,$limit,$sort,$cacheMinutes)

Parameters Description Required Expected Default
query A filter used to limit the data set. 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. 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 write the getProducts method

{$products=$utils->getProducts()}

In the example above, a variable "products" is assigned to the resulting data set returned from the product collection. The getProducts method will get the data from the products collection for each message that is rendered per contact.

Set the query

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

Return records filtered by a specified value

["key"=>"value"]

Example:

{$products=$utils->getProducts(["productName"=>"shorts"])}

Return records filtered by multiple specified values

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

Example:

{$products=$utils->getProducts(["productName"=>"shorts","size"=>"medium"])}

Return records filtered by multiple specified values of the same key

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

Example:

{$products=$utils->getProducts(["productID"=>["in" => [123,124]]])}

Return records not in the specified array

{$products=$utils->getProducts(["productID"=>["notIn" => [123,124]]])}

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:

{$products=$utils->getProducts(["price"=>["lt"=>39]])}
  {$products=$utils->getProducts(["price"=>["gt"=>29]])}
  {$products=$utils->getProducts(["price"=>["gte"=>49]])}

Return records filtered by values between two numbers

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

Example:

{$products=$utils->getProducts(["price"=>["between"=>["start"=>10,"end"=>30]]])}

Set the limit

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

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

{$products=$utils->getProducts([],5)}

If an array parameter is left empty (query in this example) be sure to leave a placeholder of empty brackets "[]" or an error will result.

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

{$products=$utils->getProducts(["price"=>40],5)}

Sort the data

Sort results by price in an ascending order

{$products=$utils->getProducts([],null,['column'=>'price','direction'=>'ASC'])}

Sort results by price in an descending order

{$products=$utils->getProducts([],null,['column'=>'price','direction'=>'DESC'])}

If an integer parameter is left empty (limit in this example) be sure to leave a placeholder of the word "null" or an error will result. Empty single quotes is also a valid entry.

Set the cacheMinutes

A cache can be set in memory for the data so the system doesn't have to request the data for every individual message. This optimizes the time it takes to compile and send a message. You can specify the number of minutes that the data is stored in memory with this parameter.

{$products=$utils->getProducts([],null,[],20)}

Render the data in a message

After the data is available with the getRecords 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:

{$products=$utils->getProducts()}
{foreach $products as $product}
<strong>{$product.productName|capitalize}</strong> - ${$product.price}<br><br>
{foreach $product.variants as $variant}
Color: {$variant.attr.color}<br>
Size: {$variant.attr.size}<br>
Sku: {$variant.sku}<br><br>
{/foreach}
{/foreach}

Variants are stored as an array. You can use a nested {foreach} in order to loop through each of the variant items per product.

Reference an index of the array

You also have to option to target the "nth" item within an array using it's index. For example, if you only wanted to render the first variant of each product you would write:

{$products=$utils->getProducts()}
{foreach $products as $product}
<strong>{$product.productName|capitalize}</strong> - ${$product.price}<br><br>
Color: {$product.variants[0].attr.color}<br>
Size: {$product.variants[0].attr.size}<br>
Sku: {$product.variants[0].sku}<br><br>
{/foreach}

This example will look in the 1st variant of the variant array and render the values for "color", "size" and "sku".

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

In the next article, you can learn about getting order data.

Comments

0 comments

Please sign in to leave a comment.