These functions are available in bot scripts and snippets:
- array_column
- array_combine
- array_diff
- array_extract_keys
- array_intersect
- array_matches
- array_sort_keys
- array_unique
- array_values
- attribute
- cerb_avatar_image
- cerb_avatar_url
- cerb_file_url
- cerb_has_priv
- cerb_placeholders_list
- cerb_record_readable
- cerb_record_writeable
- cerb_url
- cycle
- date
- clamp_float
- clamp_int
- dict_set
- dict_unset
- json_decode
- jsonpath_set
- max
- min
- random
- random_string
- range
- regexp_match_all
- shuffle
- validate_email
- validate_number
- xml_decode
- xml_encode
- xml_xpath
- xml_xpath_ns
- References
array_column
(Added in 9.2.1)
The array_column function extracts a column from the elements of an array:
{% set people = [
{"id": 1, "name": "Kina Halpue", "email": "kina@cerb.example"},
{"id": 2, "name": "Milo Dade", "email": "milo@cerb.example"},
{"id": 3, "name": "Janey Youve", "email": "janey@cerb.example"},
] %}
The email addresses are: {{array_column(people,'email')|join(', ')}}
The email addresses are: kina@cerb.example, milo@cerb.example, janey@cerb.example
array_combine
(Added in 9.0)
The array_combine function creates a new array with the given keys
and values
:
{% set keys = ['name', 'age', 'email'] %}
{% set values = ['Janey Youve', '30-ish', 'janey@cerb.example'] %}
{% set person = array_combine(keys, values) %}
{{person.name}} can be reached at {{person.email}}
Janey Youve can be reached at janey@cerb.example
array_diff
The array_diff function returns the items in the second array that are not present in the first array:
{% set arr1 = ['Apple', 'Google', 'Microsoft'] %}
{% set arr2 = ['Apple', 'Microsoft', 'Cerb'] %}
{% set diff = array_diff(arr2, arr1) %}
These are new: {{diff|join(', ')}}
These are new: Cerb
array_extract_keys
(Added in 9.6.4)
Returns the given keys from all elements of a list.
{% set records = [
{
id: 1,
subject: "Help with the API",
status: "open",
sender: "customer@cerb.example",
},
{
id: 2,
subject: "Automating email replies",
status: "open",
sender: "customer@cerb.example",
}
] %}
Sender,Subject,Status
{{array_extract_keys(records, ['sender','subject','status'])|csv}}
Sender,Subject,Status
customer@cerb.example,"Help with the API",open
customer@cerb.example,"Automating email replies",open
array_intersect
(Added in 9.0)
Returns a new array for all the elements in array1 that are also present in array2. This is the opposite of array_diff.
{% set arr1 = ['Apple', 'Google', 'Microsoft'] %}
{% set arr2 = ['Apple', 'Microsoft', 'Cerb'] %}
{% set intersect = array_intersect(arr2, arr1) %}
These are in both: {{intersect|join(', ')}}
These are in both: Apple, Microsoft
array_matches
(Added in 9.6.4)
Compares an array of values to an array of patterns.
{% set recipients = ['support@cerb.example','sales@cerb.example'] %}
{% set patterns = ['sales@*'] %}
{% set results = array_matches(recipients, patterns) %}
Matches: {{results|join(', ')}}
Matches: sales@cerb.example
array_sort_keys
(Added in 9.0)
Sort an associative array by its keys rather than its values.
{% set arr = {"z":"A", "a":"B", "m":"C"} %}
{% set arr = array_sort_keys(arr) %}
{{arr|keys|join(',')}}
a,m,z
array_unique
(Added in 9.0)
Return a new array with only the distinct values from the array
argument.
{% set arr = [1,1,2,2,3,3,4,4,5,5,6] %}
Unique values {{array_unique(arr)|join(',')}}
Unique values 1,2,3,4,5,6
array_values
(Added in 9.0)
Return the values from an associative array as a new indexed array. For instance, this can affect the output in JSON encoding by using []
rather than {key:value}
.
{% set arr = {"z":"A", "a":"B", "m":"C"} %}
{{array_values(arr)|json_encode}}
["A","B","C"]
attribute
Access the values of an object with a variable key:
{% set person = {"first_name": "Kina", "last_name": "Halpue", "title": "Customer Support Supervisor"} %}
{% set key = 'title' %}
{{attribute(person, key)}}
Customer Support Supervisor
cerb_avatar_image
Retrieve the avatar image for a given record type and ID.
cerb_avatar_image(record_type, id, updated)
{{cerb_avatar_image('worker','1','now'|date('U'))}}
<img src="https:/cerb.example/avatars/worker/1?v=1513212603" style="height:16px;width:16px;border-radius:16px;vertical-align:middle;">
cerb_avatar_url
Retrieve the avatar image URL for a given record type and ID.
cerb_avatar_url(record_type, id, updated)
{{cerb_avatar_url('worker','1','now'|date('U'))}}
https://cerb.example/avatars/worker/1?v=1513212702
cerb_file_url
Retrieve the download link for a given attachment ID.
This automatically adapts to use within Cerb and community portals (e.g. SSL, proxies).
cerb_file_url(id)
{{cerb_file_url('1')}}
https://cerb.example/files/1/original_message.html
cerb_has_priv
(Added in 9.0)
Returns a boolean depending on whether the given actor has the given privilege among their roles. If no actor is given, the current worker is assumed. This allows bot functionality, snippets, and widgets, to adapt based on worker permissions. This is particularly useful in HTML-based profile widgets.
{% if cerb_has_priv('contexts.cerberusweb.context.ticket.create', 'worker', 1) %}
Worker #1 has permission to create tickets.
{% endif %}
Worker #1 has permission to create tickets.
cerb_placeholders_list
Return an object with every placeholder in the current behavior.
{{cerb_placeholders_list()|json_encode|json_pretty}}
{
"worker__context": "cerberusweb.contexts.worker",
"worker__loaded": true,
"worker__label": "Kina Halpue",
"worker__image_url": "https://cerb.example/avatars/worker/1?v=1512582324",
"worker_at_mention_name": "Kina",
"worker_calendar_id": 7,
"worker_dob": null,
"worker_id": 1,
"worker_first_name": "Kina",
"worker_full_name": "Kina Halpue",
"worker_gender": "F",
"worker_is_disabled": 0,
"worker_is_superuser": 1,
"worker_language": "en_US",
"worker_last_name": "Halpue",
"worker_location": "",
"worker_mobile": "15555555555",
"worker_phone": "",
"worker_time_format": "D, d M Y h:i a",
"worker_timezone": "America/Los_Angeles",
"worker_title": "Customer Support",
"worker_updated": 1512582324,
"worker_record_url": "https://cerb.example/profiles/worker/1-Kina-Halpue",
...
}
cerb_record_readable
(Added in 9.0)
Returns a boolean if the given actor has read access to the given record. If no actor is provided then the current worker is assumed. This allows bots and widgets to adapt based on record permissions. For instance, an HTML widget on a profile dashboard could only show a button to workers who can modify the record.
{% if cerb_record_readable('ticket', 123, 'worker', 1) %}
Worker #1 can read ticket #123.
{% endif %}
Worker #1 can read ticket #123.
cerb_record_writeable
(Added in 9.0)
Returns a boolean if the given actor has write access to the given record. If no actor is provided then the current worker is assumed. This allows bots and widgets to adapt based on record permissions. For instance, an HTML widget on a profile dashboard could only show a button to workers who can modify the record.
{% if cerb_record_writeable('ticket', 123, 'worker', 1) %}
Worker #1 can modify ticket #123.
{% endif %}
Worker #1 can modify ticket #123.
cerb_url
Retrieve a full URL to a page or resource in Cerb.
This automatically adapts to use within Cerb and community portals (e.g. SSL, proxies).
{{cerb_url("c=profiles&type=ticket&id=5")}}
https://cerb.example/profiles/ticket/5
cycle
Round-robin through a sequence.
{% set options = ['odd','even'] %}
{% for n in 1..10 %}
* {{cycle(options, n)}}
{% endfor %}
* even
* odd
* even
* odd
* even
* odd
* even
* odd
* even
* odd
date
Create a date object for use with the date_modify filter.
{% set d = date('1-Jan-2018 10:00am') %}
{{d|date_modify('+2 hours')|date('F d, Y g:ia')}}
January 01, 2018 12:00pm
clamp_float
Set the range boundaries for a decimal value.
{{clamp_float(-105.19,0,100)}}
0
clamp_int
Set the range boundaries for an integer value.
{{clamp_int(110,-90,90)}}
90
dict_set
You can use the dict_set function to quickly add, modify, or append items in an array or object.
You can set deeply nested keys in a single line using dot-notation:
{% set var = {"group": {}} %}
{% set var = dict_set(var, 'group.name', 'Support') %}
{% set var = dict_set(var, 'group.manager.name.first', 'Kina') %}
{% set var = dict_set(var, 'group.manager.name.last', 'Halpue') %}
{{var|json_encode|json_pretty}}
{
"group": {
"name": "Support",
"manager": {
"name": {
"first": "Kina",
"last": "Halpue"
}
}
}
}
Append items to an array by adding .[]
to the key:
{% set var = {"group": {}} %}
{% set var = dict_set(var, 'group.name', 'Support') %}
{% set var = dict_set(var, 'group.members.[]', 'Kina Halpue') %}
{% set var = dict_set(var, 'group.members.[]', 'William Portcullis') %}
{% set var = dict_set(var, 'group.members.[]', 'Steven Emplois') %}
{{var|json_encode|json_pretty}}
{
"group": {
"name": "Support",
"members": [
"Kina Halpue",
"William Portcullis",
"Steven Emplois"
]
}
}
Append to nested arrays:
{% set var = [1,2,[3,4,[5,6]]] %}
{% set var = dict_set(var, '2.2.[]', 7) %}
{% set var = dict_set(var, '2.2.[]', 8) %}
{% set var = dict_set(var, '2.3', 9) %}
{{var|json_encode|json_pretty}}
[
1,
2,
[
3,
4,
[
5,
6,
7,
8
],
9
]
]
dict_unset
You can use the dict_unset function to remove items by key from an array or object.
You can unset deeply nested keys in a single line using dot-notation:
{% set person = {"person":{"name":{"first":"Jane","last":"Tester"},"age":28,"location":"Secret"}} %}
{% set person = dict_unset(person, ['person.name.last','person.age','person.location']) %}
{{person|json_encode|json_pretty}}
{
"person": {
"name": {
"first": "Jane"
}
}
}
json_decode
You can decode a JSON-encoded string with the json_decode function:
{% set json_string = "{\"name\":\"Joe Customer\",\"order_id\":12345}" %}
{% set json = json_decode(json_string) %}
Customer: {{json.name}}
Order #: {{json.order_id}}
Customer: Joe Customer
Order #: 12345
This returns an object.
jsonpath_set
This is nearly identical to dict_set.
{% set json_string = "{\"name\":\"Joe Customer\",\"order_id\":12345}" %}
{% set json = json_decode(json_string) %}
{% set json = jsonpath_set(json, 'order_id', '67890') %}
{{json.order_id}}
67890
You can specify an array by appending []
without a leading dot (.
):
{% set json_string = "{\"team\":{\"groups\":[]}}" %}
{% set json = json_decode(json_string) %}
{% set json = jsonpath_set(json, 'team.groups[]', 'Support') %}
{% set json = jsonpath_set(json, 'team.groups[]', 'Sales') %}
{% set json = jsonpath_set(json, 'team.groups[]', 'Development') %}
{{json|json_encode|json_pretty}}
{
"team": {
"groups": [
"Support",
"Sales",
"Development"
]
}
}
max
Return the largest value in an array or object.
{% set numbers = [1,9,8,4,2] %}
{{max(numbers)}}
9
min
Return the smallest value in an array or object.
{% set numbers = [1,9,8,4,2] %}
{{max(numbers)}}
1
random
Return a random item from a string or array, or a random number between 0 and the given number (inclusive).
{{random([1,2,3,4,5,6,7,8,9,0])}}
{{random("abcdefghijklmnopqrstuvwxyz")}}
{{random(20)}}
9
o
17
random_string
Generate a random string of the given length. This is useful for generating confirmation codes or temporary passwords.
{{random_string(16)}}
61AE3XG3ZMW8QDTM
range
Return an array with values between from
and to
(inclusive).
range(from,to,step)
{{range(5,15)|json_encode}}
{{range(5,15,2)|json_encode}}
[5,6,7,8,9,10,11,12,13,14,15]
[5,7,9,11,13,15]
regexp_match_all
regexp_match_all(pattern, string, group)
{% set headers =
"X-Mailer: Cerb
From: customer@cerb.example
To: support@cerb.example
"
%}
{% set results = regexp_match_all("#^(.*?): (.*?)$#m", headers) %}
{{results|json_encode|json_pretty}}
[
[
"X-Mailer: Cerb",
"From: customer@cerb.example",
"To: support@cerb.example"
],
[
"X-Mailer",
"From",
"To"
],
[
"Cerb",
"customer@cerb.example",
"support@cerb.example"
]
]
shuffle
Randomize an array:
{{shuffle([1,2,3,4,5])|json_encode}}
[2,4,5,1,3]
validate_email
Validate an email address:
{{validate_email('kina')|json_encode}}
{{validate_email('kina#cerb.example')|json_encode}}
{{validate_email('kina@cerb.example')|json_encode}}
false
false
true
validate_number
Validate a number:
{{validate_number('abcde')|json_encode}}
{{validate_number('20.f')|json_encode}}
{{validate_number(10)|json_encode}}
{{validate_number('123.45')|json_encode}}
false
false
true
true
xml_decode
You can decode an XML1 string into an XML object with the xml_decode function.
Use the xml_xpath function to extract values with XPath2 queries.
xml_decode(xml_string,namespaces,mode)
- xml_string: The string of XML to convert into an object.
- namespaces: An optional array of namespaces.
- mode: Use
html
to convert an HTML DOM into an XML document.
{% set string_of_xml =
"<response>
<client_id>1</client_id>
<invoice_id>123</invoice_id>
</response>"
-%}
{% set xml = xml_decode(string_of_xml) %}
{{xml_encode(xml)}}
<?xml version="1.0"?>
<response>
<client_id>1</client_id>
<invoice_id>123</invoice_id>
</response>
xml_encode
You can encode an object as XML with the xml_encode function:
{% set string_of_xml =
"<response xmlns=\"http://www.example.com/api/\">
<client_id>1</client_id>
<invoice_id>123</invoice_id>
</response>"
-%}
{% set xml = xml_decode(string_of_xml) %}
{{xml_encode(xml.client_id)}}
<client_id>1</client_id>
xml_xpath
Use the xml_xpath function to extract values with XPath2 queries:
{% set string_of_xml =
"<response>
<client_id>1</client_id>
<invoice_id>123</invoice_id>
</response>"
-%}
{% set xml = xml_decode(string_of_xml) %}
{% set client_id = xml_xpath(xml, '//client_id')|first %}
{% set invoice_id = xml_xpath(xml, '//invoice_id')|first %}
Client ID: {{client_id}}
Invoice ID: {{invoice_id}}
Client ID: 1
Invoice ID: 123
xml_xpath_ns
You can define an XML namespace with the xml_xpath_ns function:
{% set string_of_xml =
"<response xmlns=\"http://www.example.com/api/\">
<client_id>1</client_id>
<invoice_id>123</invoice_id>
</response>"
-%}
{% set xml = xml_decode(string_of_xml) %}
{% set xml = xml_xpath_ns(xml, 'ns', 'http://www.example.com/api/') %}
{% set client_id = xml_xpath(xml, '//ns:client_id')|first %}
{% set invoice_id = xml_xpath(xml, '//ns:invoice_id')|first %}
Client ID: {{client_id}}
Invoice ID: {{invoice_id}}
Client ID: 1
Invoice ID: 123
References
-
Wikipedia: XML - https://en.wikipedia.org/wiki/XML ↩
-
Wikipedia: XPath - https://en.wikipedia.org/wiki/XPath ↩ ↩2