{"_id":"58f94336d8be780f00239df6","__v":0,"user":"55a6caa022cfa321008e01d6","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"58105bf298aea40f00afa3ba","__v":0,"version":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-26T07:32:02.240Z","from_sync":false,"order":9,"slug":"handlebars-syntax","title":"Handlebars Syntax and Helpers"},"parentDoc":null,"project":"55a6e72e8cc73e0d00096635","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-20T23:24:38.527Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:html]\n{\n  \"html\": \"<head>\\n<title>Handlebars Helpers Reference</title>\\n<meta name=\\\"description=\\\" content=\\\"Reference to Handlebars helpers custom to (or otherwise supported on) the Stencil themes framework.\\\">\\n</head>\\n<!-- Add more examples, like the existing example examples. -->\"\n}\n[/block]\nThis page describes the Handlebars helpers supported on the Stencil framework. It includes helpers that are custom to, or customized for, Stencil. Helpers are listed in the following sections:\n\n* [Array Helpers](#array)\n* [Collection Helpers](#collection)\n* [Comparison Helpers](#comparison)\n* [Control-Flow Helpers](#control)\n* [Date Helpers](#date)\n* [HTML Helpers](#html)\n* [Image Helpers](#image)\n* [Inflection Helpers](#inflection)\n* [Injection Helpers](#injection)\n* [Markdown Helpers](#markdown)\n* [Math Helpers](#math)\n* [Number Helpers](#number)\n* [Object Helpers](#object)\n* [Operator Helpers](#operator)\n* [String Helpers](#string)\n* [URL Helpers](#url)\n* [Miscellaneous Helpers](#misc)\n\n\nFor background information on using Handlebars helpers, please see the [official Handlebars documentation](http://handlebarsjs.com).\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Compatibility and Restrictions\",\n  \"body\": \"* Stencil's Handlebars helpers are based on Handlebars version 3.0.1.\\n\\n* Most of the helpers identified below as \\\"standard\\\" require a Stencil CLI upgrade to version 1.8.0 or higher. (You can check your current installed version using the `stencil -V` or `stencil --version` command, as outlined [here](/docs/stencil-cli-options).)\\n\\n* For security reasons, BigCommerce does not allow Stencil developers to define new custom Handlebars helpers – you must use the helpers currently available. However, you can suggest new custom helpers via a pull request to the <a href=\\\"https://github.com/bigcommerce/cornerstone\\\">Stencil Github repo</a>.\"\n}\n[/block]\n# <a name=\"array\"></a> Array Helpers\n\nThe following helpers are available to manage arrays:\n\n* [Stencil Custom Array Helpers](#array_custom)\n* [Standard Array Helpers](#array_std) \n\n## <a name=\"array_custom\"></a> Stencil Custom Array Helpers\n\nThe following array helpers are custom to the Stencil framework.\n[block:html]\n{\n  \"html\": \"<!--\\nhttps://github.com/bigcommerce/stencil-cli/issues/341 reports that `itemAt` is not really firing. So, will hide this next item after getting eyes on a bug report to address the problem.\\n-->\"\n}\n[/block]\n### {{itemAt}}]\n\nBlock helper that returns the item at the specified index.\n\n#### Parameters\n\n* `array` **{Array}**\n* `idx` **{Number}**\n* `returns` **{any}** `value`\n\n#### Example\n\nGiven the array `['a', 'b', 'c']`:\n\n```handlebars\n{{itemAt array 1}}\n//=> 'b'\n```\n\n### {{join}}\n\nThe `join` helper is custom to Stencil. It joins an array of string items, with separators. It returns a string. \n\n#### Parameters\n\n- `values`: {Array}\n- `separator`: {String}\n- `limit=<number>`: An optional limit.\n\n### {{limit}}\n\nThe `limit` helper is custom to Stencil. It limits the number of items returned from an array variable, and returns a new array.\n\n#### Parameters\n\n- `data`: {Array}\n- `limit`: {Number}\n\n#### {{limit}} Example \n\nAssume that `{{cart.items}}` would return 10 items. You could use this helper to limit that behavior to only the first four items, by specifying: \n\n```\n{{limit cart.items 4}}\n```\n\n### {{pluck}}\n\nThe `pluck` helper is custom to Stencil. For one or more specified search key(s), it retrieves corresponding values from some or all elements in a specified collection. \n\nThe `pluck` helper returns the retrieved values in a comma-separated string. This helper's general form is:\n\n```\n{{pluck ([limit] <collection> [<limit-value>]) '<search-key>'}}\n```\n\n#### Parameters\n\n- `limit`, `limit-value`: Optional parameters to limit the number of results returned.\n- `collection`: The collection to search.\n- `search-key`: The string to search for.\n\n\n#### {{pluck}} Example 1\n\nAssume that the `categories` collection contains:\n\n```\ncategories: [\n  { \"id\": 1, \"name\": \"Bakeware\" },\n  { \"id\": 2, \"name\": \"Cookware\" },\n  { \"id\": 3, \"name\": \"Cutlery\" }\n]\n```\n\nIn this case, this Handlebars statement:\n\n```\n{{pluck (limit categories 2) 'name'}}\n```\n\n...would return:\n\n```\n\"Bakeware,Cookware\"\n```\n\n#### {{pluck}} Example 2\n\nIf the `categories` themselves each contained an image object, then you could use dot notation to access that image object's children:\n\n```\ncategories: [\n  { \"id\": 1, \"name\": \"Bakeware\", \"image\": { \"data\": \"http://...\", \"alt\": \"Bakeware image\"} },\n  { \"id\": 2, \"name\": \"Cookware\" \"image\": { \"data\": \"http://...\", \"alt\": \"Cookware image\"} },\n  { \"id\": 3, \"name\": \"Cutlery\" \"image\": { \"data\": \"http://...\", \"alt\": \"Cutlery image\"} }\n]\n```\n\nIn this case, this Handlebars statement:\n\n```\n{{pluck (limit categories 2) 'image.data'}}\n```\n\n...would return a comma-separated list of image URLs.\n\n\n## <a name=\"array_std\"></a> Standard Array Helpers\n\nThe following standard array helpers are supported on the Stencil framework.\n\n### <a name=\"after\"></a> {{after}}\n\nReturns all of the items in an array after the specified index. Opposite of [before](#before).\n\nGiven the array `['a', 'b', 'c']`:\n\n#### Parameters\n\n* `array` {Array}: Collection.\n* `n` {Number}: Starting index (number of items to exclude).\n* `returns` {Array}: Array exluding `n` items.\n\n#### Example\n\n```handlebars\n{{after array 1}}\n//=> '[\"c\"]'\n```\n\n### {{arrayify}}\n\nCasts the given `value` to an array.\n\n#### Parameters\n\n* `value` {any}\n* `returns` {Array}\n\n#### Example\n\n```handlebars\n{{arrayify \"foo\"}}\n//=> '[\"foo\"]'\n```\n\n### <a name=\"before\"></a> {{before}}\n\nReturns all of the items in the collection before the specified count. Opposite of [after](#after).\n\nGiven the array `['a', 'b', 'c']`:\n\n#### Parameters\n\n* `array` {Array}\n* `n` {Number}\n* `returns` {Array}: Array excluding items after the given number.\n\n#### Example\n\n```handlebars\n{{before array 2}}\n//=> '[\"a\", \"b\"]'\n```\n\n### {{eachIndex}}\n\n#### Parameters\n\n* `array` {Array}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{#eachIndex collection}}\n  {{item}} is {{index}}\n{{/eachIndex}}\n```\n\n### {{filter}}\n\nBlock helper that filters the given array. Renders the block for values that evaluate to `true`; otherwise, returns the inverse block.\n\n#### Parameters\n\n* `array` {Array}\n* `value` {any}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{#filter array \"foo\"}}AAA{{else}}BBB{{/filter}}\n//=> 'BBB\n```\n\n### <a name=\"first\"></a> {{first}}\n\nReturns the first item, or first `n` items, of an array.\n\n#### Parameters\n\n* `array` {Array}\n* `n` {Number}: Number of items to return, starting at `0`.\n* `returns` {Array}\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd', 'e']`:\n\n```handlebars\n{{first array 2}}\n//=> '[\"a\", \"b\"]'\n```\n\n### {{forEach}}\n\nIterates 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:\n\n* `index`\n* `total`\n* `isFirst`\n* `isLast`\n\nAlso, `:::at:::index` is exposed as a private variable, and additional private variables may be defined as hash arguments.\n\n#### Parameters\n\n* `array` {Array}\n* `returns` {String}\n\n#### Example\n\n```js\nvar accounts = [\n{'name': 'John', 'email': 'john@example.com'},\n{'name': 'Malcolm', 'email': 'malcolm@example.com'},\n{'name': 'David', 'email': 'david@example.com'}\n];\n\n// example usage\n// {{#forEach accounts}}\n//   <a href=\"mailto:{{ email }}\" title=\"Send an email to {{ name }}\">\n//     {{ name }}\n//   </a>{{#unless isLast}}, {{/unless}}\n// {{/forEach}}\n```\n\n### {{inArray}}\n\nBlock helper that renders the block if an array has the given `value`. Optionally, you can specify an inverse block to render when the array does not have the given value.\n\n#### Parameters\n\n* `array` {Array}\n* `value` {any}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\nGiven the array `['a', 'b', 'c']`:\n\n```handlebars\n{{#inArray array \"d\"}}\n  foo\n{{else}}\n  bar\n{{/inArray}}\n//=> 'bar'\n```\n\n### {{isArray}}\n\nReturns true if `value` is an es5 array.\n\n#### Parameters\n\n* `value` {any}: The value to test.\n* `returns` {Boolean}\n\n#### Example\n\n```handlebars\n{{isArray \"abc\"}}\n//=> 'false'\n```\n\n### <a name=\"last\"></a> {{last}}\n\nReturns the last item, or last `n` items, of an array. Opposite of [first](#first).\n\n#### Parameters\n\n* `array` {Array}\n* `n` {Number}: Number of items to return, starting with the last item.\n* `returns` {Array}\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd', 'e']`:\n\n```handlebars\n{{last array 2}}\n//=> '[\"d\", \"e\"]'\n```\n\n### {{lengthEqual}}\n\nBlock helper that compares the length of the given array to the number passed as the second argument. If the array length is equal to the given `length`, the block is returned. Otherwise, you have the option of returning an inverse block.\n\n#### Parameters\n\n* `array` {Array}\n* `length` {Number}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd', 'e']`:\n\n```handlebars\n{{#lengthEqual array 10}}AAA{{else}}BBB{{/lengthEqual}}\n//=> 'BBB'\n```\n\n### {{map}}\n\nReturns a new array, created by calling `function` on each element of the given `array`.\n\n#### Parameters\n\n* `array` {Array}\n* `fn` {Function}\n* `returns` {String}\n\n#### Example\n\nGiven an array `['a', 'b', 'c']`:\n\n```js\n// register `double` as a helper\nfunction double(str) {\n  return str + str;\n}\n// then used like this:\n// {{map array double}}\n//=> '[\"aa\", \"bb\", \"cc\"]'\n```\n\n### {{some}}\n\nBlock helper that returns the block *if* the callback returns true for some value in the given array.\n\n#### Parameters\n\n* `array` {Array}\n* `cb` {Function}: Callback function.\n* {Options}: Handlebars-provided options object.\n* `returns` {Array}\n\n#### Example\n\nGiven the array `[1, 'b', 3]`:\n\n```handlebars\n{{#some array isString}}\n  Render me if the array has a string.\n{{else}}\n  Render me if it doesn't.\n{{/some}}\n//=> 'Render me if the array has a string.'\n```\n\n### {{sort}}\n\nSorts the given `array`. If an array of objects is passed, you may optionally pass (as the second argument) a `key` to sort on. Alternatively, you may pass a sorting function as the second argument.\n\n#### Parameters\n\n* `array` {Array}: The array to sort.\n* `key` {String|Function}: The object key to sort by, or a sorting function.\n\n#### Example\n\nGiven an array `['b', 'a', 'c']`:\n\n\n```handlebars\n{{sort array}}\n//=> '[\"a\", \"b\", \"c\"]'\n```\n\n### {{sortBy}}\n\nSorts 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.\n\n#### Parameters\n\n* `array` {Array}: The array to sort.\n* `props` {String|Function}: One or more properties to sort by, or sorting functions to use.\n\n#### Example\n\nGiven an array `[{a: 'zzz'}, {a: 'aaa'}]`:\n\n```handlebars\n{{sortBy array \"a\"}}\n//=> '[{\"a\":\"aaa\"}, {\"a\":\"zzz\"}]'\n```\n\n### <a name=\"withAfter\"></a> {{withAfter}}\n\nUse the items in the array, _after_ the specified index, as context inside a block. Opposite of [withBefore](#withBefore).\n\n#### Parameters\n\n* `array` {Array}\n* `idx` {Number}\n* `options` {Object}\n* `returns` {Array}\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd', 'e']`:\n\n```handlebars\n{{#withAfter array 3}}\n  {{this}}\n{{/withAfter}}\n//=> \"de\"\n```\n\n### <a name=\"withBefore\"></a> {{withBefore}}\n\nUse the items in the array, _before_ the specified index, as context inside a block. Opposite of [withAfter](#withAfter).\n\n#### Parameters\n\n* `array` {Array}\n* `idx` {Number}\n* `options` {Object}\n* `returns` {Array}\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd', 'e']`:\n\n```handlebars\n{{#withBefore array 3}}\n  {{this}}\n{{/withBefore}}\n//=> 'ab'\n```\n\n### <a name=\"withFirst\"></a> {{withFirst}}\n\nUses a collection's first item inside a Handlebars block expression. Opposite of [withLast](#withLast).\n\n#### Parameters\n\n* `array` {Array}\n* `idx` {Number}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\nGiven the array `['a', 'b', 'c']`:\n\n```handlebars\n{{#withFirst array}}\n  {{this}}\n{{/withFirst}}\n//=> 'a'\n```\n[block:html]\n{\n  \"html\": \"<!--\\n\\n### {{withGroup}}\\n\\nBlock helper that groups array elements by the given `every` value.\\n\\n#### Parameters\\n\\n* `array` **{Array}**\\n* `every` **{Number}**\\n* `options` **{Object}**\\n* `returns` **{String}**\\n\\n#### Example\\n\\nGiven the array `['a', 'b', 'c', 'd','e','f','g','h']`:\\n\\n```handlebars\\n{{#withGroup array 4}}\\n  {{#each this}}\\n    {{.}}\\n  {{each}}\\n  <br>\\n{{/withGroup}}\\n//=> 'a','b','c','d'\\n//=> 'e','f','g','h'\\n```\\n\\n-->\"\n}\n[/block]\n### <a name=\"withLast\"></a> {{withLast}}\n\nUse the last item, or `n` items, in an array as context inside a block. Opposite of [withFirst](#withFirst).\n\n#### Parameters\n\n* `array` {Array}\n* `idx` {Number}: The starting index.\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\nGiven the array `['a', 'b', 'c']`:\n\n```handlebars\n{{#withLast array}}\n  {{this}}\n{{/withLast}}\n//=> 'c'\n```\n\n### {{withSort}}\n\nBlock helper that sorts a collection and exposes the sorted collection as context inside the block.\n\n#### Parameters\n\n* `array` {Array}\n* `prop` {String}\n* `options` {Object}: Specify `reverse=\"true\"` to reverse the array.\n* `returns` {String}\n\n#### Example\n\nGiven the array `['b', 'a', 'c']`:\n\n```handlebars\n{{#withSort array}}{{this}}{{/withSort}}\n//=> 'abc'\n```\n\n# <a name=\"collection\"></a> Collection Helpers\n\nThe following standard helpers are available to handle collections.\n\n### {{isEmpty}}\n\nBlock helper that returns a block *if* the given collection is empty. If the collection is not empty, returns the inverse block (if supplied).\n\n#### Parameters\n\n* `collection` {Object}\n* `options` {Object}\n* `returns` {String}\n\n### {{iterate}}\n\nIterates over an array or object.\n\n#### Parameters\n\n* `context` {Object|Array}: The collection to iterate over.\n* `options` {Object}\n* `returns` {String}\n\n### {{length}}\n\nReturns the length of the given collection. When using a string literal in the template, the string must be value JSON. See the example below. Otherwise, pass in an array or object from the context.\n\n#### Parameters\n\n* `value` {Array|Object|String}\n* `returns` {Number}: The length of the value.\n\n#### Example\n\n```handlebars\n{{length '[\"a\", \"b\", \"c\"]'}}\n//=> 3\n\n//=> myArray = ['a', 'b', 'c', 'd', 'e'];\n{{length myArray}}\n//=> 5\n\n//=> myObject = {'a': 'a', 'b': 'b'};\n{{length myObject}}\n//=> 2\n```\n\n# <a name=\"comparison\"></a> Comparison Helpers\n\nThe following standard helpers are available to handle comparisons.\n\n### {{and}}\n\nBlock helper that renders the block if *both* of the given values are truthy. If you specify an inverse block, it will be rendered when falsy.\n\n#### Parameters\n\n* `a` {any}\n* `b` {any}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}\n\n### {{gt}}\n\nBlock helper that renders a block if `a` is *greater than* `b`.\n\nIf an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=\"\"` hash argument for the second value.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{gte}}\n\nBlock helper that renders a block if `a` is *greater than or equal to* `b`.\n\nIf an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=\"\"` hash argument for the second value.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{has}}\n\nBlock helper that renders a block if `value` has `pattern`. If an inverse block is specified, it will be rendered when falsy.\n\n#### Parameters\n\n* `val` {any}: The value to check.\n* `pattern` {any}: The pattern to check for.\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}\n\n### {{eq}}\n\nBlock helper that renders a block if `a` is *equal to* `b`. If an inverse block is specified,  it will be rendered when falsy. You may optionally use the `compare=\"\"` hash argument for the second value.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{ifEven}}\n\nReturns `true` if the given value is an even number.\n\n#### Parameters\n\n* `number` {Number}\n* `options` {Object}: Handlebars-provided options object\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n#### Example\n\n```handlebars\n{{#ifEven value}}\n  render A\n{{else}}\n  render B\n{{/ifEven}}\n```\n\n### {{ifNth}}\n\nConditionally renders a block *if* dividing the `a` operand by `b` yields a remainder of zero. If you specify an inverse block, it will be rendered when the remainder is *not* zero.\n\n#### Parameters\n\n* {}: {Number}\n* {}: {Number}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{ifOdd}}\n\nBlock helper that renders a block if `value` is *an odd number*. If an inverse block is specified, it will be rendered when falsy.\n\n#### Parameters\n\n* `value` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n#### Example\n\n```handlebars\n{{#ifOdd value}}\n  render A\n{{else}}\n  render B\n{{/ifOdd}}\n```\n\n### {{is}}\n\nBlock helper that renders a block if `a` is *equal to* `b`. If an inverse block is specified, it will be rendered when falsy.\n\n#### Parameters\n\n* `a` {any}\n* `b` {any}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}\n\n### {{isnt}}\n\nBlock helper that renders a block if `a` is *not equal to* `b`. If an inverse block is specified, it will be rendered when falsy.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}\n\n### {{lt}}\n\nBlock helper that renders a block if `a` is *less than* `b`.\n\nIf an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=\"\"` hash argument for the second value.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{lte}}\n\nBlock helper that renders a block if `a` is *less than or equal to* `b`.\n\nIf an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=\"\"` hash argument for the second value.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{neither}}\n\nBlock helper that renders a block if *neither of* the given values are truthy. If you specify an inverse block, it will be rendered when falsy.\n\n#### Parameters\n\n* `a` {any}\n* `b` {any}\n* `options` {}: Handlebars options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{unlessEq}}\n\nBlock helper that always renders the inverse block *unless `a` is equal to `b`*.\n\n#### Parameters\n\n* `a` {String}\n* `b` {String}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Inverse block by default, or block if falsy.\n\n### {{unlessGt}}\n\nBlock helper that always renders the inverse block *unless `a` is greater than `b`*.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Inverse block by default, or block if falsy.\n\n### {{unlessLt}}\n\nBlock helper that always renders the inverse block *unless `a` is less than `b`*.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{unlessGteq}}\n\nBlock helper that always renders the inverse block *unless `a` is greater than or equal to `b`*.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n### {{unlessLteq}}\n\nBlock helper that always renders the inverse block *unless `a` is less than or equal to `b`*.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}: Handlebars-provided options object.\n* `returns` {String}: Block, or inverse block if specified and falsy.\n\n\n# <a name=\"control\"></a> Control-Flow Helpers\n\nThe following control-flow helpers have been customized for the Stencil framework:\n\n* [Conditional Control Flow](#ctrl_conditional)\n* [Loop Control Flow](#ctrl_loop)\n\nBeyond the formal examples below, syntax and examples for control-flow helpers are covered in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html).\n\n\n## <a name=\"ctrl_conditional\"></a> Conditional Control Flow\n\nThe following helpers provide control structures that test for conditions, and branch accordingly.\n\n### <a name=\"if\"></a> {{if}}\n\nThe `if` helper has been customized for Stencil, and has the following syntax:\n\n```\n{{#if <statement>}}\n  ... \n{{else if}}  /* optional else-if block */\n  ...\n{{else}}  /* optional else block */\n  ...\n{{/if}}\n```\n\nThe `<statement>` that the `if` helper evaluates can take these forms:\n\n- An object, as in: `{{#if object}}`.\n- A comparison expression, as in: `{{#if <lvalue> <operator> <rvalue>}}`.\n\n\nWhen you pass only one parameter to the `if` helper, it will return the following:\n- For an array parameter, the array's length.\n- For an empty object, a value of `false`.\n\n\n### {{unless}}\n\nThe `unless` helper is logically the opposite of the [`if` helper](#if), subject to the [restrictions](#unless_restrix) below. The syntax for `unless` can be found in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html).\n\n#### Formal Example\n\n```\n{{#unless statement}}\n   ... /* block to display/execute unless statement is true */\n{{/unless}}\n```\n\n#### <a name=\"unless_restrix\"></a> Restrictions\n\nStatements using `unless` can refer to: \n\n* Objects, as in: `{{#unless object}}`.\n\nUnlike the `if` helper,  `unless` on the Stencil framework does not support operators for comparison expressions. \nSo, for example, the following expression would throw an error:\n\n```\n{{#unless this.alt \"===\" \"hidden\"}}\n```\n\nA workaround for this logic is to recast the expression as `if`/not-equal-to. So the following expression would be valid:\n\n```\n{{#if this.alt \"!==\" \"hidden\"}}\n```\n\n#### Stencil Example \n\nHere is a usage example from Stencil's Cornerstone base theme: The `templates/pages/search.html` template displays search results. In this template's section that displays search suggestions, an `#unless` loop determines what to output for the final result:\n\n```\n{{#each category_results}}\n<li class=\"category-suggestion\">\n    {{#each this}}\n        <a href=\"{{url}}\">{{name}}</a>\n        {{#unless @last}} > {{/unless}}\n    {{/each}}\n</li>\n{{/each}}\n```\n\n### Nested if/else Statements to Test for if/and Conditions\n\nHandlebars does not provide an `if`/`and` conditional structure. However, to test for multiple conditions, you can nest `if`/`else` statements, as shown in this example:\n\n```\n <nav class=\"navigation\">\n      <ul>\n        {{#each nav_items}}\n            {{#if name '===' 'About Us'}}\n            {{else}}\n              {{#if name '===' 'Contact Us'}}\n              {{else}}\n                <li>\n                  <a class=\"top-level-nav-link\" href=\"{{url}}\">\n                    {{name}}\n                  </a>\n                </li>\n              {{/if}}\n            {{/if}}\n        {{/each}}\n      </ul>\n    </nav>\n```\n\n## <a name=\"ctrl_loop\"></a> Loop Control Flow\n\nThe following helpers are used to control loop execution.\n\n### {{any}}\n\nThe `any` helper is custom to Stencil. It checks whether at least one parameter evaluates to `true`.  Parameters can be of different types (strings, numbers, arrays, or collections).\n\n#### Examples\n\nFormally, the `any` helper is invoked as shown here:\n\n```\n{{#any items selected=true}} \n  ... /* block to display if any items have selected=true */\n{{/any}}\n```\n\nA usage example is http://cornerstone-light-demo.mybigcommerce.com/shop-all/garden, a category page in Stencil's Cornerstone base theme that does _not_ have faceted search turned on. Shoppers will see \"Shop by price\" filters instead of product filters. \n\nThe Stencil code controlling this component resides in the theme's `templates/components/category/shop-by-price.html` file. In this component, the `{{#any...` Handlebars helper is used to determine whether a shopper has selected one of the filters, and whether a \"reset\" button needs to be displayed:\n\n```\n{{#any shop_by_price selected=true}}\n    <li class=\"navList-item\">\n        <a href=\"{{category_url}}\" class=\"navList-action\">\n            {{lang 'category.reset'}}\n        </a>\n    </li>\n{{/any}}\n```\n\n### {{all}}\n\nThe `all` helper is custom to Stencil. It checks whether _all_ parameters evaluate to `true`. Parameters can be of different types (strings, numbers, arrays, or collections).\n\n#### Example\n\n```\n{{#all items theme_settings.optionA theme_settings.optionB}}\n  ... /* block to display, if all items evaluate to true */\n{{/all}}\n```\n\n### contains Helper\n\nThe `contains` helper is custom to Stencil. It checks whether the second parameter is included in the first parameter (typically a collection).\n\n#### Example\n\n```\n{{#contains fonts \"Roboto\"}}\n  ... /* block to display, if any items contain \"Roboto\" */\n{{/contains}}\n```\n\n### {{each}}\n\nThe syntax for the `each` helper can be found in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html).\n\n#### Example\n\n```\n{{#each array | object}}\n  ...\n{{else}} /* optional block to execute if the the list is empty */\n  ...\n{{/each}}\n```\n\n#### Notes\n\n- Within an each block, use `{{this}}` to reference the current item.\n- Within an each block, use `{{@index}}` to reference the current item's index number.\n- When iterating through objects, `{{@key}}` returns the current key name.\n- `{{each}}` loops can be nested.\n\n\n### {{for}}\n\nThe `for` helper is a custom Stencil helper. In particular, this helper is limited to 100 iterations, in order to protect against infinite loops. \n\nThe `for` helper has the following syntax, where parameters `<from>` and `<to>` are numbers, and `<context>` is an object:\n\n```\n{{#for <from> <to> <context>}}\n  ...\n{{/for}}\n```\n\n\n# <a name=\"date\"></a> Date Helpers\n\nThe following standard Handlebars helper handles dates.\n\n### {{moment}}\n\nExposes `helper-date` as `moment`.\n\n\n# <a name=\"html\"></a> HTML Helpers\n\nThe following standard helpers are available to handle HTML content.\n\n### {{ellipsis}}\n\nTruncates a string to the specified `length`, and appends an elipsis, `…`.\n\n#### Parameters\n\n* `str` {String}\n* `length` {Number}: The desired length of the returned string.\n* `returns` {String}: The truncated string.\n\n#### Example\n\n```js\n{{ellipsis \"<span>foo bar baz</span>\", 7}}\n//=> 'foo bar…'\n```\n\n### {{sanitize}}\n\nStrips HTML tags from a string, so that only the text nodes are preserved.\n\n#### Parameters\n\n* `str` {String}: The string of HTML to sanitize.\n* `returns` {String}\n\n#### Example\n\n```js\n{{sanitize \"<span>foo</span>\"}}\n//=> 'foo'\n```\n\n### {{ul}}\n\nBlock helper for creating unordered lists (`<ul></ul>`).\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}\n* `returns` {String}\n\n### {{ol}}\n\nBlock helper for creating ordered lists  (`<ol></ol>`).\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}\n* `returns` {String}\n\n### {{thumbnailImage}}\n\nReturns a `<figure>` with a thumbnail linked to a full picture.\n\n#### Parameters\n\n* `context` {Object}: Object with values/attributes to add to the generated elements:\n* `context.alt` {String}\n* `context.src` {String}\n* `context.width` {Number}\n* `context.height` {Number}\n* `returns` {String}: HTML `<figure>` element with image and optional caption/link.\n\n\n# <a name=\"image\"></a> Image Helpers\n\nThe Stencil framework provides the following custom helper to manage images.\n\n## {{getImage}}\n\nThe `getImage` helper is custom to Stencil. It returns the URL for an image of the specified size. Values for the size parameter are defined in the `config.json` file’s `settings` section.\n\nThis helper's parameters are:\n\n- `stencilImage`: a StencilImage.\n- `size`: a string.\n- `defaultImage` (optional): a string. \n\nHere is an example: \n\n```\n{{getImage image \"thumbnail\"}}\n``` \n\nYou can use the optional `defaultImage` parameter to specify an image that will be displayed in cases where the passed `stencilImage` value is null.\n\n\n# <a name=\"inflection\"></a> Inflection Helpers\n\nThe following standard helpers are available to transform strings.\n\n### {{inflect}}\n\nHandles singular/plural forms.\n\n#### Parameters\n\n* `count` {Number}\n* `singular` {String}: The singular form\n* `plural` {String}: The plural form\n* `include` {String}\n* `returns` {String}\n\n### {{ordinalize}}\n\nReturns an ordinalized number (as a string).\n\n#### Parameters\n\n* `val` {String}: The value to ordinalize.\n* `returns` {String}: The ordinalized number.\n\n#### Example\n\n```handlebars\n{{ordinalize 1}}\n//=> '1st'\n{{ordinalize 21}}\n//=> '21st'\n{{ordinalize 29}}\n//=> '29th'\n{{ordinalize 22}}\n//=> '22nd'\n```\n\n# <a name=\"injection\"></a> Injection Helpers\n\nThe Stencil framework provides the following custom helpers to insert various resources into a page context:\n\n* [{{cdn}}](#cdn)\n* [{{getFontsCollection}}](#fonts)\n* [{{inject}} and {{jsContext}}](#inject)\n* [{{stylesheet}}](#stylesheet)\n\n### <a name=\"cdn\"></a> {{cdn}}\n\nThe `cdn` helper is custom to Stencil. It is a URL transformer for content delivery networks.\n\nWhen you reference static assets that you have locally staged outside your `<theme-name>` directory and uploaded using WebDAV, place the `webdav:` prefix before each corresponding `assetPath` parameter. For example, a link like:\n\n```\n<img src=\"{{cdn \"webdav:img/image.jpg\"}}\">\n```\n\n...will be transformed to a result like:\n\n```\n<img src=\"https://cdn.bcapp/3dsf74g/content/img/image.jpg\">\n```\n\nThe presumed WebDAV root directory is `/content/`. (So, in this example, the `image.jpg` file had been uploaded to the WebDAV `/content/` directory.) The presumed local directory is `<theme-name>/assets/`, so you can omit that path when referencing its contained files or subdirectories.\n\n\n#### <a name=\"cdn-custom\"></a> CDN Custom Endpoints\n\nYou can define custom CDN endpoints to use with the `cdn` Handlebars helper. This facilitates including large, high-resolution image assets in themes, without exceeding BigCommerce's [50 MB limit](docs/bundling-and-submitting-a-theme#ship-zip-small) when bundling the theme for upload to BigCommerce. \n\nYou could use a local version of the image in development, and a version on a CDN (for exampe, Imgix) in production. To do so, define custom CDN endpoints in your theme's [`config.json` file](/docs/configjson-reference#config-theme-settings), as highlighted in this example:\n\n```\n{\n  \"name\": \"Cornerstone\",\n  \"version\": \"1.3.5\",\n  \"settings\": {\n    \"homepage_new_products_count\": 12,\n    \"homepage_featured_products_count\": 8,\n    <b>\"cdn\": {\n      \"customcdn\": {\n        \"path\": \"https://bigcommerce.customcdn.net\"\n      }\n    }</b>\n  }\n}\n```\n\nAfter defining an endpoint, you can use the short name in the same way as you would use a `webdav:` abbreviation:\n\n```\n<img src=\"{{cdn \"customcdn:img/image.jpg\"}}\" />\n```\n\nIn local development, that helper would return:\n\n<pre>&lt;img src=\"<b>/assets/cdn/</b>customcdn/img/image.jpg\" /&gt;\n</pre>\n\nWhereas in production, it would return:\n\n```\n<img src=\"https://bigcommerce.customcdn.net/img/image.jpg\" />\n```\n\nAs highlighted above, the helper is configured to rewrite local URLs to a `<theme-name>/assets/cdn/` subfolder. The `stencil bundle` command excludes `assets/cdn/` subfolder from the bundle that it creates – circumventing the 50 MB size limit on the resulting .zip file.\n\n\n### <a name=\"fonts\"></a> {{getFontsCollection}}\n\nThe `getFontsCollection` helper is custom to Stencil. It returns a link tag that loads all selected font collections. It takes no parameters.\n\n\n### <a name=\"inject\"></a> {{inject}} and {{jsContext}}\n\nOccasionally, your theme's client-side application code might need to incorporate dynamic data from the template context. Stencil provides two custom Handlebars helpers to help you achieve this: `inject`  and `jsContext`.\n\n#### About the {{inject}} Helper\n\nThe `inject` helper collects data definitions for injection into the `jsContext` variable. It composes a JSON object containing a subset of the template context to be sent to the browser. Parameters of the `inject` helper are:\n\n- `key`: a string.\n- `value`: multiple types supported. \n\nAn `inject` call takes this form:\n\n```\n{{inject \"stringBasedKey\" contextValue}}\n```\n\n#### About the {{jsContext}} Helper\n\nThe `jsContext` helper takes no parameters; it simply returns a JSON object containing all data collected by the `inject` helper. To retrieve the parsable JSON object, just call `{{jsContext}}` after all of the `{{inject}}` calls.\n\n\n#### {{inject}} + {{jsContext}} Example 1\n\nTo set up the product name in your client-side app, you can do the following, if you are in the context of a product:\n\n```\n{{inject \"myProductName\" product.title}}\n\n<script>\n// Note the lack of quotes around the jsContext handlebars helper, it becomes a string automatically.\nvar jsContext = JSON.parse({{jsContext}}); \n\n// jsContext would output \"{\\\"myProductName\\\": \\\"Sample Product\\\"}\" which can feed directly into \nyour JavaScript.\n\nconsole.log(jsContext.myProductName); // Will output: Sample Product\n</script>\n```\n\n##### Notes on Example 1\n\nYou can compose your JSON object across multiple pages to create a different set of client-side data, depending on the currently loaded template context.\n\nThe Stencil theme makes the `jsContext` available on the active page scoped. It also makes it available on the global `PageManager` objects, as `this.context`.\n\n#### {{inject}} Example 2\n\nThe following code uses `inject` to add all product IDs into JavaScript on category pages. It resides in a theme's `<theme-name>/templates/pages/category.html` template. Note the two `inject` calls directly under the front matter:\n\n```\n---\ncategory:\n    shop_by_price: true\n    products:\n        limit: {{theme_settings.categorypage_products_per_page}}\n---\n{{inject \"categoryProductsPerPage\" theme_settings.categorypage_products_per_page}}\n{{inject \"productIds\" (pluck category.products 'id')}}\n{{#partial \"head\"}}\n    {{#if pagination.category.previous}}\n        <link rel=\"prev\" href=\"{{pagination.category.previous}}\">\n    {{/if}}\n    {{#if pagination.category.next}}\n        <link rel=\"next\" href=\"{{pagination.category.next}}\">\n    {{/if}}\n{{/partial}}\n\n{{#partial \"page\"}}\n\n{{> components/common/breadcrumbs breadcrumbs=breadcrumbs}}\n{{#if category.image}}\n    <img src=\"{{getImage category.image 'zoom_size'}}\">\n{{/if}}\n<h1 class=\"page-heading\">{{category.name}}</h1>\n{{{category.description}}}\n{{{snippet 'categories'}}}\n<div class=\"page\">\n    <aside class=\"page-sidebar\" id=\"faceted-search-container\">\n        {{> components/category/sidebar}}\n    </aside>\n\n    <main class=\"page-content\" id=\"product-listing-container\">\n        {{#if category.products}}\n            {{> components/category/product-listing}}\n        {{else}}\n            <p>{{lang 'categories.no_products'}}</p>\n        {{/if}}\n    </main>\n</div>\n\n{{/partial}}\n{{> layout/base}}\n```\n\n### <a name=\"stylesheet\"></a> {{stylesheet}}\n\nThe `stylesheet` helper is custom to Stencil. It renders a link tag to insert a stylesheet into your theme. (This is required if you want Theme Editor to rewrite the stylesheet file when a merchant customizes their theme.) This helper returns an HTML string.\n\n#### Parameters\n\n- path: String containing the path to the theme's CSS stylesheet file.\n- Other parameters are optional, appended in the form: `key=\"value\"`.\n\n#### Example\n\n```\n{{{stylesheet \"assets/css/style.css\" class=\"myStylesheet\"}}}\n```\n\n\n# <a name=\"markdown\"></a> Markdown Helpers\n\nThe following standard helper is available to convert markdown.\n\n### {{markdown}}\n\nBlock helper that converts a string of inline markdown to HTML.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}\n* `returns` {String}\n\n#### Example\n\n```html\n{{#markdown}}\n# Foo\n{{/markdown}}\n//=> <h1>Foo</h1>\n```\n\n# <a name=\"math\"></a> Math Helpers\n\nThe following standard helpers are available to handle mathematical operations.\n\n\n### {{add}}\n\nReturns the sum of `a` plus `b`.\n\n#### Parameters\n\n* `a` {Number}\n* `b` {Number}\n\n### {{subtract}}\n\nReturn the differnece of `a` minus `b`.\n\n#### Parameters\n\n* `a` {Number}\n* `b` {Number}\n\n### {{divide}}\n\nDivides `a` by `b`.\n\n#### Parameters\n\n* `a` {Number}: numerator\n* `b` {Number}: denominator\n\n### {{multiply}}\n\nMultiplies `a` by `b`.\n\n#### Parameters\n\n* `a` {Number}: factor\n* `b` {Number}: multiplier\n\n### {{floor}}\n\nGets the `Math.floor()` of the given value.\n\n#### Parameters\n\n* `value` {Number}\n\n### {{ceil}}\n\nGets the `Math.ceil()` [ceiling] of the given value.\n\n#### Parameters\n\n* `value` {Number}\n\n### {{round}}\n\nRounds the given value.\n\n#### Parameters\n\n* `value` {Number}\n\n### {{sum}}\n\nReturns the sum of all numbers in the given array.\n\n#### Parameters\n\n* `array` {Array}: Array of numbers to add up.\n* `returns` {Number}\n\n#### Example\n\n```handlebars\n{{sum \"[1, 2, 3, 4, 5]\"}}\n//=> '15'\n```\n\n### {{avg}}\n\nReturns the average of all numbers in the given array.\n\n#### Parameters\n\n* `array` {Array}: Array of numbers to add up and average.\n* `returns` {Number}\n\n#### Example\n\n```handlebars\n{{avg \"[1, 2, 3, 4, 5]\"}}\n//=> '3'\n```\n\n# <a name=\"number\"></a> Number Helpers\n\nThe following standard helpers are available to handle and transform numbers.\n\n### {{addCommas}}\n\nAdds commas to numbers.\n\n#### Parameters\n\n* `num` {Number}\n* `returns` {Number}\n\n### {{phoneNumber}}\n\nConverts a string or number to a formatted phone number.\n\n#### Parameters\n\n* `num` {Number|String}: The phone number to format, e.g., `8005551212`\n* `returns` {Number}: The formatted phone number: `(800) 555-1212`\n\n### {{random}}\n\nGenerates a random number between two values.\n\n#### Parameters\n\n* `min` {Number}\n* `max` {Number}\n* `returns` {String}\n\n### {{toAbbr}}\n\nAbbreviates numbers to the given number of `precision`. This is for general numbers, not size in bytes.\n\n#### Parameters\n\n* `number` {Number}\n* `precision` {Number}\n* `returns` {String}\n\n### {{toExponential}}\n\nReturns a string, representing the given number in exponential notation.\n\n#### Parameters\n\n* `number` {Number}\n* `fractionDigits` {Number}: Optional. An integer specifying the number of digits to use after the decimal point. Defaults to as many digits as necessary to specify the number.\n* `returns` {Number}\n\n#### Example\n\n```js\n{{toExponential number digits}};\n```\n\n### {{toFixed}}\n\nFormats the given number, using fixed-point notation.\n\n#### Parameters\n\n* `number` {Number}\n* `digits` {Number}: Optional. The number of digits to use after the decimal point. This can be a value between 0 and 20, inclusive, and implementations may optionally support a larger range of values. If this argument is omitted, it is treated as 0.\n* `returns` {Number}\n\n### {{toFloat}}\n\n#### Parameters\n\n* `number` {Number}\n* `returns` {Number}\n\n### {{toInt}}\n\n#### Parameters\n\n* `number` {Number}\n* `returns` {Number}\n\n### {{toPrecision}}\n\n#### Parameters\n\n* `number` {Number}\n* `precision` {Number}: Optional. The number of significant digits.\n* `returns` {Number}\n\n\n# <a name=\"object\"></a> Object Helpers\n\nThe following standard helpers are available to handle objects.\n\n### {{extend}}\n\nExtends the context with the properties of other objects. A shallow merge is performed to avoid mutating the context.\n\n#### Parameters\n\n* `objects` {Object}: One or more objects to extend.\n* `returns` {Object}\n\n### {{forIn}}\n\nBlock helper that iterates over the properties of an object, exposing each key and value on the context.\n\n#### Parameters\n\n* `context` {Object}\n* `options` {Object}\n* `returns` {String}\n\n### {{forOwn}}\n\nBlock helper that iterates over the *own* properties of an object, exposing each key and value on the context.\n\n#### Parameters\n\n* `obj` {Object}: The object to iterate over.\n* `options` {Object}\n* `returns` {String}\n\n### {{toPath}}\n\nTakes arguments and, if they are string or number, converts them to a dot-delineated object property path.\n\n#### Parameters\n\n* `prop` {String|Number}: The property segments to assemble (can be multiple).\n* `returns` {String}\n\n### {{get}}\n\nUses property paths (`a.b.c`) to get a value or nested value from the context. Works as a regular helper or block helper.\n\n#### Parameters\n\n* `prop` {String}: The property to get, optionally using dot notation for nested properties.\n* `context` {Object}: The context object.\n* `options` {Object}: The Handlebars options object, if used as a block helper.\n* `returns` {String}\n\n### {{getObject}}\n\nUses property paths (`a.b.c`) to get an object from the context. Unlike the `get` helper, this helper will return the actual object, including the given property key. Also, this helper does not work as a block helper.\n\n#### Parameters\n\n* `prop` {String}: The property to get, optionally using dot notation for nested properties.\n* `context` {Object}: The context object.\n* `returns` {String}\n\n### {{hasOwn}}\n\nReturns true if `key` is an own, enumerable property of the given `context` object.\n\n#### Parameters\n\n* `key` {String}\n* `context` {Object}: The context object.\n* `returns` {Boolean}\n\n#### Example\n\n```handlebars\n{{hasOwn context key}}\n```\n\n### {{isObject}}\n\nReturns true if `value` is an object.\n\n#### Parameters\n\n* `value` {String}\n* `returns` {Boolean}\n\n#### Example\n\n```handlebars\n{{isObject \"foo\"}}\n//=> false\n```\n\n### {{merge}}\n\nDeeply merges the properties of the given `objects` with the context object.\n\n#### Parameters\n\n* `object` {Object}: The target object. Pass an empty object to shallow-clone.\n* `objects` {Object}\n* `returns` {Object}\n\n### {{JSONparse}}\n\nBlock helper that parses a string using `JSON.parse`, then passes the parsed object to the block as context.\n\n#### Parameters\n\n* `string` {String}: The string to parse.\n* `options` {Object}: Handlebars options object.\n\n### {{JSONstringify}}\n\nStringifies an object using `JSON.stringify`.\n\n#### Parameters\n\n* `obj` {Object}: Object to stringify.\n* `returns` {String}\n\n\n# <a name=\"operator\"></a> Operator Helpers\n\nThe Stencil framework supports the following operator helpers:\n\n[Comparison Operators](#op_comparison)\n[Logical {{or}} Operator](#op_logical)\n[{{typeof}} Operator](#op_type)\n\n## <a name=\"op_comparison\"></a> Comparison Operators\n\nThe following helpers are available to handle comparisons.\n\n| Helper | Definition |\n|--|--|\n|`==`| equal to |\n|`===`| equal to and equal type |\n|`!=`| not equal |\n|`<`| less than |\n|`>`| greater than |\n|`<=`| less than or equal to |\n|`>=`| greater than or equal to |\n\n### Equal to and Equal Type Example\n\nTo compare a string, use the `===` operator, as in this example from `templates/components/common/share.html`: \n\n```\n  {{#if service '===' 'facebook'}}\n    <svg>\n      <use xlink:href=\"#icon-facebook\"/>\n    </svg>\n  {{/if}}\n```\n\n### Not Equal or Not Equal Type Example\n\nTo improvise a `!==` (not equal or not equal type) comparison operator in Handlebars, you can use an [if](#if)/else structure as shown in this example:\n\n```\n  <nav class=\"navigation\">\n      <ul>\n        {{#each nav_items}}\n            {{#if name '===' 'About Us'}}\n            {{else}}\n              <li>\n                <a class=\"top-level-nav-link\" href=\"{{url}}\">\n                  {{name}}\n                </a>\n              </li>\n            {{/if}}\n        {{/each}}\n      </ul>\n    </nav>\n```\n\n## <a name=\"op_logical\"></a> Logical {{or}} Operator\n\nThe `or` operator has been customized for Stencil. It checks whether at least one of its parameters evaluates to true, and has the following syntax:\n\n```\n{{#or 1 0 0 0 0 0 0}} \n  ... /* execute this block if OR evaluates to true */\n{{/or}}\n```\n\n### Example\n\nHere is a usage example from Stencil's Cornerstone base theme, where it displays the cart's contents. The `templates/components/cart/content.html` template uses the `or` operator to determine whether an item contains either product options _or_ configurable fields. If at least one condition is true, the template displays an edit link for the item:\n\n```\n{{#or options configurable_fields}}\n    <a href=\"#\" data-item-edit=\"{{id}}\">{{lang 'cart.checkout.change'}}</a>\n{{/or}}\n```\n\n### Parameters \n\nThe `or` operator's parameters are one or more strings, numbers, arrays, or collections. Parameters can be of mixed types. \n\n\n## <a name=\"op_type\"></a> {{typeof}} Operator\n\nThe `typeof` operator returns the JavaScript type of a variable, such as:\n\n- string\n- number\n- boolean\n- object\n\nBy design, an array will return a `typeof` value of `object`.\n\n### Example\n\n```\n<script>\n    if (typeof(addthis) === \"object\") {\n        addthis.toolbox('.addthis_toolbox');\n    }\n</script>\n```\n\n\n# <a name=\"string\"></a> String Helpers\n\nThe following helpers are available to manipulate strings:\n\n* [Stencil Custom String Helpers](#string_custom)\n* [Standard String Helpers](#string_std)\n\n\n## <a name=\"string_custom\"></a> Stencil Custom String Helpers\n\nThe following string helpers are custom to the Stencil framework.\n\n### <a name=\"block-helper\"></a> {{block}} </span>\n\nThe `block` string helper is custom to Stencil. It defines a block of content, which can be overwritten by the [partial](#partial-helper) helper.\n\n### {{concat}}\n\nThe `concat` helper is custom to Stencil. It concatenates two string objects from the page's context, which are passed as parameters. It returns a new string object.\n\n#### Example\n\n```\n{{concat breadcrumbs.[0].name breadcrumbs.[0].url}}\n```\n\n### {{dynamicComponent}}\n\nThe `dynamicComponent` string helper is custom to Stencil. It inserts a dynamic partial from within the path that is supplied as its parameter.\n\n\n### {{json}}\n\nThe `json` string helper is custom to Stencil. You can use this helper to convert a JavaScript string object (from the page's context) into a JSON string object.\n\n\n### {{lang}}\n\nThe `lang` string helper is custom to Stencil. It maps keys to translation files, based on the locale indicated by the visitor’s browser. Its parameters are the following keys:\n\n- `translationKey`: a string.\n- `options`: key-value pairs.\n\n\n### {{nl2br}}\n\nThe `nl2br` helper is custom to Stencil. You can call this helper on a string object from the page's context, to convert its contained newline characters (`\\r\\n`, `\\n\\r`, `\\r`, `\\n`) to `<br>` tags. The `nl2br` helper returns a new string object.\n\n#### Example\n\nThis Handlebars statement:\n\n```\n{{nl2br settings.address}}\n```\n\n...will take this example string:\n\n```\n\"settings\": {\n  \"address\": \"\\r\\n685 Market St\\r\\nSan Francisco\\r\\n94105\\r\\nCA\\r\\n\"\n}\n```\n\n...and return\n\n```\n\"<br>685 Market St<br>San Francisco<br>94105<br>CA<br>\"\n```\n\n### <a name=\"partial-helper\"></a> {{partial}}\n\nThe `partial` string helper is custom to Stencil. It overrides block content defined by the [block](#block-helper) helper.\n\n\n### {{replace}}\n\nThe `replace` string helper is custom to Stencil. It searches for the first parameter within the second parameter and, if it finds it, replaces the first parameter with the contents of the specified Handlebars block.\n\nFor example, the following code would search for the string `needle` within the scope defined by `haystack`. If found, it would replace that string with the Handlebars block defined by `<context...replacement>`:\n\n```\n{{#replace \"needle\" haystack}}\n  {{<context to use as a replacement>}}\n{{/replace}}\n```\n\n### {{toLowerCase}}\n\nThe `toLowerCase` helper is custom to Stencil. Use this helper to return a copy of a string object, in all-lowercase. The helper returns a new string object.\n\n#### Example\n\nThis Handlebars statement:\n\n```\n{{toLowerCase head.title}}\n```\n\n...will take this example string:\n\n```\n\"head\": {\n  \"title\": \"This is my TEST Store\"\n}\n```\n\n...and return:\n\n```\n\"this is my test store\"\n```\n\n\n## <a name=\"string_std\"></a> Standard String Helpers\n\nThe following standard string helpers are supported on the Stencil framework.\n\n### {{camelcase}}\n\ncamelCases the characters in the given `string`.\n\n#### Parameters\n\n* `string` {String}: The string to camelcase.\n* `returns` {String}\n\n#### Example\n\n```js\n{{camelcase \"foo bar baz\"}};\n//=> 'fooBarBaz'\n```\n\n### {{capitalize}}\n\nCapitalizes the first word in a sentence.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{capitalize \"foo bar baz\"}}\n//=> \"Foo bar baz\"\n```\n\n### {{capitalizeAll}}\n\nCapitalizes all words in a string.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{capitalizeAll \"foo bar baz\"}}\n//=> \"Foo Bar Baz\"\n```\n\n### {{center}}\n\nCenters a string, using non-breaking spaces.\n\n#### Parameters\n\n* `str` {String}\n* `spaces` {String}\n* `returns` {String}\n\n### {{chop}}\n\nLike `trim`, but removes both extraneous whitespace *and non-word characters* from the beginning and end of a string.\n\n#### Parameters\n\n* `string` {String}: The string to chop.\n* `returns` {String}\n\n#### Example\n\n```js\n{{chop \"_ABC_\"}}\n//=> 'ABC'\n\n{{chop \"-ABC-\"}}\n//=> 'ABC'\n\n{{chop \" ABC \"}}\n//=> 'ABC'\n```\n\n### {{dashcase}}\n\ndash-cases the characters in `string`. Replaces non-word characters and periods with hyphens.\n\n#### Parameters\n\n* `string` {String}\n* `returns` {String}\n\n#### Example\n\n```js\n{{dashcase \"a-b-c d_e\"}}\n//=> 'a-b-c-d-e'\n```\n\n### {{dotcase}}\n\ndot.cases the characters in `string`.\n\n#### Parameters\n\n* `string` {String}\n* `returns` {String}\n\n#### Example\n\n```js\n{{dotcase \"a-b-c d_e\"}}\n//=> 'a.b.c.d.e'\n```\n\n### {{hyphenate}}\n\nReplaces spaces in a string with hyphens.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{hyphenate \"foo bar baz qux\"}}\n//=> \"foo-bar-baz-qux\"\n```\n\n### {{isString}}\n\nReturns true if `value` is a string.\n\n#### Parameters\n\n* `value` {String}\n* `returns` {Boolean}\n\n#### Example\n\n```handlebars\n{{isString \"foo\"}}\n//=> 'true'\n```\n\n### {{lowercase}}\n\nLowercases all characters in the given string.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{lowercase \"Foo BAR baZ\"}}\n//=> 'foo bar baz'\n```\n\n### {{occurrences}}\n\nReturns the number of occurrences of `substring` within the given `string`.\n\n#### Parameters\n\n* `str` {String}\n* `substring` {String}\n* `returns` {Number}: Number of occurrences.\n\n#### Example\n\n```handlebars\n{{occurrences \"foo bar foo bar baz\" \"foo\"}}\n//=> 2\n```\n\n### {{pascalcase}}\n\nPascalCases the characters in `string`.\n\n#### Parameters\n\n* `string` {String}\n* `returns` {String}\n\n#### Example\n\n```js\n{{pascalcase \"foo bar baz\"}}\n//=> 'FooBarBaz'\n```\n\n### {{pathcase}}\n\npath/cases the characters in `string`.\n\n#### Parameters\n\n* `string` {String}\n* `returns` {String}\n\n#### Example\n\n```js\n{{pathcase \"a-b-c d_e\"}}\n//=> 'a/b/c/d/e'\n```\n\n### {{plusify}}\n\nReplaces spaces in the given string with pluses.\n\n#### Parameters\n\n* `str` {String}: The input string\n* `returns` {String}: Input string with spaces replaced by plus signs\n\n#### Example\n\n```handlebars\n{{plusify \"foo bar baz\"}}\n//=> 'foo+bar+baz'\n```\n\n### {{reverse}}\n\nReverses a string.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{reverse \"abcde\"}}\n//=> 'edcba'\n```\n\n### {{sentence}}\n\nSentence-cases the given string.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{sentence \"hello world. goodbye world.\"}}\n//=> 'Hello world. Goodbye world.'\n```\n\n### {{snakecase}}\n\nsnake_cases the characters in the given `string`.\n\n#### Parameters\n\n* `string` {String}\n* `returns` {String}\n\n#### Example\n\n```js\n{{snakecase \"a-b-c d_e\"}}\n//=> 'a_b_c_d_e'\n```\n\n### {{split}}\n\nSplits `string` at the given `character`.\n\n#### Parameters\n\n* `string` {String}: The string to split.\n* `returns` {String} `character`: Default is `,`\n\n#### Example\n\n```js\n{{split \"a,b,c\" \",\"}}\n//=> ['a', 'b', 'c']\n```\n\n### {{startsWith}}\n\nTests whether a string begins with the given prefix.\n\n#### Parameters\n\n* `prefix` {String}\n* `testString` {String}\n* `options` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{#startsWith \"Goodbye\" \"Hello, world!\"}}\n  Whoops\n{{else}}\n  Bro, do you even hello world?\n{{/startsWith}}\n```\n[block:html]\n{\n  \"html\": \"<!--\\n\\n### [{{strlen}}](lib/string.js#L442)\\n\\nReturns a string's length.\\n\\n#### Parameters\\n\\n* `string` **{String}**\\n* `options` **{Object}**\\n* `returns` **{Number}**\\n\\n#### Example\\n\\n```handlebars\\n{{strlen \\\"Hello, world!\\\"}}\\n//=> 13\\n```\\n\\n-->\"\n}\n[/block]\n### {{titleize}}\n\nTitle-cases the given string.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n#### Example\n\n```handlebars\n{{titleize \"this is title case\"}}\n//=> 'This Is Title Case'\n```\n\n### {{trim}}\n\nRemoves extraneous whitespace from the beginning and end of a string.\n\n#### Parameters\n\n* `string` {String}: The string to trim.\n* `returns` {String}\n\n#### Example\n\n```js\n{{trim \" ABC \"}}\n//=> 'ABC'\n```\n\n### {{uppercase}}\n\nUppercases all of the characters in the given string. If used as a block helper, it will uppercase the entire block. This helper\ndoes not support inverse blocks.\n\n#### Parameters\n\n* `str` {String}: The string to uppercase.\n* `options` {Object}: Handlebars options object.\n* `returns` {String}\n\n\n# <a name=\"url\"></a> URL Helpers\n\nThe following standard helpers are available to transform URLs.\n\n\n### {{encodeURI}}\n\nEncodes a Uniform Resource Identifier (URI) component, by replacing each instance of certain characters by one, two, three, or four escape sequences that represent the UTF-8 encoding of the character.\n\n#### Parameters\n\n* `str` {String}: The un-encoded string.\n* `returns` {String}: The encoded string.\n\n### {{decodeURI}}\n\nDecodes a Uniform Resource Identifier (URI) component.\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}\n\n### {{urlResolve}}\n\nTakes a base URL, and an href URL, and resolves them as a browser would for an anchor tag.\n\n#### Parameters\n\n* `base` {String}\n* `href` {String}\n* `returns` {String}\n\n### {{urlParse}}\n\nParses a `url` string into an object.\n\n#### Parameters\n\n* `str` {String}: URL string.\n* `returns` {String}: Returns stringified JSON.\n\n### {{stripQuerystring}}\n\nStrips the query string from a `url`.\n\n#### Parameters\n\n* `url` {String}\n* `returns` {String}: The URL without the queryString.\n\n### {{stripProtocol}}\n\nStrips the protocol from a `url`.\n\nUseful for displaying media that might have an `http` protocol on secure connections. Will change `http://foo.bar` to `//foo.bar`\n\n#### Parameters\n\n* `str` {String}\n* `returns` {String}: The URL with the `http` protocol stripped.\n\n\n# <a name=\"misc\"></a> Miscellaneous Helpers\n\nThe following standard helpers are also supported on the Stencil framework.\n\n\n### {{default}}\n\nReturns the first value, if that value is defined; otherwise, returns the \"default\" value.\n\n#### Parameters\n\n* `value` {any}\n* `defaultValue` {any}\n* `returns` {String}\n\n### {{option}}\n\nGiven the context `{options: {a: {b: {c: 'ddd'}}}}`, returns the given value of `prop` from `this.options`.\n\n#### Parameters\n\n* `prop` {String}\n* `returns` {any}\n\n#### Example\n\n```handlebars\n{{option \"a.b.c\"}}\n<!-- results => `ddd` -->\n```\n\n### {{noop}}\n\nBlock helper that renders the block without taking any arguments.\n\n#### Parameters\n\n* `options` {Object}\n* `returns` {String}\n\n### {{withHash}}\n\nBlock helper that builds the context for the block from the options hash.\n\n#### Parameters\n\n* `options` {Object}: Handlebars-provided options object.\n\n[block:html]\n{\n  \"html\": \"<!-- [Hidden from String helpers:]\\n## <span id=\\\"truncate-helper\\\"> truncate Helper </span>\\n\\nThe `truncate` helper is custom to Stencil, and works like the JavaScript `substring()` function: Use it to truncate a string to a specified length. The `truncate` helper's parameters are:\\n\\n- `str`: a string.\\n- `length`: the maximum number of characters to return.\\n\\nThis helper will return a new string that contains the first `length` characters from the original `str` string. (If the original string contains fewer than `length` characters, `truncate` will return the whole string.)\\n\\n### Example\\n\\nAssume that a store owner wants to display a card, at the bottom of the store's home page, highlighting the most recent blog post. This card should display the blog thumbnail, the post's title, and the first 40 characters\\nof the post's body. The following extract `truncate` call will extract those first 40 characters:\\n\\n```\\n{{truncate 'blog.post.body.' 40)}\\n```\\n-->\\n\\n<!-- [Removed from Other helpers:]\\n* [snippet Helper](#snippet)\\n\\n## <span id=\\\"snippet\\\"> snippet Helper </span>\\n\\nThe `snippet` helper is custom to Stencil. It defines an injection point, within a storefront page, where theme developers can inject JavaScript, HTML, or CSS to support applications.\\n\\n###Parameters: \\n\\n- [location](/docs/snippet-locations): a string.\\n-->\"\n}\n[/block]","excerpt":"","slug":"handlebars-helpers-reference","type":"basic","title":"Handlebars Helpers Reference"}

