clayhandlebars

A collection of helpers and partials for handlebars

Installation

npm install --save clayhandlebars

Usage

By default, clayhandlebars will export a function that returns a new handlebars instance with all of the helpers and partials added.

var hbs = require('clayhandlebars')(),
  template = hbs.compile('<h1>Hello {{ place }}!</h1>'),
  result = template({ place: 'World' });

// result: <h1>Hello World!</h1>

Passing env in

If you want to configure and use your own handlebars environment, you can pass it through

var Handlebars = require('express-handlebars'),
  env = new Handlebars({ /* some config */ }),
  hbs = require('clayhandlebars')(env),
  app = require('express')();

app.engine('handlebars', hbs.engine);
app.set('view engine', 'handlebars');

Helpers

Currently 57 helpers in 10 categories:

arrays

components

addAnnotatedTextAria ( code | tests )
addInSplashAds ( code | tests )
addOrderedIds ( code | tests )
adsToDummies ( code | tests )
displaySelf ( code | tests )
displaySelfAll ( code | tests )
filterComponents ( code | tests )
getComponentName ( code | tests )

conditionals

html

misc

numbers

objects

strings

time

urls

urlencode ( code | tests )

arrays

join ( code | tests )

join all elements of array into a string, optionally using a given separator

Params

array (array)
[sep] (string) the separator to use (defaults to ', ')

Returns (string)

Example

{{ join ["a", "b", "c"] "-" }}
//=> "a-b-c"

map ( code | tests )

map through array, call function on each item

Params

array (array|string) of items to iterate through
fn (function) to run on each item

Returns (array)

Example

{{ join (map [{ a: "1" }, { a: "2" }] (getProp "a")) }}
//=> "1, 2"

range ( code | tests )

return an array of numbers, in order
note: can be used inline or as a block helper (will iterate through all numbers)

Params

[start] (number) on this number (defaults to 0)
end (number) on this number
[options] (object)

Returns (array)

Example

