brazejs

A braze compatible Liquid template engine in pure JavaScript. Built on top of liquidjs, with Braze tags/filters/syntax added and incompatible features removed.

Install via npm:

npm install --save brazejs

For detailed usage please refer to liquidjs' original doc.

Difference with liquidjs

Braze's liquid is a subset of Shopify's liquid, hence some incompatible features have to be removed. Braze also has it's own support for some Braze specific tags/filters/output, we add them in as plugin to liquidjs.

Removed

• filters

  • abs: Braze doesn't support abs

Added

• Filters

  • Encoding

    | Filter Name | Example | Notes | | --- | --- | --- | | md5 | {{"sample" \| md5}} | | | sha1 | {{"strings" \| sha1}} | | | sha2 | {{"to" \| sha2}} | This is using SHA-256 | | hmac_sha1 | {{"be" \| hmac_sha1}} | | | base64 | {{"encoded" \| base64}} | |

  • URL

    | Filter Name | Example | Notes | | --- | --- | --- | | url_escape | {{"hey<>hi" \| url_escape}} | ⚠️ this uses encodeURI which is slightly different from Braze's implementation | | url_param_escape | {{"hey<>hi" \| url_param_escape}} | ⚠️ this uses encodeURIComponent which is slightly different from Braze's implementation |

  • Property Accessor

    | Filter Name | Example | Notes | | --- | --- | --- | | property_accessor | {{hash \| property_accessor: 'key'}} | Example hash: { 'key' => 'hello' } |

  • Number Formatting

    | Filter Name | Example | Notes | | --- | --- | --- | | number_with_delimiter | {{123456 \| number_with_delimiter}} | ⚠️ this uses toLocaleString which is slightly different from Braze's implementation |

  • JSON Escape

    | Filter Name | Example | Notes | | --- | --- | --- | | json_escape | {{'123"456' \| json_escape}} | ⚠️ this uses JSON.stringify which is slightly different from Braze's implementation |

• Tags

  • abort_message: abort rendering and output an optional message

    Example:

    {% abort_message() %}
    {% abort_message('aborted due to error') %}

  • connected_content: call an external API

    Example:

    {% connected_content http://numbersapi.com/random/trivia :save trivia :cache 900 :basic_auth <secret_name> %}

    Supported options: :basic_auth, :content_type, :save, :cache, :method, :body

    For basic auth to work, you'll need to add the username and password into the context object.

    // replace <secret_name> so that it matches your basic auth name in Braze 
    {
        "__secrets": {
            "<secret_name>": {
                "username": "<your username>",
                "password": "<your password>"
            }
        }
    }

• Output

  • ${} support for Personalization tags

    For it to work the attributes need to be added into context

    {
        "first_name": "<my_name>",
        "user_id": "<my_uid>",
        "custom_attribute": {
            "<attr1>": "<val1>",
            "<attr2>": "<val2>"
        }
    }

    Then you can access them in the template:

    {{ ${first_name} }}
    {{ custom_attribute.${attr1} }}

  • Object will be converted to Ruby presentation

    If context is { "obj": {"foo": "bar"} }, liquidjs renders to [object Object], while brazejs renders it to {"foo"=>"bar"}

• Content blocks

  • Content Blocks is supported

    {{content_blocks.${contentBlockName}}}

    By default the content blocks template is being searched in directories in following order:

      1. current dir
      2. content_blocks under current dir
      3. content_blocks in parent dir
            

    It will also search for file names in this order:

      1. exact match
      2. convert file name to kebab-case
      3. append .liquid
      4. convert file name to kebab-case and append .liquid
            

    It's also possible to configure the root dir and file extension in context:

      {
          "__contentBlocks": {
              "root": "path_to_dir",
              "ext": ".html"
          }
      }
        

    ⚠️ At time of writing, Braze only support nesting 2 levels of content blocks

Use cases

• Together with differencify to do visual test for your Braze templates
• Use in VSCode Extension for easier local development