Source Link: https://help.lob.com/print-and-mail/designing-mail-creatives/maximizing-engagement/dynamic-personalization/advanced-templating-handlebars
--- description: Using the Handlebar templating engine to create advanced templates --- # Advanced templating (Handlebars) ## Personalizing templates with Handlebars By default, Lob uses a [basic templating engine](https://www.lob.com/guides#html_and_merge) based on Mustache. If you would like to render complex personalizations, use the alternate Handlebars templating engine route through Lob API. [Handlebars syntax](https://handlebarsjs.com/) allows you to populate, evaluate, and iterate using templates and API requests. The biggest advantage of this approach is quickly creating dynamic personalization without making any changes to your codebase. We can use advanced templating to make dynamic tables. ### Creating a template 1. Start with any Handlebars-friendly template. Dynamic variables should be wrapped in double curly braces `{{like_this}}` . To the right is an example of a simple `handlebars` template. ```html Name is: {{user.name}} Location is: {{user.location}} ``` 2. To push your template to a Lob environment, use the [`/v1/templates`](https://api.lob.com/v1/templates) API. Creating Handlebars templates via the Dashboard UI is not supported at this time. To specify that our service should use the Handlebars templating engine, you will need pass `handlebars` in the template request `engine` field as shown on the right. ```html POST [/v1/templates]()/ { "description":"Test Template", "html":"Name is: {{user.name}}
Location is: {{user.location}} ", "engine":"handlebars", "required_vars": ["user"] //optional } Response { "id": "tmpl_81ff8f64ce61285", .... } ``` {% hint style="info" %} Note the optional field, **`required_vars`**. Any request to create a mailpiece using this template will require the variables listed there in order to complete successfully. {% endhint %} ### Template compilation API **You can use this newly created endpoint to test** that your Handlebars template compiles as expected. To do that, use the `/v1/templates/` endpoint and add your merge variable(s) as a dynamic URL query parameter. You can use this to inspect how your template will display with the merge variables passed in. The response is the same format that Lob will use to render your mailpiece.
```
If the input is an empty JSONObject `{}`, then `author` will become `undefined` and `if` condition fails, resulting in the output as follow:
```html
```
When using a block expression, you can specify a template section to run if the expression returns a falsey value. The section, marked by `else` is called an "else section".
```html
{{/withGroup}} ``` #### [**\{{withLast\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L727) Use the last item or `n` items in an array as context inside a block. Opposite of [**withFirst**](https://www.npmjs.com/package/handlebars-helpers#withFirst). **Params** * `array` **{Array}** * `idx` **{Number}**: The starting index. * `options` **{Object}** * `returns` **{String}** **Example** ``` {{#withLast array}} {{this}}{{/withLast}} ``` #### [**\{{withSort\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L766) Block helper that sorts a collection and exposes the sorted collection as context inside the block. **Params** * `array` **{Array}** * `prop` **{String}** * `options` **{Object}**: Specify `reverse="true"` to reverse the array. * `returns` **{String}** **Example** ``` {{#withSort array}}{{this}}{{/withSort}} ``` #### [**\{{unique\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L816) Block helper that return an array with all duplicate values removed. Best used along with a [**each**](https://www.npmjs.com/package/handlebars-helpers#each) helper. **Params** * `array` **{Array}** * `options` **{Object}** * `returns` **{Array}** **Example** ``` {{#each (unique array)}}{{.}}{{/each}} ```
####
--- description: Using the Handlebar templating engine to create advanced templates --- # Advanced templating (Handlebars) ## Personalizing templates with Handlebars By default, Lob uses a [basic templating engine](https://www.lob.com/guides#html_and_merge) based on Mustache. If you would like to render complex personalizations, use the alternate Handlebars templating engine route through Lob API. [Handlebars syntax](https://handlebarsjs.com/) allows you to populate, evaluate, and iterate using templates and API requests. The biggest advantage of this approach is quickly creating dynamic personalization without making any changes to your codebase. We can use advanced templating to make dynamic tables. ### Creating a template 1. Start with any Handlebars-friendly template. Dynamic variables should be wrapped in double curly braces `{{like_this}}` . To the right is an example of a simple `handlebars` template. ```html Name is: {{user.name}} Location is: {{user.location}} ``` 2. To push your template to a Lob environment, use the [`/v1/templates`](https://api.lob.com/v1/templates) API. Creating Handlebars templates via the Dashboard UI is not supported at this time. To specify that our service should use the Handlebars templating engine, you will need pass `handlebars` in the template request `engine` field as shown on the right. ```html POST [/v1/templates]()/ { "description":"Test Template", "html":"Name is: {{user.name}}
Location is: {{user.location}} ", "engine":"handlebars", "required_vars": ["user"] //optional } Response { "id": "tmpl_81ff8f64ce61285", .... } ``` {% hint style="info" %} Note the optional field, **`required_vars`**. Any request to create a mailpiece using this template will require the variables listed there in order to complete successfully. {% endhint %} ### Template compilation API **You can use this newly created endpoint to test** that your Handlebars template compiles as expected. To do that, use the `/v1/templates/` endpoint and add your merge variable(s) as a dynamic URL query parameter. You can use this to inspect how your template will display with the merge variables passed in. The response is the same format that Lob will use to render your mailpiece.
GET
/v1/templates/:id/compile
?merge_vars={"someVar":"someVal"}
Returns HTML
### Create a mailpiece using Handlebars
Now that your template has been created in a Lob environment, the templating `engine` has been set to `handlebars`, and you've tested out your template using the Template Compilation API, you can send a mailpiece request to the `/v1/checks/`, `/v1/postcards/`, `/v1/letters/` or `/v1/self_mailers/` endpoint as you normally would. In the request message body, use the `merge_variables` field to pass in dynamic values.
## Helpers
### Built in helpers
The below helpers can be used for many dynamic use cases. Helpers like `if` blocks can include nested built-in and customer helper conditionals (like `if`, `and`, `or`, `eq`, etc).
{% tabs %}
{% tab title="if" %}
### **#if**
You can use the `if` helper to conditionally render a block. If its argument returns `false`, `undefined`, `null`, `""`, `0`, or `[]`, Handlebars will not render the block.
```html
{{#if author}}
```
When you pass the following input to the above template:
```json
{
author: true,
firstName: "Yehuda",
lastName: "Katz",
}
```
This will produce the result as below:
```html
{{firstName}} {{lastName}}
{{/if}}Yehuda Katz
{{#if author}}
```
{% endtab %}
{% tab title="unless" %}
### **#unless**
You can use the `unless` helper as the inverse of the `if` helper. Its block will be rendered if the expression returns a falsy value.
```html
{{firstName}} {{lastName}}
{{else}}Unknown Author
{{/if}}
{{#unless license}}
```
If looking up `license` under the current context returns a falsy value, Handlebars will render the warning. Otherwise, it will render nothing.
{% endtab %}
{% tab title="each" %}
### **#each**
You can iterate over a list using the built-in `each` helper. Inside the block, you can use `this` to reference the element being iterated over.
```html
WARNING: This entry does not have a license!
{{/unless}}-
{{#each people}}
- {{this}} {{/each}}
- Yehuda Katz
- Alan Johnson
- Charles Jolley
{{this}}
{{else}}No content
{{/each}} ``` When looping through items in `each`, you can optionally reference the current loop index via `{{@index}}`. ```html {{#each array}} {{@index}}: {{this}} {{/each}} ``` Additionally for object iteration, `{{@key}}` references the current key name: ```html {{#each object}} {{@key}}: {{this}} {{/each}} ``` The first and last steps of iteration are noted via the `@first` and `@last` variables when iterating over an array. When iterating over an object only the `@first` is available. Nested each blocks may access the iteration variables via depth based paths. To access the parent index, for example, `{{@../index}}` can be used. {% endtab %} {% tab title="with" %} ### **#with** The `with`-helper allows you to change the evaluation context of template-part. ```html {{#with person}} {{firstname}} {{lastname}} {{/with}} ``` when used with this context: ```json { person: { firstname: "Yehuda", lastname: "Katz", }, } ``` will result in: ``` Yehuda Katz ``` `with` can also be used with block parameters to define known references in the current block. The example above can be converted to ```html {{#with city as | city |}} {{#with city.location as | loc |}} {{city.name}}: {{loc.north}} {{loc.east}} {{/with}} {{/with}} ``` Which allows for complex templates to potentially provide clearer code than `../` depthed references allow for. You can optionally provide an `{{else}}` section which will display only when the passed value is empty. ```html {{#with city}} {{city.name}} (not shown because there is no city) {{else}} No city found {{/with}} ``` {% endtab %} {% tab title="lookup" %} ### **#lookup** The `lookup` helper allows for dynamic parameter resolution using Handlebars variables. This is useful for resolving values for array indexes. ```json {{#each people}} {{.}} lives in {{lookup ../cities @index}} {{/each}} ``` It can also be used to lookup properties of object based on data from the input. The following is a more complex example that uses `lookup` in a sub-expression to change the evaluation contextto another object based on a property-value. ```json {{#each persons as | person |}} {{name}} lives in {{#with (lookup ../cities [resident-in])~}} {{name}} ({{country}}) {{/with}} ``` {% endtab %} {% endtabs %} ### Custom helpers Custom helpers are additional functions that can assist in the formatting of your document. The documentation here is directly pulled from the associated third-party [github repo](https://github.com/helpers/handlebars-helpers). The helpers below are supported. {% hint style="info" %} For uniformity with Handlebars' terminology, we use the word`falsey` instead of the more commonly used `falsy`. {% endhint %}Array helpers
#### [**\{{after\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L22) Returns all of the items in an array after the specified index. Opposite of [**before**](https://www.npmjs.com/package/handlebars-helpers#before). **Params** * `array` **{Array}**: Collection * `n` **{Number}**: Starting index (number of items to exclude) * `returns` **{Array}**: Array exluding `n` items. **Example** ```html {{after array 1}} ``` #### [**\{{arrayify\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L39) Cast the given `value` to an array. **Params** * `value` **{any}** * `returns` **{Array}** **Example** ```html {{arrayify "foo"}} ``` #### [**\{{before\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L58) Return all of the items in the collection before the specified count. Opposite of [**after**](https://www.npmjs.com/package/handlebars-helpers#after). **Params** * `array` **{Array}** * `n` **{Number}** * `returns` **{Array}**: Array excluding items after the given number. **Example** ```xml {{before array 2}} ``` #### [**\{{eachIndex\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L77) Implementation of the default Handlebars loop helper \{{#each\}} adding index (0-based index) to the loop content **Params** * `array` **{Array}** * `options` **{Object}** * `returns` **{String}** **Example** ```html {{#eachIndex array}} {{item}} is {{index}} {{/eachIndex}} ``` #### [**\{{filter\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L102) Block helper that filters the given array and renders the block for values that evaluate to `true`, otherwise the inverse block is returned. **Params** * `array` **{Array}** * `value` **{any}** * `options` **{Object}** * `returns` **{String}** **Example** ``` {{#filter array "foo"}}AAA {{else}}BBB {{/filter}} ``` #### [**\{{first\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L142) Returns the first item, or first `n` items of an array. **Params** * `array` **{Array}** * `n` **{Number}**: Number of items to return, starting at `0`. * `returns` **{Array}** **Example** ```html {{first "['a', 'b', 'c', 'd', 'e']" 2}} ``` #### [**\{{forEach\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L184) Iterates over each item in an array and exposes the current item in the array as context to the inner block. In addition to the current array item, the helper exposes the following variables to the inner block: * `index` * `total` * `isFirst` * `isLast` Also, `@index` is exposed as a private variable, and additional private variables may be defined as hash arguments. **Params** * `array` **{Array}** * `returns` **{String}** **Example** ```html {{#forEach accounts}} {{ name }} {{#unless isLast}}, {{/unless}} {{/forEach}} ``` #### [**\{{inArray\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L224) Block helper that renders the block if an array has the given `value`. Optionally specify an inverse block to render when the array does not have the given value. **Params** * `array` **{Array}** * `value` **{any}** * `options` **{Object}** * `returns` **{String}** **Example** ```html {{#inArray array "d"}} foo{{else}} bar{{/inArray}} ``` #### [**\{{isArray\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L244) Returns true if `value` is an es5 array. **Params** * `value` **{any}**: The value to test. * `returns` **{Boolean}** **Example** ```html {{isArray "abc"}} {{isArray array}} ``` #### [**\{{itemAt\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L263) Returns the item from `array` at index `idx`. **Params** * `array` **{Array}** * `idx` **{Number}** * `returns` **{any}** `value` **Example** ```html {{itemAt array 1}} ``` #### [**\{{join\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L294) Join all elements of array into a string, optionally using a given separator. **Params** * `array` **{Array}** * `separator` **{String}**: The separator to use. Defaults to `,`. * `returns` **{String}** **Example** ```html {{join array}} {{join array '-'}} ``` #### [**\{{equalsLength\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L313) Returns true if the the length of the given `value` is equal to the given `length`. Can be used as a block or inline helper. **Params** * `value` **{Array|String}** * `length` **{Number}** * `options` **{Object}** * `returns` **{String}** ```html {{equalsLength value 7}} {{equalsLength value 5}} ``` #### [**\{{last\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L349) Returns the last item, or last `n` items of an array or string. Opposite of [**first**](https://www.npmjs.com/package/handlebars-helpers#first). **Params** * `value` **{Array|String}**: Array or string. * `n` **{Number}**: Number of items to return from the end of the array. * `returns` **{Array}** **Example** ```html {{last value}} {{last value 2}} {{last value 3}} ``` #### [**\{{length\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L379) Returns the length of the given string or array. **Params** * `value` **{Array|Object|String}** * `returns` **{Number}**: The length of the value. **Example** ```html {{length '["a", "b", "c"]'}} {{length myArray}} {{length myObject}} ``` #### [**\{{map\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L414) Returns a new array, created by calling `function` on each element of the given `array`. For example, **Params** * `array` **{Array}** * `fn` **{Function}** * `returns` **{String}** **Example** ``` {{map array double}} ``` #### [**\{{pluck\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L445) Map over the given object or array or objects and create an array of values from the given `prop`. Dot-notation may be used (as a string) to get nested properties. **Params** * `collection` **{Array|Object}** * `prop` **{Function}** * `returns` **{String}** **Example** ``` // {{pluck items "data.title"}} ``` #### [**\{{reverse\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L473) Reverse the elements in an array, or the characters in a string. **Params** * `value` **{Array|String}** * `returns` **{Array|String}**: Returns the reversed string or array. **Example** ``` {{reverse value}} {{reverse value}} ``` #### [**\{{some\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L504) Block helper that returns the block if the callback returns true for some value in the given array. **Params** * `array` **{Array}** * `iter` **{Function}**: Iteratee * **{Options}**: Handlebars provided options object * `returns` **{String}** **Example** ``` {{#some array isString}} Render me if the array has a string.{{else}} Render me if it doesn't. {{/some}} ``` #### [**\{{sort\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L532) Sort the given `array`. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. You may alternatively pass a sorting function as the second argument. **Params** * `array` **{Array}**: the array to sort. * `key` **{String|Function}**: The object key to sort by, or sorting function. **Example** ``` {{sort array}} ``` #### [**\{{sortBy\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L557) Sort an `array`. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. You may alternatively pass a sorting function as the second argument. **Params** * `array` **{Array}**: the array to sort. * `props` **{String|Function}**: One or more properties to sort by, or sorting functions to use. **Example** ``` {{sortBy array "a"}} ``` #### [**\{{withAfter\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L588) Use the items in the array _after_ the specified index as context inside a block. Opposite of [**withBefore**](https://www.npmjs.com/package/handlebars-helpers#withBefore). **Params** * `array` **{Array}** * `idx` **{Number}** * `options` **{Object}** * `returns` **{Array}** **Example** ``` {{#withAfter array 3}} {{this}}{{/withAfter}} ``` #### [**\{{withBefore\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L618) Use the items in the array _before_ the specified index as context inside a block. Opposite of [**withAfter**](https://www.npmjs.com/package/handlebars-helpers#withAfter). **Params** * `array` **{Array}** * `idx` **{Number}** * `options` **{Object}** * `returns` **{Array}** **Example** ``` {{#withBefore array 3}} {{this}}{{/withBefore}} ``` #### [**\{{withFirst\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L648) Use the first item in a collection inside a handlebars block expression. Opposite of [**withLast**](https://www.npmjs.com/package/handlebars-helpers#withLast). **Params** * `array` **{Array}** * `idx` **{Number}** * `options` **{Object}** * `returns` **{String}** **Example** ``` {{#withFirst array}} {{this}}{{/withFirst}} ``` #### [**\{{withGroup\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L692) Block helper that groups array elements by given group `size`. **Params** * `array` **{Array}**: The array to iterate over * `size` **{Number}**: The desired length of each array "group" * `options` **{Object}**: Handlebars options * `returns` **{String}** **Example** ``` {{#withGroup array 4}} {{#each this}} {{.}} {{each}}{{/withGroup}} ``` #### [**\{{withLast\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L727) Use the last item or `n` items in an array as context inside a block. Opposite of [**withFirst**](https://www.npmjs.com/package/handlebars-helpers#withFirst). **Params** * `array` **{Array}** * `idx` **{Number}**: The starting index. * `options` **{Object}** * `returns` **{String}** **Example** ``` {{#withLast array}} {{this}}{{/withLast}} ``` #### [**\{{withSort\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L766) Block helper that sorts a collection and exposes the sorted collection as context inside the block. **Params** * `array` **{Array}** * `prop` **{String}** * `options` **{Object}**: Specify `reverse="true"` to reverse the array. * `returns` **{String}** **Example** ``` {{#withSort array}}{{this}}{{/withSort}} ``` #### [**\{{unique\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/array.js#L816) Block helper that return an array with all duplicate values removed. Best used along with a [**each**](https://www.npmjs.com/package/handlebars-helpers#each) helper. **Params** * `array` **{Array}** * `options` **{Object}** * `returns` **{Array}** **Example** ``` {{#each (unique array)}}{{.}}{{/each}} ```
Comparison helpers
#### [**\{{and\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/comparison.js#L27) Helper that renders the block if **both** of the given values are truthy. If an inverse block is specified it will be rendered when falsey. Works as a block helper, inline helper or subexpression. **Params** * `a` **{any}** * `b` **{any}** * `options` **{Object}**: Handlebars provided options object * `returns` **{String}** **Example** ``` {{#and great magnificent}}A{{else}}B{{/and}} ``` #### [**\{{compare\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/comparison.js#L57) Render a block when a comparison of the first and third arguments returns true. The second argument is the [**arithemetic operator**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators) to use. You may also optionally specify an inverse block to render when falsey. **Params** * `a` **{}** * `operator` **{}**: The operator to use. Operators must be enclosed in quotes: `">"`, `"="`, `"<="`, and so on. * `b` **{}** * `options` **{Object}**: Handlebars provided options object * `returns` **{String}**: Block, or if specified the inverse block is rendered if falsey. #### [**\{{contains\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/comparison.js#L124) Block helper that renders the block if `collection` has the given `value`, using strict equality (`===`) for comparison, otherwise the inverse block is rendered (if specified). If a `startIndex` is specified and is negative, it is used as the offset from the end of the collection. **Params** * `collection` **{Array|Object|String}**: The collection to iterate over. * `value` **{any}**: The value to check for. * `[startIndex=0]` **{Number}**: Optionally define the starting index. * `options` **{Object}**: Handlebars provided options object. **Example** ``` {{#contains array "d"}} This will not be rendered.{{else}} This will be rendered.{{/contains}} ``` #### [**\{{default\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/comparison.js#L143) Returns the first value that is not undefined, otherwise the "default" value is returned. **Params** * `value` **{any}** * `defaultValue` **{any}** * `returns` **{String}** #### [**\{{eq\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/comparison.js#L165) Block helper that renders a block if `a` is **equal to** `b`. If an inverse block is specified it will be rendered when falsey. You may optionally use the `compare=""` hash argument for the second value. **Params** * `a` **{String}** * `b` **{String}** * `options` **{Object}**: Handlebars provided options object * `returns` **{String}**: Block, or inverse block if specified and falsey. **Example** ```html { "state":"California" } {{#if (eq state "California")}}Welcome to Cali
{{else}}You\\'re not in California
{{/if}} ; {{append item.stem ".html"}} ``` #### [**\{{camelcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L41) camelCase the characters in the given `string`. **Params** * `string` **{String}**: The string to camelcase. * `returns` **{String}** **Example** ``` {{camelcase "foo bar baz"}};``` #### [**\{{capitalize\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L60) Capitalize the first word in a sentence. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{capitalize "foo bar baz"}} ``` #### [**\{{capitalizeAll\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L77) Capitalize all words in a string. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{capitalizeAll "foo bar baz"}} ``` #### [**\{{center\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L95) Center a string using non-breaking spaces **Params** * `str` **{String}** * `spaces` **{String}** * `returns` **{String}** #### [**\{{chop\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L125) Like trim, but removes both extraneous whitespace **and non-word characters** from the beginning and end of a string. **Params** * `string` **{String}**: The string to chop. * `returns` **{String}** **Example** ``` {{chop "_ABC_"}} {{chop "-ABC-"}} {{chop " ABC "}} ``` #### [**\{{dashcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L143) dash-case the characters in `string`. Replaces non-word characters and periods with hyphens. **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{dashcase "a-b-c d_e"}} ``` #### [**\{{dotcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L162) dot.case the characters in `string`. **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{dotcase "a-b-c d_e"}} ``` #### [**\{{downcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L182) Lowercase all of the characters in the given string. Alias for [**lowercase**](https://www.npmjs.com/package/handlebars-helpers#lowercase). **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{downcase "aBcDeF"}} ``` #### [**\{{ellipsis\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L202) Truncates a string to the specified `length`, and appends it with an elipsis, `…`. **Params** * `str` **{String}** * `length` **{Number}**: The desired length of the returned string. * `returns` **{String}**: The truncated string. **Example** ``` {{ellipsis (sanitize "foo bar baz"), 7}} {{ellipsis "foo bar baz", 7}} ``` #### [**\{{hyphenate\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L223) Replace spaces in a string with hyphens. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{hyphenate "foo bar baz qux"}} ``` #### [**\{{isString\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L240) Return true if `value` is a string. **Params** * `value` **{String}** * `returns` **{Boolean}** **Example** ``` {{isString "foo"}} ``` #### [**\{{lowercase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L256) Lowercase all characters in the given string. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{lowercase "Foo BAR baZ"}} ``` #### [**\{{occurrences\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L278) Return the number of occurrences of `substring` within the given `string`. **Params** * `str` **{String}** * `substring` **{String}** * `returns` **{Number}**: Number of occurrences **Example** ``` {{occurrences "foo bar foo bar baz" "foo"}} ``` #### [**\{{pascalcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L303) PascalCase the characters in `string`. **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{pascalcase "foo bar baz"}} ``` #### [**\{{pathcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L323) path/case the characters in `string`. **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{pathcase "a-b-c d_e"}} ``` #### [**\{{plusify\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L343) Replace spaces in the given string with pluses. **Params** * `str` **{String}**: The input string * `returns` **{String}**: Input string with spaces replaced by plus signs **Example** ``` {{plusify "foo bar baz"}} ``` #### [**\{{prepend\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L363) Prepends the given `string` with the specified `prefix`. **Params** * `str` **{String}** * `prefix` **{String}** * `returns` **{String}** **Example** ``` {{prepend val "foo-"}} ``` #### [**\{{raw\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L385) Render a block without processing mustache templates inside the block. **Params** * `options` **{Object}** * `returns` **{String}** **Example** ``` {{{{#raw}}}}{{foo}}{{{{/raw}}}} ``` #### [**\{{remove\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L413) Remove all occurrences of `substring` from the given `str`. **Params** * `str` **{String}** * `substring` **{String}** * `returns` **{String}** **Example** ``` {{remove "a b a b a b" "a "}} ``` #### [**\{{removeFirst\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L432) Remove the first occurrence of `substring` from the given `str`. **Params** * `str` **{String}** * `substring` **{String}** * `returns` **{String}** **Example** ``` {{remove "a b a b a b" "a"}} ``` #### [**\{{replace\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L452) Replace all occurrences of substring `a` with substring `b`. **Params** * `str` **{String}** * `a` **{String}** * `b` **{String}** * `returns` **{String}** **Example** ``` {{replace "a b a b a b" "a" "z"}} ``` #### [**\{{replaceFirst\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L473) Replace the first occurrence of substring `a` with substring `b`. **Params** * `str` **{String}** * `a` **{String}** * `b` **{String}** * `returns` **{String}** **Example** ``` {{replace "a b a b a b" "a" "z"}} ``` #### [**\{{reverse\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L492) Reverse a string. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{reverse "abcde"}} ``` #### [**\{{sentence\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L509) Sentence case the given string **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{sentence "hello world. goodbye world."}} ``` #### [**\{{snakecase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L528) snake\_case the characters in the given `string`. **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{snakecase "a-b-c d_e"}} ``` #### [**\{{split\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L547) Split `string` by the given `character`. **Params** * `string` **{String}**: The string to split. * `returns` **{String}** `character`: Default is an empty string. **Example** ``` {{split "a,b,c" ","}} ``` #### [**\{{startsWith\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L572) Tests whether a string begins with the given prefix. **Params** * `prefix` **{String}** * `testString` **{String}** * `options` **{String}** * `returns` **{String}** **Example** ``` {{#startsWith "Goodbye" "Hello, world!"}} Whoops{{else}} Do you even hello world? {{/startsWith}} ``` #### [**\{{titleize\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L596) Title case the given string. **Params** * `str` **{String}** * `returns` **{String}** **Example** ``` {{titleize "this is title case"}} ``` #### [**\{{trim\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L623) Removes extraneous whitespace from the beginning and end of a string. **Params** * `string` **{String}**: The string to trim. * `returns` **{String}** **Example** ``` {{trim " ABC "}} ``` #### [**\{{trimLeft\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L639) Removes extraneous whitespace from the beginning of a string. **Params** * `string` **{String}**: The string to trim. * `returns` **{String}** **Example** ``` {{trim " ABC "}} ``` #### [**\{{trimRight\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L657) Removes extraneous whitespace from the end of a string. **Params** * `string` **{String}**: The string to trim. * `returns` **{String}** **Example** ``` {{trimRight " ABC "}} ``` #### [**\{{truncate\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L680) Truncate a string to the specified `length`. Also see [**ellipsis**](https://www.npmjs.com/package/handlebars-helpers#ellipsis). **Params** * `str` **{String}** * `limit` **{Number}**: The desired length of the returned string. * `suffix` **{String}**: Optionally supply a string to use as a suffix to denote when the string has been truncated. Otherwise an ellipsis (`…`) will be used. * `returns` **{String}**: The truncated string. **Example** ``` truncate("foo bar baz", 7); truncate(sanitize("foo bar baz", 7)); ``` #### [**\{{truncateWords\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L712) Truncate a string to have the specified number of words. Also see [**truncate**](https://www.npmjs.com/package/handlebars-helpers#truncate). **Params** * `str` **{String}** * `limit` **{Number}**: The desired length of the returned string. * `suffix` **{String}**: Optionally supply a string to use as a suffix to denote when the string has been truncated. * `returns` **{String}**: The truncated string. **Example** ``` truncateWords("foo bar baz", 1); truncateWords("foo bar baz", 2); truncateWords("foo bar baz", 3); ``` #### [**\{{upcase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L742) Uppercase all of the characters in the given string. Alias for [**uppercase**](https://www.npmjs.com/package/handlebars-helpers#uppercase). **Params** * `string` **{String}** * `returns` **{String}** **Example** ``` {{upcase "aBcDeF"}} ``` #### [**\{{uppercase\}}**](https://github.com/helpers/handlebars-helpers/blob/HEAD/lib/string.js#L763) Uppercase all of the characters in the given string. If used as a block helper it will uppercase the entire block. This helper does not support inverse blocks. **Params** * `str` **{String}**: The string to uppercase * `options` **{Object}**: Handlebars options object * `returns` **{String}** **Example** ``` {{uppercase "aBcDeF"}} ``` * `array` **{Array}**: The array to iterate over * `size` **{Number}**: The desired length of each array "group" * `options` **{Object}**: Handlebars options * `returns` **{String}**