{{#range 1 5}}{{ this }}{{/range}}
//=> 1234

components

addAnnotatedTextAria ( code | tests )

Add aria to phrases in paragraphs, corresponds to annotation ids.

Params

content (array) list of components

Returns (array) content

Example

{{> component-list (addAnnotatedTextAria content)}}

addInSplashAds ( code | tests )

Add in article ads to list of components in an article

Params

content (array) the list of components in the article
articleData (object) the entire article's data, used to pull in the different ad units defined
afterComponent (string) the component type to insert the ad after

Returns (object) splash

Example

{{> component-list (addInSplashAds content this "picks-links-container") }}

addOrderedIds ( code | tests )

Add ordered ids to components within a componentlist

Params

content (Array) list of components
prefix (string) prefix for the ids
[offset] (number) index to start at, defaults to 1

Returns (Array) content

Example

{{> component-list (addOrderedIds content "annotation-") }}

adsToDummies ( code | tests )

Given a list of component instance objects, replace each ad component
with a site's "dummy" ad instance, matching the properties of the ad
instance replaced.

Params

content (Array) an array of component instance objects, e.g. [{_ref: 'a/uri/etc', foo: 'bar'}, ...]
[dummyAd] (Object) an ad object with the reference to the dummy ad instance

Returns (Array) an array of components, with ads replaced with the ad dummy instance

displaySelf ( code | tests )

Return the first component (from a list of components) with a truthy displaySelf property. Used by Spaces.

Params

components (array) with displaySelf properties

Returns (object) first component with displaySelf: true

Example

{{> component-list (displaySelf content) }}

displaySelfAll ( code | tests )

Return all components (from a list of components) with a truthy displaySelf property. Used by Spaces.

Params

components (array) with displaySelf properties

Returns (array) all components with displaySelf: true

Example

{{> component-list (displaySelfAll content) }}

filterComponents ( code | tests )

filters component references in a component list

Params

content (array) list of components
shouldKeep (boolean) if true, only matching component references are returned; if false, then only non-matching component references are returned
componentName (string) name of the component to remove from the list (accepts multiple arguments)

Returns (array) content

Example

{{> component-list (filterComponents content false "some-component" "another-component")}}

getComponentName ( code | tests )

get a component's name from the reference

Params

ref (string) full component uri

Returns (string)

Example

{{ getComponentName "domain.com/components/foo" }}
//=> foo

conditionals

compare ( code | tests )

compare two values, with an operator.
note: if you don't pass an operator, it assumes ===
note: this can be used as a block or inline helper

Params

left (*) left value
operator (string) to compare with
right (*) right value
[options] (object)

Returns (string) if inline, otherwise calls block functions

Example

{{ compare 10 ">" 5 }}
//=> "true"

if ( code | tests )

overwrite default handlebars 'if' helper
this adds support for an inline helper, {{if foo bar}} (if foo is truthy, print bar)
as well as an inline if/else helper, {{if foo bar else=baz}} (if foo is truthy, print bar. otherwise, print baz)

Params

conditional (*) to check for truthiness
value (*) to print if conditional is truthy
[options] (object)

Returns (string) if inline, otherwise calls block functions

Example

{{ if true "bar" else="baz" }}
//=> "bar"

ifAll ( code | tests )

block helper for checking if ALL arguments passed in are truthy

Returns (string) calls block functions

Example

{{#ifAll foo bar baz}}
  all are truthy
{{else}}
  not all are truthy
{{/ifAll}}

ifAny ( code | tests )

block helper for checking if ANY arguments passed in are truthy

Returns (string) calls block functions

Example

{{#ifAny foo bar baz}}
  at least one is truthy
{{else}}
  none are truthy
{{/ifAny}}

ifNone ( code | tests )

block helper for checking if NO arguments passed in are truthy

Returns (string) calls block functions

Example

{{#ifNone foo bar baz}}
  all are falsy
{{else}}
  not all are falsy
{{/ifNone}}

modulo ( code | tests )

compare the modulo of two values to a third value

Params

dividend (number)
divisor (number)
remainder (number)
[options] (object)

Returns (string) if inline, otherwise calls block functions

Example

{{modulo 3 2 1}}
//=> true

unlessAll ( code | tests )

block helper for checking that NOT ALL arguments passed in are truthy
note: this is the inverse of the ifAll helper

Returns (string) calls block functions

Example

{{#unlessAll foo bar baz}}
  not all are truthy
{{else}}
  all are truthy
{{/ifAll}}

html

perWordClasses ( code | tests )

wraps each word in spans with classes allowing designers and devs to target individual words with css

Params

html (string) to add classes to
options (object)
[options.hash.perLetter] (boolean) if you want an extra span wrapping each letter. defaults to true

Returns (string) words wrapped in classes

Example

{{{ perWordClasses "One two three" perLetter=false }}}
//=> <span class="_one">One</span> <span class="_two">two</span> <span class="_three">three</span>

striptags ( code | no tests )

straight passthrough to striptags

Example

{{ striptags "<p><b>Hello</b> <em>World!</em></p>" }}
//=> Hello World!

wordCount ( code | tests )

counts the words in a string of text or html

Params

[html] (string)

Returns (number) the number of words

Example

{{wordCount "<div> This is <b> cool </b> </div>"}}
//=> 3

misc

default ( code | tests )

return the first value if it's not empty, otherwise return the second value
note: this overrides handlebar-helper's default helper, since that only checks for null values (not all falsy/empty values)

Params

value (*) to check
defaultValue (*) value to return if first value is falsy

Example

{{ default "" "foo" }}
//=> foo

extractImgHeight ( code | tests )

Extract the height of a mediaplay image given the image URL.

Params

url (string)

Returns (object) extracted height

Example

{{ extractImgHeight feedImgUrl }}
//=> 946

extractImgWidth ( code | tests )

Extract the width of a mediaplay image given the image URL.

Params

url (string)

Returns (Object) extracted width

Example

{{ extractImgWidth feedImgUrl }}
//=> 1420

indexOf ( code | tests )

get the index of something inside something else

Params

outside (*) array, string, etc (anything with indexOf )
inside (*) anything that can exist inside something else

Returns (number)

Example

{{ indexOf "foo" "o" }}
//=> 1

set ( code | tests )

set data into current context or other optional context/object
note: doesn't return anything

Params

[obj] (object) context or object for storing data beyond current context
key (string) _set() key/path
val (*) value to set

Example

{{ set "a.b.c" "abc" }}{{ a.b.c }}
//=> "abc"

slugToSiteName ( code | tests )

return comma-separated site names from comma-separated slugs

Params

slugs (string) comma-separated string of slugs

Returns (string)

Example

{{ slugToSiteName (commaSeparated crosspost) }}

numbers

add ( code | tests )

Return the product of a plus b

Params

a (number)
b (number)

Returns (number)

Example

{{ add 3 2 }}
//=> 5

addCommas ( code | tests )

add commas to numbers.
note: this overrides handlebars-helpers' addCommas helper because we want to preserve zeroes in decimals (for money)
e.g. 1234.50 → 1,234.50 instead of 1,234.5
note: decimals are only preserved if passed in as a string (they don't exist in js numbers)

Params

num (number|string)

Returns (string)

Example

{{ addCommas "1234.50" }}
//=> "1,234.50"

addOrdinalSuffix ( code | tests )

add ordinal after a number
e.g. 1 → 1st , 2 → 2nd , 3 → 3rd

Params

num (number|string) number to add ordinal after

Returns (string)

Example

{{ addOrdinalSuffix 1 }}
//=> 1st

divide ( code | tests )

Return the result of a divided by b

Params

a (number)
b (number)

Returns (number)

Example

{{ divide 100 4 }}
//=> 25

multiply ( code | tests )

Return the product of a multiplied by b

Params

a (number)
b (number)

Returns (number)

Example

{{ multiply 10 10 }}
//=> 100

num ( code | tests )

converts things (usually strings) into numbers
note: this is useful if you need to parse user input

Params

x (number|string) thing to convert into a number

Returns (string)

Example

{{ num "123" }}
//=> 123

random ( code | tests )

Returns a number within a specified range.

Params

min (Number)
max (Number)

Returns (Number)

round ( code | tests )

Return the rounded value of x , optionally always rounding up or down

Params

x (number|string)
[direction] (string) always round x up or down, expects values 'up' or 'down', otherwise just round

Returns (number)

Example

{{ round 1.5 "down" }}
//=> 1

subtract ( code | tests )

Return the product of a minus b

Params

a (number)
b (number)

Returns (number)

Example

{{ subtract 3 2 }}
//=> 1

toK ( code | tests )

format thousands using k
e.g. 1000 → 1k

Params

x (number|string) number to format

Returns (string)

Example

{{ toK 1234.5 }}
//=> "1.2k"

objects

commaSeparated ( code | tests )

Turn an object into a comma-delineated list of key names, depending if their values are true/false

Params

obj (object)
shouldCapitalize (boolean) capitalizes first word in each key

Returns (string)

Example

{{ commaSeparated {alpha: true, "bravo charlie": true} true }}
//=> "Alpha, Bravo charlie"

getProp ( code | tests )

get property in object
this is similar to handlebars-helpers' get , but the context is called on a returned function.
this allows you to easily convert arrays of objects to arrays of a specific property from each objects

Params

prop (string) key/path, passed to _get()

Returns value of the property from the object

Example

{{ join (map [{ a: "1" }, { a: "2" }] (getProp "a"))}}
//=> "1, 2"

stringify ( code | tests )

stringify JSON
note: doesn't blow up on circular references

Params

obj (object)

Returns (string)

Example

{{{ stringify { a: "b" } }}}
//=> "{"a":"b"}"

strings

capitalize ( code | tests )

capitalize the first character in a string

Params

str (string)

Returns (string)

Example

{{ capitalize "foo bar" }}
//=> "Foo bar"

capitalizeAll ( code | tests )

capitalize every word in a string

Params

str (string)

Returns (string)

Example

{{ capitalizeAll "foo bar" }}
//=> "Foo Bar"

concat ( code | tests )

concatenate any number of strings

Returns (string) concatenated string

Example

{{ concat "Foo" "Bar" "Baz" }}
//=> "FooBarBaz"

includes ( code | tests )

check if a substring exist within a string. This is very similiar to the
indexOf helper, except it uses String.prototype.includes() and returns a
boolean.
note: handlebars returns booleans as strings, so only return a value if the substring is found
otherwise, return undefined (rather than false)

Params

string (string)
substring (string)

Example

{{ includes "hello world" "world" }}
//=> true

kebabCase ( code | no tests )

straight passthrough to _kebabCase

Example

{{ kebabCase "Foo Bar Baz" }}
//=> "foo-bar-baz"

longestWord ( code | tests )

returns the number of characters in the longest word of a string. Punctuation is NOT ignored.

Params

str (string) string to search through

Returns (number) of letters in the longest word

Example

{{ longestWord "Foo Ba b" }}
//=> 3

lowercase ( code | tests )

lower cases a string
note: non-strings will return emptystring

Params

str (string)

Returns (string) lower cased

Example

{{ lowercase "Foo" }}
//=> "foo"

randomString ( code | tests )

generate a random string
note: by default it generates an 8-character string

Params

[prefix] (string) string to append random stuff to
[options] (object)
[options.hash.characters] (number) generate string of a custom length

Returns (string)

Example

{{ randomString "greatest-hit-" characters=3 }}
//=> "greatest-hit-z56"

removeSpaces ( code | tests )

remove spaces, used by in-page id attributes so we can do in-page links
(per the HTML spec IDs cannot have spaces)

Params

str (string)

Returns (string)

Example

{{ removeSpaces "Foo Bar" }}
//=> "FooBar"

replace ( code | tests )

replace all occurrences of a with b
note: this does simple string replacement, not regex

Params

str (string) to replace inside
a (string) to replace
b (string) the replacement

Returns (string)

Example

{{ replace "Foo Bar" "Bar" "Baz" }}
//=> "Foo Baz"

trim ( code | tests )

trim leading and trailing whitespace from a string

Params

str (string)

Returns (string)

Example

{{ trim "   Foo   " }}
//=> "Foo"

truncate ( code | tests )

If a string is over a given length, truncate and append an ellipsis character to the end.

Params

str (string) to shorten
len (number) desired length
options (object)
[options.hash.suffix] (string) to append to truncated string, defaulting to an ellipsis

Returns (string)

Example

{{ truncate "Foo Bar" 4 }}
//=> "Foo…"

time

articleDate ( code | tests )

generate article dates and times, based on a relative format

Params

datetime (Date|string) for date-fns to parse

Returns (string)

Example

{{ articleDate "Fri, 13 Jan 2017 18:22:16 GMT" }}
//=> "Yesterday at 6:22 p.m."

dateMinimal ( code | tests )

generate display date (without time), based on a relative format

Params

datetime (Date|string) for date-fns to parse

Returns (string)

Example

{{ dateMinimal "Fri, 13 Jan 2017 18:22:16 GMT" }}
//=> "Yesterday"

formatLocalDate ( code | tests )

Formats a date with date-fns

Params

date (*)
[format] (string)

Returns (string)

moment ( code | no tests )

No description

urls

urlencode ( code | tests )

encode urls (ported from the nunjucks urlencode filter)
note: handlebars-helpers contains an encodeURI helper, but it doesn't handle arrays or objects.

Params

obj (*) data to encode

Returns (string) urlencoded data

Example

{{ urlencode "&" }}
//=> "%26"

Partials

Currently 1 partial:

component-list ( code | tests )

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

This project is released under the MIT license.