Handlebars Helpers Reference


[block:html] { "html": "<head>\n<title>Handlebars Helpers Reference</title>\n<meta name=\"description=\" content=\"Reference to Handlebars helpers custom to (or otherwise supported on) the Stencil themes framework.\">\n</head>\n<!-- Add more examples, like the existing example examples. -->" } [/block] This page describes the Handlebars helpers supported on the Stencil framework. It includes helpers that are custom to, or customized for, Stencil. Helpers are listed in the following sections: * [Array Helpers](#array) * [Collection Helpers](#collection) * [Comparison Helpers](#comparison) * [Control-Flow Helpers](#control) * [Date Helpers](#date) * [HTML Helpers](#html) * [Image Helpers](#image) * [Inflection Helpers](#inflection) * [Injection Helpers](#injection) * [Markdown Helpers](#markdown) * [Math Helpers](#math) * [Number Helpers](#number) * [Object Helpers](#object) * [Operator Helpers](#operator) * [String Helpers](#string) * [URL Helpers](#url) * [Miscellaneous Helpers](#misc) For background information on using Handlebars helpers, please see the [official Handlebars documentation](http://handlebarsjs.com). [block:callout] { "type": "info", "title": "Compatibility and Restrictions", "body": "* Stencil's Handlebars helpers are based on Handlebars version 3.0.1.\n\n* Most of the helpers identified below as \"standard\" require a Stencil CLI upgrade to version 1.8.0 or higher. (You can check your current installed version using the `stencil -V` or `stencil --version` command, as outlined [here](/docs/stencil-cli-options).)\n\n* For security reasons, BigCommerce does not allow Stencil developers to define new custom Handlebars helpers – you must use the helpers currently available. However, you can suggest new custom helpers via a pull request to the <a href=\"https://github.com/bigcommerce/cornerstone\">Stencil Github repo</a>." } [/block] # <a name="array"></a> Array Helpers The following helpers are available to manage arrays: * [Stencil Custom Array Helpers](#array_custom) * [Standard Array Helpers](#array_std) ## <a name="array_custom"></a> Stencil Custom Array Helpers The following array helpers are custom to the Stencil framework. [block:html] { "html": "<!--\nhttps://github.com/bigcommerce/stencil-cli/issues/341 reports that `itemAt` is not really firing. So, will hide this next item after getting eyes on a bug report to address the problem.\n-->" } [/block] ### {{itemAt}}] Block helper that returns the item at the specified index. #### Parameters * `array` **{Array}** * `idx` **{Number}** * `returns` **{any}** `value` #### Example Given the array `['a', 'b', 'c']`: ```handlebars {{itemAt array 1}} //=> 'b' ``` ### {{join}} The `join` helper is custom to Stencil. It joins an array of string items, with separators. It returns a string. #### Parameters - `values`: {Array} - `separator`: {String} - `limit=<number>`: An optional limit. ### {{limit}} The `limit` helper is custom to Stencil. It limits the number of items returned from an array variable, and returns a new array. #### Parameters - `data`: {Array} - `limit`: {Number} #### {{limit}} Example Assume that `{{cart.items}}` would return 10 items. You could use this helper to limit that behavior to only the first four items, by specifying: ``` {{limit cart.items 4}} ``` ### {{pluck}} The `pluck` helper is custom to Stencil. For one or more specified search key(s), it retrieves corresponding values from some or all elements in a specified collection. The `pluck` helper returns the retrieved values in a comma-separated string. This helper's general form is: ``` {{pluck ([limit] <collection> [<limit-value>]) '<search-key>'}} ``` #### Parameters - `limit`, `limit-value`: Optional parameters to limit the number of results returned. - `collection`: The collection to search. - `search-key`: The string to search for. #### {{pluck}} Example 1 Assume that the `categories` collection contains: ``` categories: [ { "id": 1, "name": "Bakeware" }, { "id": 2, "name": "Cookware" }, { "id": 3, "name": "Cutlery" } ] ``` In this case, this Handlebars statement: ``` {{pluck (limit categories 2) 'name'}} ``` ...would return: ``` "Bakeware,Cookware" ``` #### {{pluck}} Example 2 If the `categories` themselves each contained an image object, then you could use dot notation to access that image object's children: ``` categories: [ { "id": 1, "name": "Bakeware", "image": { "data": "http://...", "alt": "Bakeware image"} }, { "id": 2, "name": "Cookware" "image": { "data": "http://...", "alt": "Cookware image"} }, { "id": 3, "name": "Cutlery" "image": { "data": "http://...", "alt": "Cutlery image"} } ] ``` In this case, this Handlebars statement: ``` {{pluck (limit categories 2) 'image.data'}} ``` ...would return a comma-separated list of image URLs. ## <a name="array_std"></a> Standard Array Helpers The following standard array helpers are supported on the Stencil framework. ### <a name="after"></a> {{after}} Returns all of the items in an array after the specified index. Opposite of [before](#before). Given the array `['a', 'b', 'c']`: #### Parameters * `array` {Array}: Collection. * `n` {Number}: Starting index (number of items to exclude). * `returns` {Array}: Array exluding `n` items. #### Example ```handlebars {{after array 1}} //=> '["c"]' ``` ### {{arrayify}} Casts the given `value` to an array. #### Parameters * `value` {any} * `returns` {Array} #### Example ```handlebars {{arrayify "foo"}} //=> '["foo"]' ``` ### <a name="before"></a> {{before}} Returns all of the items in the collection before the specified count. Opposite of [after](#after). Given the array `['a', 'b', 'c']`: #### Parameters * `array` {Array} * `n` {Number} * `returns` {Array}: Array excluding items after the given number. #### Example ```handlebars {{before array 2}} //=> '["a", "b"]' ``` ### {{eachIndex}} #### Parameters * `array` {Array} * `options` {Object} * `returns` {String} #### Example ```handlebars {{#eachIndex collection}} {{item}} is {{index}} {{/eachIndex}} ``` ### {{filter}} Block helper that filters the given array. Renders the block for values that evaluate to `true`; otherwise, returns the inverse block. #### Parameters * `array` {Array} * `value` {any} * `options` {Object} * `returns` {String} #### Example ```handlebars {{#filter array "foo"}}AAA{{else}}BBB{{/filter}} //=> 'BBB ``` ### <a name="first"></a> {{first}} Returns the first item, or first `n` items, of an array. #### Parameters * `array` {Array} * `n` {Number}: Number of items to return, starting at `0`. * `returns` {Array} #### Example Given the array `['a', 'b', 'c', 'd', 'e']`: ```handlebars {{first array 2}} //=> '["a", "b"]' ``` ### {{forEach}} 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. #### Parameters * `array` {Array} * `returns` {String} #### Example ```js var accounts = [ {'name': 'John', 'email': 'john@example.com'}, {'name': 'Malcolm', 'email': 'malcolm@example.com'}, {'name': 'David', 'email': 'david@example.com'} ]; // example usage // {{#forEach accounts}} // <a href="mailto:{{ email }}" title="Send an email to {{ name }}"> // {{ name }} // </a>{{#unless isLast}}, {{/unless}} // {{/forEach}} ``` ### {{inArray}} Block helper that renders the block if an array has the given `value`. Optionally, you can specify an inverse block to render when the array does not have the given value. #### Parameters * `array` {Array} * `value` {any} * `options` {Object} * `returns` {String} #### Example Given the array `['a', 'b', 'c']`: ```handlebars {{#inArray array "d"}} foo {{else}} bar {{/inArray}} //=> 'bar' ``` ### {{isArray}} Returns true if `value` is an es5 array. #### Parameters * `value` {any}: The value to test. * `returns` {Boolean} #### Example ```handlebars {{isArray "abc"}} //=> 'false' ``` ### <a name="last"></a> {{last}} Returns the last item, or last `n` items, of an array. Opposite of [first](#first). #### Parameters * `array` {Array} * `n` {Number}: Number of items to return, starting with the last item. * `returns` {Array} #### Example Given the array `['a', 'b', 'c', 'd', 'e']`: ```handlebars {{last array 2}} //=> '["d", "e"]' ``` ### {{lengthEqual}} Block helper that compares the length of the given array to the number passed as the second argument. If the array length is equal to the given `length`, the block is returned. Otherwise, you have the option of returning an inverse block. #### Parameters * `array` {Array} * `length` {Number} * `options` {Object} * `returns` {String} #### Example Given the array `['a', 'b', 'c', 'd', 'e']`: ```handlebars {{#lengthEqual array 10}}AAA{{else}}BBB{{/lengthEqual}} //=> 'BBB' ``` ### {{map}} Returns a new array, created by calling `function` on each element of the given `array`. #### Parameters * `array` {Array} * `fn` {Function} * `returns` {String} #### Example Given an array `['a', 'b', 'c']`: ```js // register `double` as a helper function double(str) { return str + str; } // then used like this: // {{map array double}} //=> '["aa", "bb", "cc"]' ``` ### {{some}} Block helper that returns the block *if* the callback returns true for some value in the given array. #### Parameters * `array` {Array} * `cb` {Function}: Callback function. * {Options}: Handlebars-provided options object. * `returns` {Array} #### Example Given the array `[1, 'b', 3]`: ```handlebars {{#some array isString}} Render me if the array has a string. {{else}} Render me if it doesn't. {{/some}} //=> 'Render me if the array has a string.' ``` ### {{sort}} Sorts the given `array`. If an array of objects is passed, you may optionally pass (as the second argument) a `key` to sort on. Alternatively, you may pass a sorting function as the second argument. #### Parameters * `array` {Array}: The array to sort. * `key` {String|Function}: The object key to sort by, or a sorting function. #### Example Given an array `['b', 'a', 'c']`: ```handlebars {{sort array}} //=> '["a", "b", "c"]' ``` ### {{sortBy}} Sorts 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. #### Parameters * `array` {Array}: The array to sort. * `props` {String|Function}: One or more properties to sort by, or sorting functions to use. #### Example Given an array `[{a: 'zzz'}, {a: 'aaa'}]`: ```handlebars {{sortBy array "a"}} //=> '[{"a":"aaa"}, {"a":"zzz"}]' ``` ### <a name="withAfter"></a> {{withAfter}} Use the items in the array, _after_ the specified index, as context inside a block. Opposite of [withBefore](#withBefore). #### Parameters * `array` {Array} * `idx` {Number} * `options` {Object} * `returns` {Array} #### Example Given the array `['a', 'b', 'c', 'd', 'e']`: ```handlebars {{#withAfter array 3}} {{this}} {{/withAfter}} //=> "de" ``` ### <a name="withBefore"></a> {{withBefore}} Use the items in the array, _before_ the specified index, as context inside a block. Opposite of [withAfter](#withAfter). #### Parameters * `array` {Array} * `idx` {Number} * `options` {Object} * `returns` {Array} #### Example Given the array `['a', 'b', 'c', 'd', 'e']`: ```handlebars {{#withBefore array 3}} {{this}} {{/withBefore}} //=> 'ab' ``` ### <a name="withFirst"></a> {{withFirst}} Uses a collection's first item inside a Handlebars block expression. Opposite of [withLast](#withLast). #### Parameters * `array` {Array} * `idx` {Number} * `options` {Object} * `returns` {String} #### Example Given the array `['a', 'b', 'c']`: ```handlebars {{#withFirst array}} {{this}} {{/withFirst}} //=> 'a' ``` [block:html] { "html": "<!--\n\n### {{withGroup}}\n\nBlock helper that groups array elements by the given `every` value.\n\n#### Parameters\n\n* `array` **{Array}**\n* `every` **{Number}**\n* `options` **{Object}**\n* `returns` **{String}**\n\n#### Example\n\nGiven the array `['a', 'b', 'c', 'd','e','f','g','h']`:\n\n```handlebars\n{{#withGroup array 4}}\n {{#each this}}\n {{.}}\n {{each}}\n <br>\n{{/withGroup}}\n//=> 'a','b','c','d'\n//=> 'e','f','g','h'\n```\n\n-->" } [/block] ### <a name="withLast"></a> {{withLast}} Use the last item, or `n` items, in an array as context inside a block. Opposite of [withFirst](#withFirst). #### Parameters * `array` {Array} * `idx` {Number}: The starting index. * `options` {Object} * `returns` {String} #### Example Given the array `['a', 'b', 'c']`: ```handlebars {{#withLast array}} {{this}} {{/withLast}} //=> 'c' ``` ### {{withSort}} Block helper that sorts a collection and exposes the sorted collection as context inside the block. #### Parameters * `array` {Array} * `prop` {String} * `options` {Object}: Specify `reverse="true"` to reverse the array. * `returns` {String} #### Example Given the array `['b', 'a', 'c']`: ```handlebars {{#withSort array}}{{this}}{{/withSort}} //=> 'abc' ``` # <a name="collection"></a> Collection Helpers The following standard helpers are available to handle collections. ### {{isEmpty}} Block helper that returns a block *if* the given collection is empty. If the collection is not empty, returns the inverse block (if supplied). #### Parameters * `collection` {Object} * `options` {Object} * `returns` {String} ### {{iterate}} Iterates over an array or object. #### Parameters * `context` {Object|Array}: The collection to iterate over. * `options` {Object} * `returns` {String} ### {{length}} Returns the length of the given collection. When using a string literal in the template, the string must be value JSON. See the example below. Otherwise, pass in an array or object from the context. #### Parameters * `value` {Array|Object|String} * `returns` {Number}: The length of the value. #### Example ```handlebars {{length '["a", "b", "c"]'}} //=> 3 //=> myArray = ['a', 'b', 'c', 'd', 'e']; {{length myArray}} //=> 5 //=> myObject = {'a': 'a', 'b': 'b'}; {{length myObject}} //=> 2 ``` # <a name="comparison"></a> Comparison Helpers The following standard helpers are available to handle comparisons. ### {{and}} Block helper that renders the block if *both* of the given values are truthy. If you specify an inverse block, it will be rendered when falsy. #### Parameters * `a` {any} * `b` {any} * `options` {Object}: Handlebars-provided options object. * `returns` {String} ### {{gt}} Block helper that renders a block if `a` is *greater than* `b`. If an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=""` hash argument for the second value. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{gte}} Block helper that renders a block if `a` is *greater than or equal to* `b`. If an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=""` hash argument for the second value. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object * `returns` {String}: Block, or inverse block if specified and falsy. ### {{has}} Block helper that renders a block if `value` has `pattern`. If an inverse block is specified, it will be rendered when falsy. #### Parameters * `val` {any}: The value to check. * `pattern` {any}: The pattern to check for. * `options` {Object}: Handlebars-provided options object. * `returns` {String} ### {{eq}} Block helper that renders a block if `a` is *equal to* `b`. If an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=""` hash argument for the second value. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{ifEven}} Returns `true` if the given value is an even number. #### Parameters * `number` {Number} * `options` {Object}: Handlebars-provided options object * `returns` {String}: Block, or inverse block if specified and falsy. #### Example ```handlebars {{#ifEven value}} render A {{else}} render B {{/ifEven}} ``` ### {{ifNth}} Conditionally renders a block *if* dividing the `a` operand by `b` yields a remainder of zero. If you specify an inverse block, it will be rendered when the remainder is *not* zero. #### Parameters * {}: {Number} * {}: {Number} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{ifOdd}} Block helper that renders a block if `value` is *an odd number*. If an inverse block is specified, it will be rendered when falsy. #### Parameters * `value` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. #### Example ```handlebars {{#ifOdd value}} render A {{else}} render B {{/ifOdd}} ``` ### {{is}} Block helper that renders a block if `a` is *equal to* `b`. If an inverse block is specified, it will be rendered when falsy. #### Parameters * `a` {any} * `b` {any} * `options` {Object}: Handlebars-provided options object. * `returns` {String} ### {{isnt}} Block helper that renders a block if `a` is *not equal to* `b`. If an inverse block is specified, it will be rendered when falsy. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object. * `returns` {String} ### {{lt}} Block helper that renders a block if `a` is *less than* `b`. If an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=""` hash argument for the second value. #### Parameters * `context` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{lte}} Block helper that renders a block if `a` is *less than or equal to* `b`. If an inverse block is specified, it will be rendered when falsy. You may optionally use the `compare=""` hash argument for the second value. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{neither}} Block helper that renders a block if *neither of* the given values are truthy. If you specify an inverse block, it will be rendered when falsy. #### Parameters * `a` {any} * `b` {any} * `options` {}: Handlebars options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{unlessEq}} Block helper that always renders the inverse block *unless `a` is equal to `b`*. #### Parameters * `a` {String} * `b` {String} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Inverse block by default, or block if falsy. ### {{unlessGt}} Block helper that always renders the inverse block *unless `a` is greater than `b`*. #### Parameters * `context` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Inverse block by default, or block if falsy. ### {{unlessLt}} Block helper that always renders the inverse block *unless `a` is less than `b`*. #### Parameters * `context` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{unlessGteq}} Block helper that always renders the inverse block *unless `a` is greater than or equal to `b`*. #### Parameters * `context` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. ### {{unlessLteq}} Block helper that always renders the inverse block *unless `a` is less than or equal to `b`*. #### Parameters * `context` {Object} * `options` {Object}: Handlebars-provided options object. * `returns` {String}: Block, or inverse block if specified and falsy. # <a name="control"></a> Control-Flow Helpers The following control-flow helpers have been customized for the Stencil framework: * [Conditional Control Flow](#ctrl_conditional) * [Loop Control Flow](#ctrl_loop) Beyond the formal examples below, syntax and examples for control-flow helpers are covered in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html). ## <a name="ctrl_conditional"></a> Conditional Control Flow The following helpers provide control structures that test for conditions, and branch accordingly. ### <a name="if"></a> {{if}} The `if` helper has been customized for Stencil, and has the following syntax: ``` {{#if <statement>}} ... {{else if}} /* optional else-if block */ ... {{else}} /* optional else block */ ... {{/if}} ``` The `<statement>` that the `if` helper evaluates can take these forms: - An object, as in: `{{#if object}}`. - A comparison expression, as in: `{{#if <lvalue> <operator> <rvalue>}}`. When you pass only one parameter to the `if` helper, it will return the following: - For an array parameter, the array's length. - For an empty object, a value of `false`. ### {{unless}} The `unless` helper is logically the opposite of the [`if` helper](#if), subject to the [restrictions](#unless_restrix) below. The syntax for `unless` can be found in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html). #### Formal Example ``` {{#unless statement}} ... /* block to display/execute unless statement is true */ {{/unless}} ``` #### <a name="unless_restrix"></a> Restrictions Statements using `unless` can refer to: * Objects, as in: `{{#unless object}}`. Unlike the `if` helper, `unless` on the Stencil framework does not support operators for comparison expressions. So, for example, the following expression would throw an error: ``` {{#unless this.alt "===" "hidden"}} ``` A workaround for this logic is to recast the expression as `if`/not-equal-to. So the following expression would be valid: ``` {{#if this.alt "!==" "hidden"}} ``` #### Stencil Example Here is a usage example from Stencil's Cornerstone base theme: The `templates/pages/search.html` template displays search results. In this template's section that displays search suggestions, an `#unless` loop determines what to output for the final result: ``` {{#each category_results}} <li class="category-suggestion"> {{#each this}} <a href="{{url}}">{{name}}</a> {{#unless @last}} > {{/unless}} {{/each}} </li> {{/each}} ``` ### Nested if/else Statements to Test for if/and Conditions Handlebars does not provide an `if`/`and` conditional structure. However, to test for multiple conditions, you can nest `if`/`else` statements, as shown in this example: ``` <nav class="navigation"> <ul> {{#each nav_items}} {{#if name '===' 'About Us'}} {{else}} {{#if name '===' 'Contact Us'}} {{else}} <li> <a class="top-level-nav-link" href="{{url}}"> {{name}} </a> </li> {{/if}} {{/if}} {{/each}} </ul> </nav> ``` ## <a name="ctrl_loop"></a> Loop Control Flow The following helpers are used to control loop execution. ### {{any}} The `any` helper is custom to Stencil. It checks whether at least one parameter evaluates to `true`. Parameters can be of different types (strings, numbers, arrays, or collections). #### Examples Formally, the `any` helper is invoked as shown here: ``` {{#any items selected=true}} ... /* block to display if any items have selected=true */ {{/any}} ``` A usage example is http://cornerstone-light-demo.mybigcommerce.com/shop-all/garden, a category page in Stencil's Cornerstone base theme that does _not_ have faceted search turned on. Shoppers will see "Shop by price" filters instead of product filters. The Stencil code controlling this component resides in the theme's `templates/components/category/shop-by-price.html` file. In this component, the `{{#any...` Handlebars helper is used to determine whether a shopper has selected one of the filters, and whether a "reset" button needs to be displayed: ``` {{#any shop_by_price selected=true}} <li class="navList-item"> <a href="{{category_url}}" class="navList-action"> {{lang 'category.reset'}} </a> </li> {{/any}} ``` ### {{all}} The `all` helper is custom to Stencil. It checks whether _all_ parameters evaluate to `true`. Parameters can be of different types (strings, numbers, arrays, or collections). #### Example ``` {{#all items theme_settings.optionA theme_settings.optionB}} ... /* block to display, if all items evaluate to true */ {{/all}} ``` ### contains Helper The `contains` helper is custom to Stencil. It checks whether the second parameter is included in the first parameter (typically a collection). #### Example ``` {{#contains fonts "Roboto"}} ... /* block to display, if any items contain "Roboto" */ {{/contains}} ``` ### {{each}} The syntax for the `each` helper can be found in the official Handlebars documentation [here](http://handlebarsjs.com/builtin_helpers.html). #### Example ``` {{#each array | object}} ... {{else}} /* optional block to execute if the the list is empty */ ... {{/each}} ``` #### Notes - Within an each block, use `{{this}}` to reference the current item. - Within an each block, use `{{@index}}` to reference the current item's index number. - When iterating through objects, `{{@key}}` returns the current key name. - `{{each}}` loops can be nested. ### {{for}} The `for` helper is a custom Stencil helper. In particular, this helper is limited to 100 iterations, in order to protect against infinite loops. The `for` helper has the following syntax, where parameters `<from>` and `<to>` are numbers, and `<context>` is an object: ``` {{#for <from> <to> <context>}} ... {{/for}} ``` # <a name="date"></a> Date Helpers The following standard Handlebars helper handles dates. ### {{moment}} Exposes `helper-date` as `moment`. # <a name="html"></a> HTML Helpers The following standard helpers are available to handle HTML content. ### {{ellipsis}} Truncates a string to the specified `length`, and appends an elipsis, `…`. #### Parameters * `str` {String} * `length` {Number}: The desired length of the returned string. * `returns` {String}: The truncated string. #### Example ```js {{ellipsis "<span>foo bar baz</span>", 7}} //=> 'foo bar…' ``` ### {{sanitize}} Strips HTML tags from a string, so that only the text nodes are preserved. #### Parameters * `str` {String}: The string of HTML to sanitize. * `returns` {String} #### Example ```js {{sanitize "<span>foo</span>"}} //=> 'foo' ``` ### {{ul}} Block helper for creating unordered lists (`<ul></ul>`). #### Parameters * `context` {Object} * `options` {Object} * `returns` {String} ### {{ol}} Block helper for creating ordered lists (`<ol></ol>`). #### Parameters * `context` {Object} * `options` {Object} * `returns` {String} ### {{thumbnailImage}} Returns a `<figure>` with a thumbnail linked to a full picture. #### Parameters * `context` {Object}: Object with values/attributes to add to the generated elements: * `context.alt` {String} * `context.src` {String} * `context.width` {Number} * `context.height` {Number} * `returns` {String}: HTML `<figure>` element with image and optional caption/link. # <a name="image"></a> Image Helpers The Stencil framework provides the following custom helper to manage images. ## {{getImage}} The `getImage` helper is custom to Stencil. It returns the URL for an image of the specified size. Values for the size parameter are defined in the `config.json` file’s `settings` section. This helper's parameters are: - `stencilImage`: a StencilImage. - `size`: a string. - `defaultImage` (optional): a string. Here is an example: ``` {{getImage image "thumbnail"}} ``` You can use the optional `defaultImage` parameter to specify an image that will be displayed in cases where the passed `stencilImage` value is null. # <a name="inflection"></a> Inflection Helpers The following standard helpers are available to transform strings. ### {{inflect}} Handles singular/plural forms. #### Parameters * `count` {Number} * `singular` {String}: The singular form * `plural` {String}: The plural form * `include` {String} * `returns` {String} ### {{ordinalize}} Returns an ordinalized number (as a string). #### Parameters * `val` {String}: The value to ordinalize. * `returns` {String}: The ordinalized number. #### Example ```handlebars {{ordinalize 1}} //=> '1st' {{ordinalize 21}} //=> '21st' {{ordinalize 29}} //=> '29th' {{ordinalize 22}} //=> '22nd' ``` # <a name="injection"></a> Injection Helpers The Stencil framework provides the following custom helpers to insert various resources into a page context: * [{{cdn}}](#cdn) * [{{getFontsCollection}}](#fonts) * [{{inject}} and {{jsContext}}](#inject) * [{{stylesheet}}](#stylesheet) ### <a name="cdn"></a> {{cdn}} The `cdn` helper is custom to Stencil. It is a URL transformer for content delivery networks. When you reference static assets that you have locally staged outside your `<theme-name>` directory and uploaded using WebDAV, place the `webdav:` prefix before each corresponding `assetPath` parameter. For example, a link like: ``` <img src="{{cdn "webdav:img/image.jpg"}}"> ``` ...will be transformed to a result like: ``` <img src="https://cdn.bcapp/3dsf74g/content/img/image.jpg"> ``` The presumed WebDAV root directory is `/content/`. (So, in this example, the `image.jpg` file had been uploaded to the WebDAV `/content/` directory.) The presumed local directory is `<theme-name>/assets/`, so you can omit that path when referencing its contained files or subdirectories. #### <a name="cdn-custom"></a> CDN Custom Endpoints You can define custom CDN endpoints to use with the `cdn` Handlebars helper. This facilitates including large, high-resolution image assets in themes, without exceeding BigCommerce's [50 MB limit](docs/bundling-and-submitting-a-theme#ship-zip-small) when bundling the theme for upload to BigCommerce. You could use a local version of the image in development, and a version on a CDN (for exampe, Imgix) in production. To do so, define custom CDN endpoints in your theme's [`config.json` file](/docs/configjson-reference#config-theme-settings), as highlighted in this example: ``` { "name": "Cornerstone", "version": "1.3.5", "settings": { "homepage_new_products_count": 12, "homepage_featured_products_count": 8, <b>"cdn": { "customcdn": { "path": "https://bigcommerce.customcdn.net" } }</b> } } ``` After defining an endpoint, you can use the short name in the same way as you would use a `webdav:` abbreviation: ``` <img src="{{cdn "customcdn:img/image.jpg"}}" /> ``` In local development, that helper would return: <pre>&lt;img src="<b>/assets/cdn/</b>customcdn/img/image.jpg" /&gt; </pre> Whereas in production, it would return: ``` <img src="https://bigcommerce.customcdn.net/img/image.jpg" /> ``` As highlighted above, the helper is configured to rewrite local URLs to a `<theme-name>/assets/cdn/` subfolder. The `stencil bundle` command excludes `assets/cdn/` subfolder from the bundle that it creates – circumventing the 50 MB size limit on the resulting .zip file. ### <a name="fonts"></a> {{getFontsCollection}} The `getFontsCollection` helper is custom to Stencil. It returns a link tag that loads all selected font collections. It takes no parameters. ### <a name="inject"></a> {{inject}} and {{jsContext}} Occasionally, your theme's client-side application code might need to incorporate dynamic data from the template context. Stencil provides two custom Handlebars helpers to help you achieve this: `inject` and `jsContext`. #### About the {{inject}} Helper The `inject` helper collects data definitions for injection into the `jsContext` variable. It composes a JSON object containing a subset of the template context to be sent to the browser. Parameters of the `inject` helper are: - `key`: a string. - `value`: multiple types supported. An `inject` call takes this form: ``` {{inject "stringBasedKey" contextValue}} ``` #### About the {{jsContext}} Helper The `jsContext` helper takes no parameters; it simply returns a JSON object containing all data collected by the `inject` helper. To retrieve the parsable JSON object, just call `{{jsContext}}` after all of the `{{inject}}` calls. #### {{inject}} + {{jsContext}} Example 1 To set up the product name in your client-side app, you can do the following, if you are in the context of a product: ``` {{inject "myProductName" product.title}} <script> // Note the lack of quotes around the jsContext handlebars helper, it becomes a string automatically. var jsContext = JSON.parse({{jsContext}}); // jsContext would output "{\"myProductName\": \"Sample Product\"}" which can feed directly into your JavaScript. console.log(jsContext.myProductName); // Will output: Sample Product </script> ``` ##### Notes on Example 1 You can compose your JSON object across multiple pages to create a different set of client-side data, depending on the currently loaded template context. The Stencil theme makes the `jsContext` available on the active page scoped. It also makes it available on the global `PageManager` objects, as `this.context`. #### {{inject}} Example 2 The following code uses `inject` to add all product IDs into JavaScript on category pages. It resides in a theme's `<theme-name>/templates/pages/category.html` template. Note the two `inject` calls directly under the front matter: ``` --- category: shop_by_price: true products: limit: {{theme_settings.categorypage_products_per_page}} --- {{inject "categoryProductsPerPage" theme_settings.categorypage_products_per_page}} {{inject "productIds" (pluck category.products 'id')}} {{#partial "head"}} {{#if pagination.category.previous}} <link rel="prev" href="{{pagination.category.previous}}"> {{/if}} {{#if pagination.category.next}} <link rel="next" href="{{pagination.category.next}}"> {{/if}} {{/partial}} {{#partial "page"}} {{> components/common/breadcrumbs breadcrumbs=breadcrumbs}} {{#if category.image}} <img src="{{getImage category.image 'zoom_size'}}"> {{/if}} <h1 class="page-heading">{{category.name}}</h1> {{{category.description}}} {{{snippet 'categories'}}} <div class="page"> <aside class="page-sidebar" id="faceted-search-container"> {{> components/category/sidebar}} </aside> <main class="page-content" id="product-listing-container"> {{#if category.products}} {{> components/category/product-listing}} {{else}} <p>{{lang 'categories.no_products'}}</p> {{/if}} </main> </div> {{/partial}} {{> layout/base}} ``` ### <a name="stylesheet"></a> {{stylesheet}} The `stylesheet` helper is custom to Stencil. It renders a link tag to insert a stylesheet into your theme. (This is required if you want Theme Editor to rewrite the stylesheet file when a merchant customizes their theme.) This helper returns an HTML string. #### Parameters - path: String containing the path to the theme's CSS stylesheet file. - Other parameters are optional, appended in the form: `key="value"`. #### Example ``` {{{stylesheet "assets/css/style.css" class="myStylesheet"}}} ``` # <a name="markdown"></a> Markdown Helpers The following standard helper is available to convert markdown. ### {{markdown}} Block helper that converts a string of inline markdown to HTML. #### Parameters * `context` {Object} * `options` {Object} * `returns` {String} #### Example ```html {{#markdown}} # Foo {{/markdown}} //=> <h1>Foo</h1> ``` # <a name="math"></a> Math Helpers The following standard helpers are available to handle mathematical operations. ### {{add}} Returns the sum of `a` plus `b`. #### Parameters * `a` {Number} * `b` {Number} ### {{subtract}} Return the differnece of `a` minus `b`. #### Parameters * `a` {Number} * `b` {Number} ### {{divide}} Divides `a` by `b`. #### Parameters * `a` {Number}: numerator * `b` {Number}: denominator ### {{multiply}} Multiplies `a` by `b`. #### Parameters * `a` {Number}: factor * `b` {Number}: multiplier ### {{floor}} Gets the `Math.floor()` of the given value. #### Parameters * `value` {Number} ### {{ceil}} Gets the `Math.ceil()` [ceiling] of the given value. #### Parameters * `value` {Number} ### {{round}} Rounds the given value. #### Parameters * `value` {Number} ### {{sum}} Returns the sum of all numbers in the given array. #### Parameters * `array` {Array}: Array of numbers to add up. * `returns` {Number} #### Example ```handlebars {{sum "[1, 2, 3, 4, 5]"}} //=> '15' ``` ### {{avg}} Returns the average of all numbers in the given array. #### Parameters * `array` {Array}: Array of numbers to add up and average. * `returns` {Number} #### Example ```handlebars {{avg "[1, 2, 3, 4, 5]"}} //=> '3' ``` # <a name="number"></a> Number Helpers The following standard helpers are available to handle and transform numbers. ### {{addCommas}} Adds commas to numbers. #### Parameters * `num` {Number} * `returns` {Number} ### {{phoneNumber}} Converts a string or number to a formatted phone number. #### Parameters * `num` {Number|String}: The phone number to format, e.g., `8005551212` * `returns` {Number}: The formatted phone number: `(800) 555-1212` ### {{random}} Generates a random number between two values. #### Parameters * `min` {Number} * `max` {Number} * `returns` {String} ### {{toAbbr}} Abbreviates numbers to the given number of `precision`. This is for general numbers, not size in bytes. #### Parameters * `number` {Number} * `precision` {Number} * `returns` {String} ### {{toExponential}} Returns a string, representing the given number in exponential notation. #### Parameters * `number` {Number} * `fractionDigits` {Number}: Optional. An integer specifying the number of digits to use after the decimal point. Defaults to as many digits as necessary to specify the number. * `returns` {Number} #### Example ```js {{toExponential number digits}}; ``` ### {{toFixed}} Formats the given number, using fixed-point notation. #### Parameters * `number` {Number} * `digits` {Number}: Optional. The number of digits to use after the decimal point. This can be a value between 0 and 20, inclusive, and implementations may optionally support a larger range of values. If this argument is omitted, it is treated as 0. * `returns` {Number} ### {{toFloat}} #### Parameters * `number` {Number} * `returns` {Number} ### {{toInt}} #### Parameters * `number` {Number} * `returns` {Number} ### {{toPrecision}} #### Parameters * `number` {Number} * `precision` {Number}: Optional. The number of significant digits. * `returns` {Number} # <a name="object"></a> Object Helpers The following standard helpers are available to handle objects. ### {{extend}} Extends the context with the properties of other objects. A shallow merge is performed to avoid mutating the context. #### Parameters * `objects` {Object}: One or more objects to extend. * `returns` {Object} ### {{forIn}} Block helper that iterates over the properties of an object, exposing each key and value on the context. #### Parameters * `context` {Object} * `options` {Object} * `returns` {String} ### {{forOwn}} Block helper that iterates over the *own* properties of an object, exposing each key and value on the context. #### Parameters * `obj` {Object}: The object to iterate over. * `options` {Object} * `returns` {String} ### {{toPath}} Takes arguments and, if they are string or number, converts them to a dot-delineated object property path. #### Parameters * `prop` {String|Number}: The property segments to assemble (can be multiple). * `returns` {String} ### {{get}} Uses property paths (`a.b.c`) to get a value or nested value from the context. Works as a regular helper or block helper. #### Parameters * `prop` {String}: The property to get, optionally using dot notation for nested properties. * `context` {Object}: The context object. * `options` {Object}: The Handlebars options object, if used as a block helper. * `returns` {String} ### {{getObject}} Uses property paths (`a.b.c`) to get an object from the context. Unlike the `get` helper, this helper will return the actual object, including the given property key. Also, this helper does not work as a block helper. #### Parameters * `prop` {String}: The property to get, optionally using dot notation for nested properties. * `context` {Object}: The context object. * `returns` {String} ### {{hasOwn}} Returns true if `key` is an own, enumerable property of the given `context` object. #### Parameters * `key` {String} * `context` {Object}: The context object. * `returns` {Boolean} #### Example ```handlebars {{hasOwn context key}} ``` ### {{isObject}} Returns true if `value` is an object. #### Parameters * `value` {String} * `returns` {Boolean} #### Example ```handlebars {{isObject "foo"}} //=> false ``` ### {{merge}} Deeply merges the properties of the given `objects` with the context object. #### Parameters * `object` {Object}: The target object. Pass an empty object to shallow-clone. * `objects` {Object} * `returns` {Object} ### {{JSONparse}} Block helper that parses a string using `JSON.parse`, then passes the parsed object to the block as context. #### Parameters * `string` {String}: The string to parse. * `options` {Object}: Handlebars options object. ### {{JSONstringify}} Stringifies an object using `JSON.stringify`. #### Parameters * `obj` {Object}: Object to stringify. * `returns` {String} # <a name="operator"></a> Operator Helpers The Stencil framework supports the following operator helpers: [Comparison Operators](#op_comparison) [Logical {{or}} Operator](#op_logical) [{{typeof}} Operator](#op_type) ## <a name="op_comparison"></a> Comparison Operators The following helpers are available to handle comparisons. | Helper | Definition | |--|--| |`==`| equal to | |`===`| equal to and equal type | |`!=`| not equal | |`<`| less than | |`>`| greater than | |`<=`| less than or equal to | |`>=`| greater than or equal to | ### Equal to and Equal Type Example To compare a string, use the `===` operator, as in this example from `templates/components/common/share.html`: ``` {{#if service '===' 'facebook'}} <svg> <use xlink:href="#icon-facebook"/> </svg> {{/if}} ``` ### Not Equal or Not Equal Type Example To improvise a `!==` (not equal or not equal type) comparison operator in Handlebars, you can use an [if](#if)/else structure as shown in this example: ``` <nav class="navigation"> <ul> {{#each nav_items}} {{#if name '===' 'About Us'}} {{else}} <li> <a class="top-level-nav-link" href="{{url}}"> {{name}} </a> </li> {{/if}} {{/each}} </ul> </nav> ``` ## <a name="op_logical"></a> Logical {{or}} Operator The `or` operator has been customized for Stencil. It checks whether at least one of its parameters evaluates to true, and has the following syntax: ``` {{#or 1 0 0 0 0 0 0}} ... /* execute this block if OR evaluates to true */ {{/or}} ``` ### Example Here is a usage example from Stencil's Cornerstone base theme, where it displays the cart's contents. The `templates/components/cart/content.html` template uses the `or` operator to determine whether an item contains either product options _or_ configurable fields. If at least one condition is true, the template displays an edit link for the item: ``` {{#or options configurable_fields}} <a href="#" data-item-edit="{{id}}">{{lang 'cart.checkout.change'}}</a> {{/or}} ``` ### Parameters The `or` operator's parameters are one or more strings, numbers, arrays, or collections. Parameters can be of mixed types. ## <a name="op_type"></a> {{typeof}} Operator The `typeof` operator returns the JavaScript type of a variable, such as: - string - number - boolean - object By design, an array will return a `typeof` value of `object`. ### Example ``` <script> if (typeof(addthis) === "object") { addthis.toolbox('.addthis_toolbox'); } </script> ``` # <a name="string"></a> String Helpers The following helpers are available to manipulate strings: * [Stencil Custom String Helpers](#string_custom) * [Standard String Helpers](#string_std) ## <a name="string_custom"></a> Stencil Custom String Helpers The following string helpers are custom to the Stencil framework. ### <a name="block-helper"></a> {{block}} </span> The `block` string helper is custom to Stencil. It defines a block of content, which can be overwritten by the [partial](#partial-helper) helper. ### {{concat}} The `concat` helper is custom to Stencil. It concatenates two string objects from the page's context, which are passed as parameters. It returns a new string object. #### Example ``` {{concat breadcrumbs.[0].name breadcrumbs.[0].url}} ``` ### {{dynamicComponent}} The `dynamicComponent` string helper is custom to Stencil. It inserts a dynamic partial from within the path that is supplied as its parameter. ### {{json}} The `json` string helper is custom to Stencil. You can use this helper to convert a JavaScript string object (from the page's context) into a JSON string object. ### {{lang}} The `lang` string helper is custom to Stencil. It maps keys to translation files, based on the locale indicated by the visitor’s browser. Its parameters are the following keys: - `translationKey`: a string. - `options`: key-value pairs. ### {{nl2br}} The `nl2br` helper is custom to Stencil. You can call this helper on a string object from the page's context, to convert its contained newline characters (`\r\n`, `\n\r`, `\r`, `\n`) to `<br>` tags. The `nl2br` helper returns a new string object. #### Example This Handlebars statement: ``` {{nl2br settings.address}} ``` ...will take this example string: ``` "settings": { "address": "\r\n685 Market St\r\nSan Francisco\r\n94105\r\nCA\r\n" } ``` ...and return ``` "<br>685 Market St<br>San Francisco<br>94105<br>CA<br>" ``` ### <a name="partial-helper"></a> {{partial}} The `partial` string helper is custom to Stencil. It overrides block content defined by the [block](#block-helper) helper. ### {{replace}} The `replace` string helper is custom to Stencil. It searches for the first parameter within the second parameter and, if it finds it, replaces the first parameter with the contents of the specified Handlebars block. For example, the following code would search for the string `needle` within the scope defined by `haystack`. If found, it would replace that string with the Handlebars block defined by `<context...replacement>`: ``` {{#replace "needle" haystack}} {{<context to use as a replacement>}} {{/replace}} ``` ### {{toLowerCase}} The `toLowerCase` helper is custom to Stencil. Use this helper to return a copy of a string object, in all-lowercase. The helper returns a new string object. #### Example This Handlebars statement: ``` {{toLowerCase head.title}} ``` ...will take this example string: ``` "head": { "title": "This is my TEST Store" } ``` ...and return: ``` "this is my test store" ``` ## <a name="string_std"></a> Standard String Helpers The following standard string helpers are supported on the Stencil framework. ### {{camelcase}} camelCases the characters in the given `string`. #### Parameters * `string` {String}: The string to camelcase. * `returns` {String} #### Example ```js {{camelcase "foo bar baz"}}; //=> 'fooBarBaz' ``` ### {{capitalize}} Capitalizes the first word in a sentence. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{capitalize "foo bar baz"}} //=> "Foo bar baz" ``` ### {{capitalizeAll}} Capitalizes all words in a string. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{capitalizeAll "foo bar baz"}} //=> "Foo Bar Baz" ``` ### {{center}} Centers a string, using non-breaking spaces. #### Parameters * `str` {String} * `spaces` {String} * `returns` {String} ### {{chop}} Like `trim`, but removes both extraneous whitespace *and non-word characters* from the beginning and end of a string. #### Parameters * `string` {String}: The string to chop. * `returns` {String} #### Example ```js {{chop "_ABC_"}} //=> 'ABC' {{chop "-ABC-"}} //=> 'ABC' {{chop " ABC "}} //=> 'ABC' ``` ### {{dashcase}} dash-cases the characters in `string`. Replaces non-word characters and periods with hyphens. #### Parameters * `string` {String} * `returns` {String} #### Example ```js {{dashcase "a-b-c d_e"}} //=> 'a-b-c-d-e' ``` ### {{dotcase}} dot.cases the characters in `string`. #### Parameters * `string` {String} * `returns` {String} #### Example ```js {{dotcase "a-b-c d_e"}} //=> 'a.b.c.d.e' ``` ### {{hyphenate}} Replaces spaces in a string with hyphens. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{hyphenate "foo bar baz qux"}} //=> "foo-bar-baz-qux" ``` ### {{isString}} Returns true if `value` is a string. #### Parameters * `value` {String} * `returns` {Boolean} #### Example ```handlebars {{isString "foo"}} //=> 'true' ``` ### {{lowercase}} Lowercases all characters in the given string. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{lowercase "Foo BAR baZ"}} //=> 'foo bar baz' ``` ### {{occurrences}} Returns the number of occurrences of `substring` within the given `string`. #### Parameters * `str` {String} * `substring` {String} * `returns` {Number}: Number of occurrences. #### Example ```handlebars {{occurrences "foo bar foo bar baz" "foo"}} //=> 2 ``` ### {{pascalcase}} PascalCases the characters in `string`. #### Parameters * `string` {String} * `returns` {String} #### Example ```js {{pascalcase "foo bar baz"}} //=> 'FooBarBaz' ``` ### {{pathcase}} path/cases the characters in `string`. #### Parameters * `string` {String} * `returns` {String} #### Example ```js {{pathcase "a-b-c d_e"}} //=> 'a/b/c/d/e' ``` ### {{plusify}} Replaces spaces in the given string with pluses. #### Parameters * `str` {String}: The input string * `returns` {String}: Input string with spaces replaced by plus signs #### Example ```handlebars {{plusify "foo bar baz"}} //=> 'foo+bar+baz' ``` ### {{reverse}} Reverses a string. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{reverse "abcde"}} //=> 'edcba' ``` ### {{sentence}} Sentence-cases the given string. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{sentence "hello world. goodbye world."}} //=> 'Hello world. Goodbye world.' ``` ### {{snakecase}} snake_cases the characters in the given `string`. #### Parameters * `string` {String} * `returns` {String} #### Example ```js {{snakecase "a-b-c d_e"}} //=> 'a_b_c_d_e' ``` ### {{split}} Splits `string` at the given `character`. #### Parameters * `string` {String}: The string to split. * `returns` {String} `character`: Default is `,` #### Example ```js {{split "a,b,c" ","}} //=> ['a', 'b', 'c'] ``` ### {{startsWith}} Tests whether a string begins with the given prefix. #### Parameters * `prefix` {String} * `testString` {String} * `options` {String} * `returns` {String} #### Example ```handlebars {{#startsWith "Goodbye" "Hello, world!"}} Whoops {{else}} Bro, do you even hello world? {{/startsWith}} ``` [block:html] { "html": "<!--\n\n### [{{strlen}}](lib/string.js#L442)\n\nReturns a string's length.\n\n#### Parameters\n\n* `string` **{String}**\n* `options` **{Object}**\n* `returns` **{Number}**\n\n#### Example\n\n```handlebars\n{{strlen \"Hello, world!\"}}\n//=> 13\n```\n\n-->" } [/block] ### {{titleize}} Title-cases the given string. #### Parameters * `str` {String} * `returns` {String} #### Example ```handlebars {{titleize "this is title case"}} //=> 'This Is Title Case' ``` ### {{trim}} Removes extraneous whitespace from the beginning and end of a string. #### Parameters * `string` {String}: The string to trim. * `returns` {String} #### Example ```js {{trim " ABC "}} //=> 'ABC' ``` ### {{uppercase}} Uppercases 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. #### Parameters * `str` {String}: The string to uppercase. * `options` {Object}: Handlebars options object. * `returns` {String} # <a name="url"></a> URL Helpers The following standard helpers are available to transform URLs. ### {{encodeURI}} Encodes a Uniform Resource Identifier (URI) component, by replacing each instance of certain characters by one, two, three, or four escape sequences that represent the UTF-8 encoding of the character. #### Parameters * `str` {String}: The un-encoded string. * `returns` {String}: The encoded string. ### {{decodeURI}} Decodes a Uniform Resource Identifier (URI) component. #### Parameters * `str` {String} * `returns` {String} ### {{urlResolve}} Takes a base URL, and an href URL, and resolves them as a browser would for an anchor tag. #### Parameters * `base` {String} * `href` {String} * `returns` {String} ### {{urlParse}} Parses a `url` string into an object. #### Parameters * `str` {String}: URL string. * `returns` {String}: Returns stringified JSON. ### {{stripQuerystring}} Strips the query string from a `url`. #### Parameters * `url` {String} * `returns` {String}: The URL without the queryString. ### {{stripProtocol}} Strips the protocol from a `url`. Useful for displaying media that might have an `http` protocol on secure connections. Will change `http://foo.bar` to `//foo.bar` #### Parameters * `str` {String} * `returns` {String}: The URL with the `http` protocol stripped. # <a name="misc"></a> Miscellaneous Helpers The following standard helpers are also supported on the Stencil framework. ### {{default}} Returns the first value, if that value is defined; otherwise, returns the "default" value. #### Parameters * `value` {any} * `defaultValue` {any} * `returns` {String} ### {{option}} Given the context `{options: {a: {b: {c: 'ddd'}}}}`, returns the given value of `prop` from `this.options`. #### Parameters * `prop` {String} * `returns` {any} #### Example ```handlebars {{option "a.b.c"}} <!-- results => `ddd` --> ``` ### {{noop}} Block helper that renders the block without taking any arguments. #### Parameters * `options` {Object} * `returns` {String} ### {{withHash}} Block helper that builds the context for the block from the options hash. #### Parameters * `options` {Object}: Handlebars-provided options object. [block:html] { "html": "<!-- [Hidden from String helpers:]\n## <span id=\"truncate-helper\"> truncate Helper </span>\n\nThe `truncate` helper is custom to Stencil, and works like the JavaScript `substring()` function: Use it to truncate a string to a specified length. The `truncate` helper's parameters are:\n\n- `str`: a string.\n- `length`: the maximum number of characters to return.\n\nThis helper will return a new string that contains the first `length` characters from the original `str` string. (If the original string contains fewer than `length` characters, `truncate` will return the whole string.)\n\n### Example\n\nAssume that a store owner wants to display a card, at the bottom of the store's home page, highlighting the most recent blog post. This card should display the blog thumbnail, the post's title, and the first 40 characters\nof the post's body. The following extract `truncate` call will extract those first 40 characters:\n\n```\n{{truncate 'blog.post.body.' 40)}\n```\n-->\n\n<!-- [Removed from Other helpers:]\n* [snippet Helper](#snippet)\n\n## <span id=\"snippet\"> snippet Helper </span>\n\nThe `snippet` helper is custom to Stencil. It defines an injection point, within a storefront page, where theme developers can inject JavaScript, HTML, or CSS to support applications.\n\n###Parameters: \n\n- [location](/docs/snippet-locations): a string.\n-->" } [/block]