This documentation is for our legacy platform hosted at mtag.io. If you are using the Object Manager and Studio hosted at bluebite.com, see our Updated Documentation.
Macro Overview
Overview
Blue Bite Macros are used in Studio experiences to create rich experiences by referencing dynamic data points or transforming existing data points or user input. This page outlines the syntax and overall rules governing how to use all types of Macros.
You can also check out the tutorial What are Blue Bite Studio Macros? and see a List of Macros.
Parts of a Macro
Macros are written in the Studio as a single expression surrounded by double curly braces {{ }}. Typically, they will reference a object's properties via the access operator :. Multiple access operators can be used to continually index into nested objects. Aside from object references, Macros can also contain numbers, string literals, operators, and/or functions.
Numbers
Any numeric expression inside a Macro will be treated as a number. Numbers can be used in conjunction with arithmetic and comparative operators.
{{ 1 + 1 }} → 2
String Literals
Double straight quotes " " inside a Macro denote that the text between those quotes is a string literal and not a reference. This is particularly useful with the fallback operator.
{{ "red" }} → red
String Interpolation
The Macro operator can be used inside a string literal.
{{ "This shoe is {{ tag:data:color }}" || "Can’t find this item" }}
When tag:data:color is green → This shoe is green
When tag:data:color does not exist → Can’t find this item
Operators
Macro Operator
The Macro operator {{ }} indicates that any text inside double curly braces should be treated as a acro and not as a.
Access Operator
In order to return the correct value, most Macros use objects and properties separated by the access operator :. The example below demonstrates how to use the access operator to reference the mtag_id property from a tag object.
{{ tag:mtag_id }} → 0123456789
In some cases, custom properties may have characters which are not supported in the Macro syntax. For example, properties that begin with a number or that have spaces. The example below demonstrates how string literals and the access operator can be used to create a valid expression.
{{ tag:data:"shoe color" }} when custom tag:data property shoe color exists and is green → green
{{ tag:data:shoe color }} has two expressions, {{ tag:data:shoe }} and {{ color }} the latter is not a recognized Macro expression → Error
It is even possible to use a reference as a key. Notice how parentheses are used to establish precedence.
{{ tag:data:(tag:data:color) }} when tag:data:color is green → {{ tag:data:green }}
Fallback Operator
A fallback value specified in a Macro displays if a reference is unavailable, or an expression is malformed. Add a fallback operator || to the Macro, followed by a fallback value — which is an expression, usually a string literal.
{{ tag:data:color || "red" }}
- When tag:data:color is green → green
- When tag:data:color does not exist → red
- When the key tag:data:color exists, but the value is empty → Empty String
Fallbacks can also be used for expressions that produce errors. In the example below, the Macro {{ tag:data:color }} is interpolated into a string and will either return the value or an error. A fallback value can be provided for the error cases.
{{ "This shoe is {{ tag:data:color }}" || "Can’t find this item" }}
- When tag:data:color is green → This shoe is green
- When tag:data:color does not exist → Can’t find this item
Tip: Notice how the Macro operators {{ }} are used inside a string literal to escape the string and return the respective value. This is covered in the string interpolation section.
Arithmetic Operators
In a Macro, basic mathematical operations can be performed on numeric expressions.
{{ 1 + 1 }} → 2
List of Arithmetic Operators
Using String Literals in Arithmetic Operators
When arithmetic operators are used with string literals, the Macro will try to coerce the string into a number. Adding a string literal that does not contain a number will result in an error.
{{ "1" + 1 }} → {{ 1 + 1 }} → 2
Comparative Operators
In a Macro, comparative operators perform comparisons between strings, numbers, or booleans, returning either a true or a false value. Unlike arithmetic operators, comparative operators will not coerce a string into a number.
{{ "hello" == "hello" }} → true
{{ "1" == 1 }} → false
List of Boolean Operators
Escape Operator
Use a backslash \ to escape most reserved characters inside a Macro expression. Prepending opening braces with \ will escape the entire Macro expression and show double curly braces as a string.
My Shoe Is \{{ tag_data:shoe_color }}! → My Shoe Is {{ tag_data:shoe_color }}!
{{ "Hell\"o" }} → Hell"o
{{ "Hell\\o" }} → Hell\o
{{ "Hello\" }} → Error, opening quote is not closed.
Functions
Functions are a specific type of Macros that take inputs and return a value or object. Functions, once called, may return a value or a JSON object whose properties can be indexed-into with the access operator :.
{{ Address:from_location(Location:get("ip",{})) }} → Address Object
"Address":{
"_type":"Address",
"street":"121 E 24TH",
"city":"New York",
"postal_code":"10010",
"state":{
"_type":"State",
"code":"NY"
},
"Country"{
"_type":"Country",
"name":"United States",
"code":"US"
}
}
{{ Address:from_location(Location:get("ip",{})):country:code }} → US
Click here for a list of supported functions.
Order of Operations
Parenthesis
Parentheses are used to ensure that part of a Macro expression evaluates before another.
{{ (tag:data:color_1 || tag:data:color_2) || "red" }}
Special Characters & URL Safe String
Values must be converted to be a URL safe string. There are two sets of characters to watch out for: reserved and unsafe.
List of Reserved Characters
List of Unsafe Characters
Array Processing
The values in this array can be access in a number of ways. Suppose a Studio form (component ID 1) returned this value via API
{{ Form:get("1"):response:body }}
{
"shoes":[
{
"sku":"001",
"name":"Men's Green Boot",
"color":"Green",
"size":"11",
"gender":"Mens"
},
{
"sku":"002",
"name":"Women's Red Heel",
"color":"Red",
"size":"6",
"gender":"Womens"
},
{
"sku":"003",
"name":"Gray Trainer",
"color":"Gray",
"size":"8",
"gender":"Unisex"
}
]
}
Using index:
{{ Form:get("1"):response:body:shoes[0]:name }} → Men's Green Boot
Using search:
{{ Array:find("sku","001",Form:get("1"):response:body:shoes):name }} → Men's Green Boot
