Skip to main content

Control Flow

Overview​

In addition to their standard properties, Courier elements have a few additional properties that allow you to apply control flow logic to the element.

Each control flow property is optional.

If​

Allows an element to be conditionally rendered.

Applies to: text, meta, channel, group, action, image.

Examples​

Basic usage:

{
  "type": "text",
  "content": "Hello, {{first_name}} {{last_name}}",
  "if": "data.some_field === 3"
}

Ref​

Allows an element to be named and referenced by other elements.

Elements that reference other elements have access to:

  • The properties of that element
  • A visible property which is set to true when the element is visible in the final render and false otherwise.

Note: An element cannot reference another before it is defined.

Applies to: text, meta, channel, group, action, image.

Examples​

Basic usage:

{
  "type": "text",
  "content": "Hello, {{first_name}} {{last_name}}",
  "ref": "el3"
},
{
  "type": "text",
  "content": "Hello **world**",
  "if": "refs.el3.visible"
}

Loop​

Allows an element to be rendered multiple times based on an iterable data source.

The "loop" field must always evaluate to an iterable data source. The value of each item in the iterable data source will be available to the "content" field as $.item.

To access the current index of the loop, use $.index.

The handlebars renderer of the content fields includes a number of math helpers that can be used to assist rendering. These include:

  • add (ex. {{add 1 2}})
  • subtract (ex. {{subtract 1 2}})
  • divide (ex. {{divide 1 2}})
  • multiply (ex. {{multiply 1 2}})
  • abs (ex. {{abs -1}})
  • ceil (ex. {{ceil 1.1}})
  • mod (ex. {{mod 1 2}})
  • round (ex. {{round 1.1}})
  • floor (ex. {{floor 1.1}})

This is especially useful when using the $.index field. I.E. Item no {{add $.index 1}}.

Applies to: text, channel, group, action, image.

Examples:​

Basic usage:

{
  "type": "text",
  "content": "* {{$.item.name}} listed at {{$.item.price}}",
  "loop": "data.products"
}

In the above example the full message payload would look something like this:

{
  "message": {
    "content": {
      "version": "2022-01-01",
      "elements": [
        {
          "type": "text",
          "content": "* {{$.item.name}} listed at {{$.item.price}}",
          "loop": "data.products"
        }
      ]
    },
    "data": {
      "products": [
        {
          "name": "Mouse",
          "price": "$10"
        },
        {
          "name": "Keyboard",
          "price": "$20"
        }
      ]
    }
  }
}

In which case the text element would be expanded to this:

{
  "type": "text",
  "content": "* Mouse listed at $10",
  "loop": "data.products"
},
{
  "type": "text",
  "content": "* Keyboard listed at $20",
  "loop": "data.products"
}

Channels​

Allows an element to be selectively rendered based on the current channel.

Channels is an array of valid channels to restrict the element to. Valid channels include email, push, direct_message, sms or a provider channel such as slack.

Applies to: text, meta, channel, group, action, image.

Examples​

{
  "type": "text",
  "content": "Hello, {{first_name}} {{last_name}}",
  "channels": ["email", "slack"]
}
Was this helpful?