Skip to content
/ brazejs Public

A Braze compatible Liquid template engine in pure JavaScript.

License

Notifications You must be signed in to change notification settings

yq314/brazejs

Repository files navigation

brazejs

npm npm Build Status Coveralls GitHub issues David David Dev DUB Commitizen friendly semantic-release

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, :headers

      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"
            }
        }
      

      If your content blocks are in more than one roots, you can set an array as the root. Please make sure you give your content blocks different names, otherwise only the first matching content block will be used.

        {
            "__contentBlocks": {
                "root": ["path1", "path2"],
                "ext": ".html"
            }
        }
      

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

Use cases