Filtering Arrays

findMatching Function

To filter array attributes according to specific criteria, you should use the #findMatching function. The syntax of the output of the values matching your criteria is dependent on the type of array it is used upon.

This function may be used to filter array attributes containing:

• Simple values, also referred to as primitives, which are values that have no properties: string("This is a string"), integer(2), float(5.6), datetime(1994-11-05T13:15:30Z), boolean(true).

• Objects, which are values with properties e.g. subscriptions

The syntax of this helper function is:

{{#findMatching '{
    "data": "[attribute]", 
    "criteria": [
        {
            "operator": "[operator]", 
            "value": "[value]"
        }
    ],
    "limit": [limit]
}'}}
  [output]
{{/findMatching}}

You may also use a combination of conditions in the criteria array. For example:

...
"criteria": [
        {
            "operator": "[operator]", 
            "value": "[value]"
        },
        {
            "operator": "[operator]", 
            "value": "[value]"
        }
    ]
...    

Property	Type	Description
attribute	string	The user or event attribute that is used for the verification. e.g. user.[traits.birthday], [properties.price]
operator	string	The operator that will be used to asses whether the criteria is met or not. e.g. ==. <=. See the list of all available operators and their compatibility below.
value	string	The value the attribute property will be compared against. e.g male, 0
limit	integer	Optional. The number of values matching your criteria that will be returned by the function. e.g. 1 will return the first value that matched your criteria.
output	string	Syntax dependent on the type of array the function is used upon. See the Simple attributes and Objects sections below, depending on your use case.

Simple Attributes

For simple values, you should use the helper function with the following syntax:

{{#findMatching '{
    "data": "[attribute]", 
    "criteria": [
        {
            "operator": "[operator]", 
            "value": "[value]"
        }
    ],
    "limit": 1
}'}}
    {{this}}   
{{/findMatching}}

To output the values that match your criteria, you should use {{this}}. {{this}} will output the value satisfying your given condition/s.

Use Cases

Display all devices from a given manufacturer

For this example, we output the first 2 values containing the brand name Apple. We use a user with the attribute below to display the result of the function:

traits.devices = [
    "Apple iPhone X","Apple iPad Pro","Samsung Galaxy S6", "Apple iPhone 5"
];

The syntax of the helper function with our selected criteria is:

<ul> Your Apple devices:
{{#findMatching '{
    "data": "user.[traits.devices]", 
    "criteria": [
        {
            "operator": "contains", 
            "value": "Apple"
        }
    ],
    "limit": 2
}'}}
    <li>{{this}}</li>
{{/findMatching}}
</ul>

Once the function is evaluated, it displays the following block in the section where it is used in the message:

<ul>
    <li>Apple iPhone X</li>
    <li>Apple iPad Pro</li>
</ul>

Objects

For object attributes, you should use the helper function with the following syntax:

{{#findMatching '{
    "data": "[attribute]", 
    "criteria": [
        {
            "operator": "[operator]", 
            "value": "[value]"
        }
    ],
    "limit": [limit]
}'}}
    {{[property]}}   
{{/findMatching}}

Property	Description
property	The property of the object/s matching your criteria. For example, when working with a subscription, this may be the startDate

You may output as many properties as needed from the object attribute matching your criteria.

Use Cases

Searching a list of subscriptions

For this example, we filter a user's subscriptions to find all of Pet Food subscriptions with deliveries scheduled in the next 7 days. The date used for the purpose of the calculation is 15/06/2018. To display the result of the function, we use an example user with the attribute below:

traits.subscriptions = [
    {
        "name": "Green Petfood InsectDog hypoallergenic - 15 kg",
        "category": "Pet Food",
        "deliveryDate": "2018-06-20"
    },
    {
        "name": "Ziwi Peak | Air Dried Dog Food Beef | 4 kg",
        "category": "Pet Food",
        "deliveryDate": "2018-06-21"
    }
];

Additionally, to display the subscription delivery date in our preferred format, we use the formatting function #computeDate. The syntax of the helper function with our selected criteria and date formatting is:

<h2>Your subscriptions with deliveries scheduled in the next 7 days:</h2>
{{#findMatching '{
    "data": "user.[traits.subscriptions]",
    "criteria": [
        {
            "property": "category",
            "operator": ">=",
            "value": "Pet Food"
        },
        {
            "property": "deliveryDate",
            "operator": "<",
            "value": "+7d"}
    ]
}'}} 
    <div class="subscription">
        <p>{{subscriptionName}}</p>
        <p> Delivering on: {{computeDate '{
            "dateTrait": "deliveryDate", 
            "outputFormat": "dd/mm/yyyy"
        }'}}</p>
        </div>
{{/findMatching}}

Once the function is evaluated, it displays the following block in the section where it is used in the message:

<h2>Your subscriptions with deliveries scheduled in the next 7 days:</h2>
<div class="subscription">
    <p>Green Petfood InsectDog hypoallergenic - 15 kg</p>
    <p> Delivering on: 20/06/2018</p>
</div>
<div class="subscription">
    <p>Ziwi Peak | Air Dried Dog Food Beef | 4 kg</p>
    <p> Delivering on: 21/06/2018</p>
</div>

Fetching a specific subscription from a user profile and searching the product feed for additional information

For this example, we filter a user's subscriptions to find the first Laundry Detergent subscription with a delivery scheduled in the next 7 days. The date used for the purpose of the calculation is 11/06/2018. To display the result of the function, we use an example user with the attribute below:

traits.subscriptions = [
    {
        "name": "Tide Pods Laundry Detergent Plus",
        "sku": "TD1215",
        "category": "Laundry Detergent",
        "deliveryDate": "2018-06-13"
    }
];

Additionally, to display additional information regarding the product included in the subscription, we use the product helper function #findProduct. The syntax of the helper function with our selected criteria and additional product information is:

{{#findMatching '{
    "data": "user.[traits.subscriptions]",
    "criteria": [
        {
            "property": "category",
            "operator": ">=",
            "value": "Laundry Detergent"
        },
        {
            "property": "deliveryDate",
            "operator": "<",
            "value": "+7d"}
    ],
    "limit": 1
}'}} 
    <div class="subscription">
        <h3>Delivering this week:</h3>
        <p>{{subscriptionName}}</p> 
        {{#findProduct {{sku}}}}
           <img src="{{properties.image}}">
        {{/findProduct}}
    </div>
{{/findMatching}}

Once the function is evaluated, it displays the following block in the section where it is used in the message:

<div class="subscription">
    <h3>Delivering this week:</h3>
    <p>Tide Pods Laundry Detergent Plus</p>
    <img src="https://crossengage.io/image/TidePods.jpg">
</div>

UTM Parameters are parameters added to URLs to track the effectiveness of online marketing campaigns. When a link containing UTM parameters is clicked, the parameters identify the marketing campaign which has led to the link being clicked. This information can be parsed using analytics tools to guide future marketing activities.

each Function

The #each handlebar can display a certain child within an array which cannot be accessed via the value mapping. While this function does not allow filtering itself, we can use it with the Conditional Functions to filter required results.

{{#each user.[traits.TRAIT-NAME}} {{CHILD-NAME}} {{/each}}

This will fetch the data which is in the array. However, it will fetch all of the selected fields when the fields are available multiple times.

You can use conditions inside of the loop to conditionally display the information:

{{#each user.[traits.NAME-HERE]}}
    {{#cif '{
        "property": "[ATTRIBUTE]",
        "operator": "OPERATOR",
        "value": "VALUE"}'
        }}
        {{ATTRIBUTE 1}}
        {{ATTRIBUTE 2}}
        
        {{else}}TEXT
    {{/cif}}
{{/each}}