brazejs


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

Install via npm:

``bash
npm install --save brazejs
`

For detailed usage please refer to [liquidjs][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][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][braze/abort_message]: abort rendering and output an optional message

Example:
`
{% abort_message() %}
{% abort_message('aborted due to error') %}
`

* [connected_content][braze/connected_content]: call an external API

Example:
`
{% connected_content http://numbersapi.com/random/trivia :save trivia :cache 900 :basic_auth %}
`

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][liquidjs/context] object.
`
// replace so that it matches your basic auth name in Braze
{
"__secrets": {
"": {
"username": "",
"password": ""
}
}
}
`

* #### Output
* ${} support for [Personalization tags][personalization tags]

For it to work the attributes need to be added into [context][liquidjs/context]

`
{
"first_name": "",
"user_id": "",
"custom_attribute": {
"": "",
"": ""
}
}
`
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][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][liquidjs/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

[braze/liquid]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/overview/
[tutorial]: https://shopify.github.io/liquid/basics/introduction/
[liquidjs]: https://github.com/harttle/liquidjs
[personalization tags]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags/
[liquidjs/context]: https://github.com/harttle/liquidjs#render-from-string
[braze/filters]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/advanced_filters/
[braze/property_accessor]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/advanced_filters/#property-accessor-filter
[braze/abort_message]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/aborting_messages/
[braze/connected_content]: https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content/making_an_api_call/#making-an-api-call

#### Use cases

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