Brazejs NPM | npm.io

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

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][braze/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