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
Arithmetic Operator
Description
+
Addition
-
Subtraction
*
Multiplication
/
Devision
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
Arithmetic Operator
Description
==
Equals
!=
Not Equal To
<
Less Than
<=
Less Than or Equal To
>
Greater Than
>=
Greater Than or Equal To
AND
And
OR
Or

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

Character
Name
&
Ampersand
$
Dollar
+
Plus Sign
-
Dash
=
Equals Sign
*
Asterisk
/
Forward Slash
,
Comma
:
Colon
;
Semi-colon
?
Questionmark
@
At
#
Pound
OR
OR
XOR
Exclusive Or

List of Unsafe Characters

Character
Name
Space
<
Less Than Sign
>
Greater Than Sign
[ ]
Brackets
{ }
Braces
|
Pipe
\
Forward Slash
^
Caret
%
Percent

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