diff --git a/docs/storefront/stencil/themes/context/handlebars-reference.mdx b/docs/storefront/stencil/themes/context/handlebars-reference.md similarity index 56% rename from docs/storefront/stencil/themes/context/handlebars-reference.mdx rename to docs/storefront/stencil/themes/context/handlebars-reference.md index b542b3c98..750532924 100644 --- a/docs/storefront/stencil/themes/context/handlebars-reference.mdx +++ b/docs/storefront/stencil/themes/context/handlebars-reference.md @@ -2,67 +2,249 @@ This article is a reference for [Stencil](/docs/storefront/stencil/start) supported [Handlebars](https://handlebarsjs.com/) helpers. It includes [custom helpers](#custom-helpers) documentation and a list of acceptlisted [standard helpers](#standard-helpers). -## Custom helpers - -The following table contains BigCommerce's open source [Handlebars helpers](https://github.com/bigcommerce/paper-handlebars/tree/master/helpers). - -| Helper | Category | Description | -|:-------|:---------|:------------| -| [limit](#limit) | array | Limits array to second argument. | -| [pluck](#pluck) | array | Uses search key to get values from collections. | -| [cdn](#cdn) | assets | A URL transformer for content delivery networks. | -| [earlyHint](#earlyhint) | assets | Reduces page load time and perceived latency. | -| [money](#money) | currency | Formats number length, thousands delimiter, and decimal delimiter. | -| [moment](#moment) | date | Use [momentjs](https://momentjs.com/) to format and calculate dates. | -| [getFontLoaderConfig](#getfontloaderconfig) | fonts | Returns font-loader config as a JSON string. | -| [getFontsCollection](#getfontscollection) | fonts | Returns `` elements for configured fonts. | -| [encodeHtmlEntities](#encodehtmlentities) | html | Encodes HTML entities. | -| [nl2br](#nl2br) | html | Converts newline characters to `
` tags. | -| [pre](#pre) | html | Renders preformatted text. | -| [resourceHints](#resourcehints) | html | Pre-fetches Google fonts. | -| [stylesheet](#stylesheet) | html | Renders a `` tag for inserting a stylesheet. | -| [lang](#lang) | i18n | Maps keys to translation files. | -| [langJson](#langjson) | i18n | Returns language translation keys as a JSON string. | -| [getContentImage](#getcontentimage) | images | Returns sized image URL from store's `/content` directory. | -| [getContentImageSrcset](#getcontentimagesrcset) | images | Returns source set of URLs for images in `/content`. | -| [getImage](#getimage) | images | Returns image URL for specified size. | -| [getImageManagerImage](#getimagemanagerimage) | images | Returns sized image URL for images in `/product_images/uploaded_images`. | -| [getImageManagerImageSrcset](#getimagemanagerimagesrcset) | images | Returns image srcset for images in `/product_images/uploaded_images`. | -| [getImageSrcset](#getimagesrcset) | images | Returns single image URL or list of URLs for different sizes. | -| [getImageSrcset1x2x](#getimagesrcset) | images | Returns single image URL or list of URLs for different sizes. The 1x and 2x designations indicate the ratio of device pixels to the intended image CSS pixels. | -| [any](#any) | logic | Renders block if **any** params are true. | -| [all](#all) | logic | Renders block if **all** params are true. | -| [compare](#compare) | logic | Compares values with JavaScript operators, including `typeof`. | -| [contains](#contains) | logic | Renders block if first param is in second param. | -| [for](#for) | logic | Iterates for range `a` to `b`, inclusive of `b`. | -| [if](#if) | logic | Renders block if statement is true. | -| [or](#or) | logic | Renders block if one or more parameters evaluate to true. | -| [unless](#unless) | logic | Renders block if a statement evaluates to false. | -| [option](#option) | misc | Returns the given value of `prop` from `this.options`. | -| [get](#get) | object| Use property paths (`a.b.c`) to get a value or nested value from the context. | -| [getObject](#getobject) | object| Use property paths (`a.b.c`) to get an object from the context. | -| [concat](#concat) | string | Concatenates two strings. | -| [multiConcat](#multiConcat) | string | Concatenates multiple strings. | -| [join](#join) | string | Joins an array of string elements into one string. | -| [json](#json) | string | Converts a JavaScript object into a JSON string. | -| [occurrences](#occurrences) | string | Returns the number of occurrences of substring within the given string. | -| [replace](#replace) | string | Replaces all instances of the first parameter in the second parameter. | -| [setURLQueryParam](#seturlqueryparam) | string | Appends keys values to a URL. | -| [stripQuerystring](#stripquerystring) | string | Removes a query string. | -| [strReplace](#strreplace) | string | Replaces some or all occurrences of a target substring within a subject string. | -| [toLowerCase](#tolowercase) | string | Converts a string to lowercase. | -| [truncate](#truncate) | string | Truncates a string. | -| [block](#block) | template | Defines a content block. | -| [dynamicComponent](#dynamiccomponent) | template | Inserts a dynamic partial in the specified path. | -| [inject](#inject) | template | Injects key values into `{{jsContext}}`. | -| [jsContext](#jscontext) | template | Returns JSON for all data injected by `{{inject}}`. | -| [partial](#partial) | template | Overrides content defined by `{{block}}`. | -| [region](#region) | template | Specifies a widget region. | -| [assignVar](#assignvar) | variables | Saves value to a variable. | -| [getVar](#getvar) | variables| Returns a variable value. | + +## Supported Standard Features +The following standard Handlebars features that are supported in Stencil themes. +All documentation of standard Handlebars features can be found in the [Handlebars documentation](https://handlebarsjs.com/guide/builtin-helpers.html). + +> **NOTE**: +> +> The standard Handlebars features `if` and `unless` have additional functionality provided by BigCommerce. +> See the [if](#if) and [unless](#unless) sections for more information. + + +| Helper | Category | Description | +|:---------------------------------------------------------------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------| +| [if](https://handlebarsjs.com/guide/builtin-helpers.html#if) | logical | Block helper that renders it's contents when the input is evaluated to be [Truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). | +| [unless](https://handlebarsjs.com/guide/builtin-helpers.html#unless) | logical | Block helper that renders it's contents when the input is evaluated to be [Falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy). | +| [else](https://handlebarsjs.com/guide/builtin-helpers.html#if) | logical | Alternative output for when a logical block conditionally renders its contents. | +| [each](https://handlebarsjs.com/guide/builtin-helpers.html#each) | iteration | Block helper that iterates over the items in a given array. | +| [with](https://handlebarsjs.com/guide/builtin-helpers.html#with) | object | Block helper that uses the given value as context for the block. The first provided value becomes "this" within the block. | +| [lookup](https://handlebarsjs.com/guide/builtin-helpers.html#lookup) | utility | Inline helper to retrieve a value at a specific index within a array, or a value using a given key from a object. | +| [log](https://handlebarsjs.com/guide/builtin-helpers.html#log) | debugging | Log the input value to the standard output ( stencil-cli ). | + + +## BigCommerce Provided Helpers + +The following tables contains BigCommerce's open source handlebars helpers which can be found at the BigCommerce [GitHub](https://github.com/bigcommerce/paper-handlebars/tree/master/helpers). + + +### Assets +Asset helpers are used to access and retrieve assets from your theme or store. + +| Helper | Category | Description | +|:--------------------------------------------|:---------|:----------------------------------------------------| +| [cdn](#cdn) | assets | A URL transformer for content delivery networks. | +| [earlyHint](#earlyhint) | assets | Reduces page load time and perceived latency. | +| [getFontLoaderConfig](#getfontloaderconfig) | fonts | Returns font-loader config as a JSON string. | +| [getFontsCollection](#getfontscollection) | fonts | Returns `` elements for configured fonts. | +| [lang](#lang) | i18n | Maps keys to translation files. | +| [langJson](#langjson) | i18n | Returns language translation keys as a JSON string. | + + +### Templating +Helpers that are used to define and render templates. + +| Helper | Category | Description | +|:----------------------------------------------------------|:---------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [block](#block) | template | Defines a content block. | +| [partial](#partial) | template | Overrides content defined by `{{block}}`. | +| [region](#region) | template | Specifies a widget region. | +| [inject](#inject) | template | Injects key values into `{{jsContext}}`. | +| [jsContext](#jscontext) | template | Returns JSON for all data injected by `{{inject}}`. | +| [dynamicComponent](#dynamiccomponent) | template | Inserts a dynamic partial in the specified path. | +| [option](#option) | misc | Returns the given value of `prop` from `this.options`. | +| [stylesheet](#stylesheet) | html | Renders a `` tag for inserting a stylesheet. | +| [getContentImage](#getcontentimage) | images | Returns sized image URL from store's `/content` directory. | +| [getContentImageSrcset](#getcontentimagesrcset) | images | Returns source set of URLs for images in `/content`. | +| [getImage](#getimage) | images | Returns image URL for specified size. | +| [getImageManagerImage](#getimagemanagerimage) | images | Returns sized image URL for images in `/product_images/uploaded_images`. | +| [getImageManagerImageSrcset](#getimagemanagerimagesrcset) | images | Returns image srcset for images in `/product_images/uploaded_images`. | +| [getImageSrcset](#getimagesrcset) | images | Returns single image URL or list of URLs for different sizes. | +| [getImageSrcset1x2x](#getimagesrcset) | images | Returns single image URL or list of URLs for different sizes. The 1x and 2x designations indicate the ratio of device pixels to the intended image CSS pixels. | +| [pre](#pre) | html | Renders preformatted text. | +| [resourceHints](#resourcehints) | html | Pre-fetches Google fonts. | + + +### Logic and Control Flow +| Helper | Category | Description | +|:----------------------|:-------------|:---------------------------------------------------------------| +| [if](#if) | control flow | Renders block if statement is true. | +| [unless](#unless) | control flow | Renders block if a statement evaluates to false. | +| [or](#or) | control flow | Renders block if one or more parameters evaluate to true. | +| [any](#any) | logic | Renders block if **any** params are true. | +| [all](#all) | logic | Renders block if **all** params are true. | +| [compare](#compare) | logic | Compares values with JavaScript operators, including `typeof`. | +| [contains](#contains) | logic | Renders block if first param is in second param. | + + +### Objects, Arrays, and Iteration +| Helper | Category | Description | +|:--------------------------------|:----------|:------------------------------------------------------------------------------| +| [limit](#limit) | array | Limits array to second argument. | +| [pluck](#pluck) | array | Uses search key to get values from collections. | +| [for](#for) | iteration | Iterates for range `a` to `b`, inclusive of `b`. | +| [get](#get) | object | Use property paths (`a.b.c`) to get a value or nested value from the context. | +| [getObject](#getobject) | object | Use property paths (`a.b.c`) to get an object from the context. | +| [concat](#concat) | string | Concatenates two strings. | +| [multiConcat](#multiConcat) | string | Concatenates multiple strings. | +| [join](#join) | string | Joins an array of string elements into one string. | +| [json](#json) | string | Converts a JavaScript object into a JSON string. | +| [JSONparse](#jsonparse) | object | Parses the given string using `JSON.parse`. | +| [JSONparseSafe](#jsonparsesafe) | object | Parses the given string safely using `JSON.parseSafe`. | +| [reverse](#reverse) | string | Reverses a string. | + + +### String Manipulation +| Helper | Category | Description | +|:--------------------------------------|:---------|:--------------------------------------------------------------------------------| +| [occurrences](#occurrences) | string | Returns the number of occurrences of substring within the given string. | +| [replace](#replace) | string | Replaces all instances of the first parameter in the second parameter. | +| [setURLQueryParam](#seturlqueryparam) | string | Appends keys values to a URL. | +| [stripQuerystring](#stripquerystring) | string | Removes a query string. | +| [strReplace](#strreplace) | string | Replaces some or all occurrences of a target substring within a subject string. | +| [toLowerCase](#tolowercase) | string | Converts a string to lowercase. | +| [truncate](#truncate) | string | Truncates a string. | + + +### Utility and Miscellaneous Others +| Helper | Category | Description | +|:------------------------------------------|:----------|:---------------------------------------------------------------------| +| [money](#money) | currency | Formats number length, thousands delimiter, and decimal delimiter. | +| [moment](#moment) | date | Use [momentjs](https://momentjs.com/) to format and calculate dates. | +| [encodeHtmlEntities](#encodehtmlentities) | html | Encodes HTML entities. | +| [nl2br](#nl2br) | html | Converts newline characters to `
` tags. | +| [typeof](#typeof) | misc | Returns the type of a variable. | + + + +### Custom data and variables +| Helper | Category | Description | +|:------------------------------|:----------|:----------------------------| +| [assignVar](#assignvar) | variables | Saves value to a variable. | +| [getVar](#getvar) | variables | Returns a variable value. | | [decrementVar](#decrementvar) | variables | Decrements a variable by 1. | | [incrementVar](#incrementvar) | variables | Increments a variable by 1. | + +### 3rd Party Helpers and Libraries +The following table contains generally accepted listed standard Handlebars helpers available to all Stencil themes. +Each helper is linked to its GitHub documentation including parameters and examples. + +| Helper | Category | Description | +|:-------------------------------------------------------------------------------------------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [after](https://github.com/helpers/handlebars-helpers#after) | array | Returns all of the items in an array after the specified index. | +| [arrayify](https://github.com/helpers/handlebars-helpers#arrayify) | array | Casts the given value to an array. | +| [before](https://github.com/helpers/handlebars-helpers#before) | array | Returns all of the items in the collection before the specified count. | +| [eachIndex](https://github.com/helpers/handlebars-helpers#eachIndex) | array | | +| [filter](https://github.com/helpers/handlebars-helpers#filter) | array | Block helper that filters the given array and renders the block for values that evaluate to `true`, otherwise the inverse block is returned. | +| [first](https://github.com/helpers/handlebars-helpers#first) | array | Returns the first item or first `n` items of an array. | +| [forEach](https://github.com/helpers/handlebars-helpers#forEach) | array | Iterates over each item in an array and exposes the current item in the array as context to the inner block. | +| [inArray](https://github.com/helpers/handlebars-helpers#inArray) | array | Block helper that renders the block if an array has the given `value`. | +| [isArray](https://github.com/helpers/handlebars-helpers#isArray) | array | Returns `true` if value is an es5 array. | +| [last](https://github.com/helpers/handlebars-helpers#last) | array | Returns the last item, or last `n` items of an array or string. | +| [length](https://github.com/helpers/handlebars-helpers#length) | array | Returns the length of the given string or array. | +| [lengthEqual](https://github.com/helpers/handlebars-helpers#lengthEqual) | array | Returns true if the length of the given value is equal to the given `length`. | +| [map](https://github.com/helpers/handlebars-helpers#map) | array | Returns a new array created by calling `function` on each element of the given array. | +| [some](https://github.com/helpers/handlebars-helpers#some) | array | Block helper that returns the block if the callback returns `true` for some value in the given array. | +| [sort](https://github.com/helpers/handlebars-helpers#sort) | array | Sorts the given array. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. | +| [sortBy](https://github.com/helpers/handlebars-helpers#sortBy) | array | Sorts an array. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. | +| [withAfter](https://github.com/helpers/handlebars-helpers#withAfter) | array | Uses the items in the array *after* the specified index as context inside a block. | +| [withBefore](https://github.com/helpers/handlebars-helpers#withBefore) | array | Uses the items in the array *before* the specified index as context inside a block. | +| [withFirst](https://github.com/helpers/handlebars-helpers#withFirst) | array | Uses the first item in a collection inside a handlebars block expression. | +| [withLast](https://github.com/helpers/handlebars-helpers#withLast) | array | Uses the last item or `n` items in an array as context inside a block. | +| [withSort](https://github.com/helpers/handlebars-helpers#withSort) | array | Block helper that sorts a collection and exposes the sorted collection as context inside the block. | +| [isEmpty](https://github.com/helpers/handlebars-helpers#isEmpty) | collection | Inline, subexpression, or block helper that returns `true` (or the block) if the given collection is empty, or `false` (or the inverse block, if supplied) if the collection is not empty. | +| [iterate](https://github.com/helpers/handlebars-helpers#iterate) | collection | Block helper that iterates over an array or object. If an array is given, `.forEach` is called, or if an object is given, `.forOwn` is called, otherwise the inverse block is returned. | +| [and](https://github.com/helpers/handlebars-helpers#and) | comparison | Helper that renders the block if both of the given values are truthy. If an inverse block is specified it will be rendered when falsy. | +| [default](https://github.com/helpers/handlebars-helpers#default) | comparison | Returns the first value that is not undefined, otherwise the default value is returned. | +| [eq](https://github.com/helpers/handlebars-helpers#eq) | comparison | Block helper that renders a block if `a` is equal to `b`. If an inverse block is specified it will be rendered when falsy. | +| [gt](https://github.com/helpers/handlebars-helpers#gt) | comparison | Block helper that renders a block if `a` is greater than `b`. If an inverse block is specified, it will be rendered when false. | +| [gte](https://github.com/helpers/handlebars-helpers#gte) | comparison | 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. | +| [has](https://github.com/helpers/handlebars-helpers#has) | comparison | Block helper that renders a block if value has pattern. If an inverse block is specified it will be rendered when falsy. | +| [ifEven](https://github.com/helpers/handlebars-helpers#ifEven) | comparison | Returns `true` if the given value is an even number. | +| [ifNth](https://github.com/helpers/handlebars-helpers#ifNth) | comparison | Conditionally renders a block if the remainder is zero when `a` operand is divided by `b`. If an inverse block is specified it will be rendered when the remainder is not zero. | +| [ifOdd](https://github.com/helpers/handlebars-helpers#ifOdd) | comparison | Block helper that renders a block if value is an odd number. If an inverse block is specified it will be rendered when falsy. | +| [is](https://github.com/helpers/handlebars-helpers#is) | comparison | Block helper that renders a block if `a` is equal to `b`. If an inverse block is specified it will be rendered when falsy. Similar to eq but does not do strict equality. | +| [isnt](https://github.com/helpers/handlebars-helpers#isnt) | comparison | 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. Similar to unlessEq but does not use strict equality for comparisons. | +| [lt](https://github.com/helpers/handlebars-helpers#lt) | comparison | Block helper that renders a block if `a` is less than `b`. If an inverse block is specified it will be rendered when falsy. | +| [lte](https://github.com/helpers/handlebars-helpers#lte) | comparison | 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. | +| [neither](https://github.com/helpers/handlebars-helpers#neither) | comparison | Block helper that renders a block if neither of the given values are truthy. If an inverse block is specified it will be rendered when falsy. | +| [unlessEq](https://github.com/helpers/handlebars-helpers#unlessEq) | comparison | Block helper that always renders the inverse block unless `a` is equal to `b`. | +| [unlessGt](https://github.com/helpers/handlebars-helpers#unlessGt) | comparison | Block helper that always renders the inverse block unless `a` is greater than `b`. | +| [unlessLt](https://github.com/helpers/handlebars-helpers#unlessLt) | comparison | Block helper that always renders the inverse block unless `a` is less than `b`. | +| [unlessGteq](https://github.com/helpers/handlebars-helpers#unlessGteq) | comparison | Block helper that always renders the inverse block unless `a` is greater than or equal to `b`. | +| [unlessLteq](https://github.com/helpers/handlebars-helpers#unlessLteq) | comparison | Block helper that always renders the inverse block unless `a` is less than or equal to `b`. | +| [sanitize](https://github.com/helpers/handlebars-helpers#sanitize) | html | Strips HTML tags from a string, so that only the text nodes are preserved. | +| [ul](https://github.com/helpers/handlebars-helpers#ul) | html | Block helper for creating unordered lists (``). | +| [ol](https://github.com/helpers/handlebars-helpers#ol) | html | Block helper for creating ordered lists (`
    `). | +| [thumbnailImage](https://github.com/helpers/handlebars-helpers#thumbnailImage) | html | Returns a `
    ` with a thumbnail linked to a full picture. | +| [inflect](https://github.com/helpers/handlebars-helpers#inflect) | inflection | Returns either the singular or plural inflection of a word based on the given count. | +| [ordinalize](https://github.com/helpers/handlebars-helpers#ordinalize) | inflection | Returns an ordinalized number as a string. | +| [markdown](https://github.com/helpers/handlebars-helpers#markdown) | markdown | Block helper that converts a string of inline markdown to HTML. | +| [add](https://github.com/helpers/handlebars-helpers#add) | math | Returns the sum of `a` plus `b`. | +| [avg](https://github.com/helpers/handlebars-helpers#avg) | math | Returns the average of all numbers in the given array. | +| [ceil](https://github.com/helpers/handlebars-helpers#ceil) | math | Returns the `Math.ceil()` of the given value. | +| [divide](https://github.com/helpers/handlebars-helpers#divide) | math | Divides `a` by `b`. | +| [floor](https://github.com/helpers/handlebars-helpers#floor) | math | Returns the `Math.floor()` of the given value. | +| [multiply](https://github.com/helpers/handlebars-helpers#multiply) | math | Returns the product of `a` times `b`. | +| [random](https://github.com/helpers/handlebars-helpers#random) | math | Generates a random number between two values. | +| [round](https://github.com/helpers/handlebars-helpers#round) | math | Rounds the given number. | +| [subtract](https://github.com/helpers/handlebars-helpers#subtract) | math | Returns the product of `a` minus `b`. | +| [sum](https://github.com/helpers/handlebars-helpers#sum) | math | Returns the sum of all numbers in the given array. | +| [noop](https://github.com/helpers/handlebars-helpers#noop) | misc | Block helper that renders the block without taking any arguments. | +| [withHash](https://github.com/helpers/handlebars-helpers#withHash) | misc | Block helper that builds the context for the block from the options hash. | +| [addCommas](https://github.com/helpers/handlebars-helpers#addCommas) | number | Adds commas to numbers. | +| [phoneNumber](https://github.com/helpers/handlebars-helpers#phoneNumber) | number | Converts a string or number to a formatted phone number. | +| [toAbbr](https://github.com/helpers/handlebars-helpers#toAbbr) | number | Abbreviates numbers to the given number of precision. This is for general numbers, not size in bytes. | +| [toExponential](https://github.com/helpers/handlebars-helpers#toExponential) | number | Returns a string representing the given number in exponential notation. | +| [toFixed](https://github.com/helpers/handlebars-helpers#toFixed) | number | Formats the given number using fixed-point notation. | +| [toFloat](https://github.com/helpers/handlebars-helpers#toFloat) | number | | +| [toInt](https://github.com/helpers/handlebars-helpers#toInt) | number | | +| [toPrecision](https://github.com/helpers/handlebars-helpers#toPrecision) | number | Returns a string representing the `Number` object to the specified precision. | +| [extend](https://github.com/helpers/handlebars-helpers#extend) | object | Extends the context with the properties of other objects. A shallow merge is performed to avoid mutating the context. | +| [forIn](https://github.com/helpers/handlebars-helpers#forIn) | object | Block helper that iterates over the properties of an object exposing each key and value on the context. | +| [forOwn](https://github.com/helpers/handlebars-helpers#forOwn) | object | Block helper that iterates over the own properties of an object, exposing each key and value on the context. | +| [toPath](https://github.com/helpers/handlebars-helpers#toPath) | object | Takes arguments and, if they are string or number, converts them to a dot-delineated object property path. | +| [hasOwn](https://github.com/helpers/handlebars-helpers#hasOwn) | object | Returns `true` if `key` is an own, enumerable property of the given context object. | +| [isObject](https://github.com/helpers/handlebars-helpers#isObject) | object | Returns `true` if value is an object. | +| [JSONstringify](https://github.com/helpers/handlebars-helpers#JSONstringify) | object | Stringifies an object using `JSON.stringify`. | +| [merge](https://github.com/helpers/handlebars-helpers#merge) | object | Deeply merges the properties of the given objects with the context object. | +| [pick](https://github.com/helpers/handlebars-helpers#pick) | object | Picks properties from the context object. | +| [camelcase](https://github.com/helpers/handlebars-helpers#camelcase) | string | camelCase the characters in the given string. | +| [capitalize](https://github.com/helpers/handlebars-helpers#capitalize) | string | Capitalizes the first word in a sentence. | +| [capitalizeAll](https://github.com/helpers/handlebars-helpers#capitalizeAll) | string | Capitalizes all words in a string. | +| [center](https://github.com/helpers/handlebars-helpers#center) | string | Centers a string using non-breaking spaces. | +| [chop](https://github.com/helpers/handlebars-helpers#chop) | string | Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string. | +| [dashcase](https://github.com/helpers/handlebars-helpers#dashcase) | string | Replaces non-word characters and periods with hyphens. | +| [dotcase](https://github.com/helpers/handlebars-helpers#dotcase) | string | `dot.case` the characters in a string. | +| [ellipsis](https://github.com/helpers/handlebars-helpers#ellipsis) | string | Truncates a string to the specified length, and appends it with an elipsis, `…`. | +| [hyphenate](https://github.com/helpers/handlebars-helpers#hyphenate) | string | Replaces spaces in a string with hyphens. | +| [isString](https://github.com/helpers/handlebars-helpers#isString) | string | Returns `true` if value is a string. | +| [lowercase](https://github.com/helpers/handlebars-helpers#lowercase) | string | Lowercase all characters in the given string. | +| [occurrences](https://github.com/helpers/handlebars-helpers#occurrences) | string | Returns the number of occurrences of `substring` within the given string. | +| [pascalcase](https://github.com/helpers/handlebars-helpers#pascalcase) | string | PascalCase the characters in a string. | +| [pathcase](https://github.com/helpers/handlebars-helpers#pathcase) | string | `path/case` the characters in a string. | +| [plusify](https://github.com/helpers/handlebars-helpers#plusify) | string | Replaces spaces in the given string with pluses. | +| [sentence](https://github.com/helpers/handlebars-helpers#sentence) | string | Sentence case the given string. | +| [snakecase](https://github.com/helpers/handlebars-helpers#snakecase) | string | `snake_case` the characters in the given string. | +| [split](https://github.com/helpers/handlebars-helpers#split) | string | Splits a string by the given character. | +| [startsWith](https://github.com/helpers/handlebars-helpers#startsWith) | string | Tests whether a string begins with the given prefix. | +| [titleize](https://github.com/helpers/handlebars-helpers#titleize) | string | Title case the given string. | +| [trim](https://github.com/helpers/handlebars-helpers#trim) | string | Removes extraneous whitespace from the beginning and end of a string. | +| [uppercase](https://github.com/helpers/handlebars-helpers#uppercase) | string | Uppercase all of the characters in the given string. If used as a block helper it will uppercase the entire block. This helper does not support inverse blocks. | +| [encodeURI](https://github.com/helpers/handlebars-helpers#encodeURI) | url | Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character. | +| [decodeURI](https://github.com/helpers/handlebars-helpers#decodeURI) | url | Decodes a Uniform Resource Identifier (URI) component. | +| [urlResolve](https://github.com/helpers/handlebars-helpers#urlResolve) | url | Takes a `base` URL and a `href` URL and resolves them as a browser would for an anchor tag. | +| [urlParse](https://github.com/helpers/handlebars-helpers#urlParse) | url | Parses a URL string into an object. | +| [stripProtocol](https://github.com/helpers/handlebars-helpers#stripProtocol) | url | Strips protocol from a URL. Useful for displaying media that may have an 'http' protocol on secure connections. | + + +# Helpers Documentation +Below is a list of example implementations and use cases for the custom helpers provided by BigCommerce platform. +For more information, see the [Handlebars GitHub Repo](https://github.com/bigcommerce/paper-handlebars). + + ### limit ```handlebars showLineNumbers @@ -320,7 +502,7 @@ This example produces an early hint in a `Link` header that looks like: ; rel=preload; as=script; crossorigin=anonymous ``` -The following example uses the `getFontsCollection` and `stylesheet` helpers. These helpers produce early hints by default, without using the `earlyHint` helper directly. +The following example uses the `getFontsCollection` and `stylesheet` helpers. These helpers produce early hints by default, without using the `earlyHint` helper directly. ```handlebars showLineNumbers @@ -335,7 +517,7 @@ The following example uses the `getFontsCollection` and `stylesheet` helpers. Th The output displays in a `Link` header that looks like: ``` showLineNumbers -Link: ; rel=preload; as=script; crossorigin=anonymous, +Link: ; rel=preload; as=script; crossorigin=anonymous, ; rel=preload; as=style, ; rel=preload; as=script ; rel=preload; as=style ``` @@ -1672,122 +1854,34 @@ Parse data safely with JSONparseSafe. This helper is similar to the JSONparse he - [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/jsonParseSafe.js) -## Standard helpers - - -The following table contains acceptlisted standard Handlebars helpers available to all Stencil themes. Each helper is linked to its GitHub documentation including parameters and examples. - -| Helper | Category | Description | -|:-------|:---------|:------------| -| [after](https://github.com/helpers/handlebars-helpers#after) | array | Returns all of the items in an array after the specified index. | -| [arrayify](https://github.com/helpers/handlebars-helpers#arrayify)| array | Casts the given value to an array. | -| [before](https://github.com/helpers/handlebars-helpers#before) | array | Returns all of the items in the collection before the specified count. | -| [each](https://handlebarsjs.com/guide/builtin-helpers.html#each) | array | Block helper that iterates over the items in a given array. | -| [eachIndex](https://github.com/helpers/handlebars-helpers#eachIndex) | array | | -| [filter](https://github.com/helpers/handlebars-helpers#filter) | array | Block helper that filters the given array and renders the block for values that evaluate to `true`, otherwise the inverse block is returned. | -| [first](https://github.com/helpers/handlebars-helpers#first) | array | Returns the first item or first `n` items of an array. | -| [forEach](https://github.com/helpers/handlebars-helpers#forEach) | array | Iterates over each item in an array and exposes the current item in the array as context to the inner block. | -| [inArray](https://github.com/helpers/handlebars-helpers#inArray) | array | Block helper that renders the block if an array has the given `value`. | -| [isArray](https://github.com/helpers/handlebars-helpers#isArray) | array | Returns `true` if value is an es5 array. | -| [last](https://github.com/helpers/handlebars-helpers#last) | array | Returns the last item, or last `n` items of an array or string. | -| [length](https://github.com/helpers/handlebars-helpers#length) | array | Returns the length of the given string or array. | -| [lengthEqual](https://github.com/helpers/handlebars-helpers#lengthEqual)| array | Returns true if the length of the given value is equal to the given `length`. | -| [map](https://github.com/helpers/handlebars-helpers#map) | array | Returns a new array created by calling `function` on each element of the given array. | -| [some](https://github.com/helpers/handlebars-helpers#some) | array | Block helper that returns the block if the callback returns `true` for some value in the given array. | -| [sort](https://github.com/helpers/handlebars-helpers#sort) | array | Sorts the given array. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. | -| [sortBy](https://github.com/helpers/handlebars-helpers#sortBy) | array | Sorts an array. If an array of objects is passed, you may optionally pass a `key` to sort on as the second argument. | -| [withAfter](https://github.com/helpers/handlebars-helpers#withAfter) | array | Uses the items in the array *after* the specified index as context inside a block. | -| [withBefore](https://github.com/helpers/handlebars-helpers#withBefore) | array | Uses the items in the array *before* the specified index as context inside a block. | -| [withFirst](https://github.com/helpers/handlebars-helpers#withFirst) | array | Uses the first item in a collection inside a handlebars block expression. | -| [withLast](https://github.com/helpers/handlebars-helpers#withLast) | array | Uses the last item or `n` items in an array as context inside a block. | -| [withSort](https://github.com/helpers/handlebars-helpers#withSort) | array | Block helper that sorts a collection and exposes the sorted collection as context inside the block. | -| [isEmpty](https://github.com/helpers/handlebars-helpers#isEmpty)| collection | Inline, subexpression, or block helper that returns `true` (or the block) if the given collection is empty, or `false` (or the inverse block, if supplied) if the collection is not empty. | -| [iterate](https://github.com/helpers/handlebars-helpers#iterate) | collection | Block helper that iterates over an array or object. If an array is given, `.forEach` is called, or if an object is given, `.forOwn` is called, otherwise the inverse block is returned. | -| [and](https://github.com/helpers/handlebars-helpers#and) | comparison | Helper that renders the block if both of the given values are truthy. If an inverse block is specified it will be rendered when falsy. | -| [default](https://github.com/helpers/handlebars-helpers#default) | comparison | Returns the first value that is not undefined, otherwise the default value is returned. | -| [eq](https://github.com/helpers/handlebars-helpers#eq) | comparison | Block helper that renders a block if `a` is equal to `b`. If an inverse block is specified it will be rendered when falsy. | -| [gt](https://github.com/helpers/handlebars-helpers#gt) | comparison | Block helper that renders a block if `a` is greater than `b`. If an inverse block is specified, it will be rendered when false. | -| [gte](https://github.com/helpers/handlebars-helpers#gte) | comparison | 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. | -| [has](https://github.com/helpers/handlebars-helpers#has) | comparison | Block helper that renders a block if value has pattern. If an inverse block is specified it will be rendered when falsy. | -| [ifEven](https://github.com/helpers/handlebars-helpers#ifEven) | comparison | Returns `true` if the given value is an even number. | -| [ifNth](https://github.com/helpers/handlebars-helpers#ifNth) | comparison | Conditionally renders a block if the remainder is zero when `a` operand is divided by `b`. If an inverse block is specified it will be rendered when the remainder is not zero. | -| [ifOdd](https://github.com/helpers/handlebars-helpers#ifOdd) | comparison | Block helper that renders a block if value is an odd number. If an inverse block is specified it will be rendered when falsy. | -| [is](https://github.com/helpers/handlebars-helpers#is) | comparison | Block helper that renders a block if `a` is equal to `b`. If an inverse block is specified it will be rendered when falsy. Similar to eq but does not do strict equality.| -| [isnt](https://github.com/helpers/handlebars-helpers#isnt) | comparison | 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. Similar to unlessEq but does not use strict equality for comparisons. | -| [lt](https://github.com/helpers/handlebars-helpers#lt) | comparison | Block helper that renders a block if `a` is less than `b`. If an inverse block is specified it will be rendered when falsy. | -| [lte](https://github.com/helpers/handlebars-helpers#lte) | comparison | 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.| -| [neither](https://github.com/helpers/handlebars-helpers#neither) | comparison | Block helper that renders a block if neither of the given values are truthy. If an inverse block is specified it will be rendered when falsy. | -| [unlessEq](https://github.com/helpers/handlebars-helpers#unlessEq) | comparison | Block helper that always renders the inverse block unless `a` is equal to `b`.| -| [unlessGt](https://github.com/helpers/handlebars-helpers#unlessGt) | comparison | Block helper that always renders the inverse block unless `a` is greater than `b`.| -| [unlessLt](https://github.com/helpers/handlebars-helpers#unlessLt) | comparison | Block helper that always renders the inverse block unless `a` is less than `b`. | -| [unlessGteq](https://github.com/helpers/handlebars-helpers#unlessGteq) | comparison | Block helper that always renders the inverse block unless `a` is greater than or equal to `b`. | -| [unlessLteq](https://github.com/helpers/handlebars-helpers#unlessLteq) | comparison | Block helper that always renders the inverse block unless `a` is less than or equal to `b`.| -| [sanitize](https://github.com/helpers/handlebars-helpers#sanitize) | html | Strips HTML tags from a string, so that only the text nodes are preserved.| -| [ul](https://github.com/helpers/handlebars-helpers#ul) | html | Block helper for creating unordered lists (`
      `). | -| [ol](https://github.com/helpers/handlebars-helpers#ol) | html | Block helper for creating ordered lists (`
        `). | -| [thumbnailImage](https://github.com/helpers/handlebars-helpers#thumbnailImage) | html | Returns a `
        ` with a thumbnail linked to a full picture. | -| [inflect](https://github.com/helpers/handlebars-helpers#inflect) | inflection | Returns either the singular or plural inflection of a word based on the given count. | -| [ordinalize](https://github.com/helpers/handlebars-helpers#ordinalize) | inflection | Returns an ordinalized number as a string. | -| [markdown](https://github.com/helpers/handlebars-helpers#markdown) | markdown | Block helper that converts a string of inline markdown to HTML. | -| [add](https://github.com/helpers/handlebars-helpers#add) | math | Returns the sum of `a` plus `b`. | -| [avg](https://github.com/helpers/handlebars-helpers#avg) | math| Returns the average of all numbers in the given array. | -| [ceil](https://github.com/helpers/handlebars-helpers#ceil) | math| Returns the `Math.ceil()` of the given value. | -| [divide](https://github.com/helpers/handlebars-helpers#divide)| math| Divides `a` by `b`. | -| [floor](https://github.com/helpers/handlebars-helpers#floor) | math | Returns the `Math.floor()` of the given value. | -| [multiply](https://github.com/helpers/handlebars-helpers#multiply) | math | Returns the product of `a` times `b`. | -| [random](https://github.com/helpers/handlebars-helpers#random) | math | Generates a random number between two values. | -| [round](https://github.com/helpers/handlebars-helpers#round) | math | Rounds the given number. | -| [subtract](https://github.com/helpers/handlebars-helpers#subtract) | math | Returns the product of `a` minus `b`. | -| [sum](https://github.com/helpers/handlebars-helpers#sum) | math | Returns the sum of all numbers in the given array. | -| [noop](https://github.com/helpers/handlebars-helpers#noop) | misc | Block helper that renders the block without taking any arguments. | -| [withHash](https://github.com/helpers/handlebars-helpers#withHash) | misc| Block helper that builds the context for the block from the options hash. | -| [addCommas](https://github.com/helpers/handlebars-helpers#addCommas) | number | Adds commas to numbers. | -| [phoneNumber](https://github.com/helpers/handlebars-helpers#phoneNumber) | number | Converts a string or number to a formatted phone number. | -| [toAbbr](https://github.com/helpers/handlebars-helpers#toAbbr) | number | Abbreviates numbers to the given number of precision. This is for general numbers, not size in bytes. | -| [toExponential](https://github.com/helpers/handlebars-helpers#toExponential) | number | Returns a string representing the given number in exponential notation. | -| [toFixed](https://github.com/helpers/handlebars-helpers#toFixed)|number| Formats the given number using fixed-point notation. | -| [toFloat](https://github.com/helpers/handlebars-helpers#toFloat) | number | | -| [toInt](https://github.com/helpers/handlebars-helpers#toInt) | number | | -| [toPrecision](https://github.com/helpers/handlebars-helpers#toPrecision) |number| Returns a string representing the `Number` object to the specified precision. | -| [extend](https://github.com/helpers/handlebars-helpers#extend) | object | Extends the context with the properties of other objects. A shallow merge is performed to avoid mutating the context. | -| [forIn](https://github.com/helpers/handlebars-helpers#forIn) | object | Block helper that iterates over the properties of an object exposing each key and value on the context. | -| [forOwn](https://github.com/helpers/handlebars-helpers#forOwn) |object| Block helper that iterates over the own properties of an object, exposing each key and value on the context. | -| [toPath](https://github.com/helpers/handlebars-helpers#toPath) | object | Takes arguments and, if they are string or number, converts them to a dot-delineated object property path. | -| [hasOwn](https://github.com/helpers/handlebars-helpers#hasOwn) | object | Returns `true` if `key` is an own, enumerable property of the given context object. | -| [isObject](https://github.com/helpers/handlebars-helpers#isObject) | object | Returns `true` if value is an object. | -| [JSONparse](#jsonparse) | object | Parses the given string using `JSON.parse`. | -| [JSONparseSafe](#jsonparsesafe) | object | Parses the given string safely using `JSON.parseSafe`. | -| [JSONstringify](https://github.com/helpers/handlebars-helpers#JSONstringify) | object | Stringifies an object using `JSON.stringify`. | -| [merge](https://github.com/helpers/handlebars-helpers#merge) |object| Deeply merges the properties of the given objects with the context object. | -| [pick](https://github.com/helpers/handlebars-helpers#pick) | object | Picks properties from the context object. | -| [camelcase](https://github.com/helpers/handlebars-helpers#camelcase) |string| camelCase the characters in the given string. | -| [capitalize](https://github.com/helpers/handlebars-helpers#capitalize) | string | Capitalizes the first word in a sentence. | -| [capitalizeAll](https://github.com/helpers/handlebars-helpers#capitalizeAll) | string | Capitalizes all words in a string. | -| [center](https://github.com/helpers/handlebars-helpers#center) |string| Centers a string using non-breaking spaces. | -| [chop](https://github.com/helpers/handlebars-helpers#chop) | string | Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string. | -| [dashcase](https://github.com/helpers/handlebars-helpers#dashcase) | string | Replaces non-word characters and periods with hyphens. | -| [dotcase](https://github.com/helpers/handlebars-helpers#dotcase) | string | `dot.case` the characters in a string. | -| [ellipsis](https://github.com/helpers/handlebars-helpers#ellipsis) | string | Truncates a string to the specified length, and appends it with an elipsis, `…`. | -| [hyphenate](https://github.com/helpers/handlebars-helpers#hyphenate) | string | Replaces spaces in a string with hyphens. | -| [isString](https://github.com/helpers/handlebars-helpers#isString) | string | Returns `true` if value is a string. | -| [lowercase](https://github.com/helpers/handlebars-helpers#lowercase) | string | Lowercase all characters in the given string. | -| [occurrences](https://github.com/helpers/handlebars-helpers#occurrences) | string | Returns the number of occurrences of `substring` within the given string. | -| [pascalcase](https://github.com/helpers/handlebars-helpers#pascalcase) | string | PascalCase the characters in a string. | -| [pathcase](https://github.com/helpers/handlebars-helpers#pathcase) | string | `path/case` the characters in a string. | -| [plusify](https://github.com/helpers/handlebars-helpers#plusify) | string | Replaces spaces in the given string with pluses. | -| [reverse](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/3p/string.js#L280) | string | Reverses a string. | -| [sentence](https://github.com/helpers/handlebars-helpers#sentence) | string | Sentence case the given string. | -| [snakecase](https://github.com/helpers/handlebars-helpers#snakecase) | string | `snake_case` the characters in the given string. | -| [split](https://github.com/helpers/handlebars-helpers#split) | string | Splits a string by the given character. | -| [startsWith](https://github.com/helpers/handlebars-helpers#startsWith) | string | Tests whether a string begins with the given prefix. | -| [titleize](https://github.com/helpers/handlebars-helpers#titleize) | string | Title case the given string. | -| [trim](https://github.com/helpers/handlebars-helpers#trim) | string | Removes extraneous whitespace from the beginning and end of a string. | -| [uppercase](https://github.com/helpers/handlebars-helpers#uppercase) | string | Uppercase all of the characters in the given string. If used as a block helper it will uppercase the entire block. This helper does not support inverse blocks. | -| [encodeURI](https://github.com/helpers/handlebars-helpers#encodeURI) | url | Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character. | -| [decodeURI](https://github.com/helpers/handlebars-helpers#decodeURI) | url | Decodes a Uniform Resource Identifier (URI) component. | -| [urlResolve](https://github.com/helpers/handlebars-helpers#urlResolve) | url | Takes a `base` URL and a `href` URL and resolves them as a browser would for an anchor tag. | -| [urlParse](https://github.com/helpers/handlebars-helpers#urlParse) | url | Parses a URL string into an object. | -| [stripProtocol](https://github.com/helpers/handlebars-helpers#stripProtocol) | url | Strips protocol from a URL. Useful for displaying media that may have an 'http' protocol on secure connections. | + + +### typeof + +Evaluate the "type" of an input variable. See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof) for more information. + +```handlebars showLineNumbers +{{typeof value}} +``` + +#### Parameters + +- `value` (String|Number|Array|Object): The value to check. + +#### Example + +```handlebars +{{#JSONparseSafe '{"string":"John Doe","number":123,"boolean":true,"nullValue":null,"objectValue":{"name":"John"},"array":["John","Doe"]}'}} + {{typeof undefined}} + {{typeof null}} + {{typeof this.boolean}} + {{typeof this.number}} + {{typeof this.string}} + {{typeof this}} +{{/JSONparseSafe}} +``` + +- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/typeof.js) ## Contributing to helpers