@shferreira/brazejs

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