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}}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
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}}Last updated