handlebars-helpers

More than 130 Handlebars helpers in ~20 categories that can be used with any Handlebars project.

• Install
• Usage
• Helpers
  • array
  • code
  • comparison
  • data
  • date
  • fs
  • html
  • i18n
  • index
  • inflection
  • logging
  • markdown
  • math
  • misc
  • number
  • object
  • path
  • string
  • url
• Contributing
• Tests
• Authors
• Related projects
• Running tests
• Contributing
• Author
• License

(Table of contents generated by verb)

Install

Install with npm

$ npm i handlebars-helpers --save

Usage

var helpers = require('handlebars-helpers')();
//=> returns object with all (130+) helpers

Get a specific collection

Helper collections are exposed as getters, so only the helpers you want will be required and loaded.

var helpers = require('handlebars-helpers');
var math = helpers.math();
//=> only the `math` helpers

var helpers = require('handlebars-helpers');
var array = helpers.array();
//=> only the `collections` helpers

Optionally pass your own handlebars

var handlebars = require('handlebars');
var helpers = require('handlebars-helpers')({
  handlebars: handlebars
});

// or for a specific collection
var math = helpers.math({
  handlebars: handlebars
});

Helpers

array

.any

Params

• array {Array}
• options {Object}

.after

Returns all of the items in an arry after the specified index. Opposite of {{before}}.

Params

• array {Array}: Collection
• n {Number}: Starting index (number of items to exclude)
• returns {Array}: Array exluding n items.

Example

{{after "['a', 'b', 'c']" 1}}
//=> '["c"]'

.arrayify

Cast val to an array.

Params

• val {*}: The value to arrayify.
• returns {Array}: An array.
• returns {Array}

Example

{{arrayify "abc"}}
//=> '["a"]'

.before

Return all of the items in the collection before the specified count. Opposite of {{after}}.

Params

• array {Array}
• n {Number}
• returns {Array}: Array excluding items after the given number.

Example

{{before "['a', 'b', 'c']" 2}}
//=> '["a", "b"]'

.filter

Params

• array {type}
• value {type}
• options {type}
• returns {String}

.eachIndexPlusOne

Params

• array {Array}
• options {Object}
• returns {String}

Example

{{#eachIndexPlusOne array}}
  {{item}} is {{index}}
{{/eachIndexPlusOne}}

.empty

Params

• array {type}
• options {type}
• returns {String}

.first

Returns the first item, or first n items of an array.

Params

• array {Array}
• n {Number}: Number of items to return, starting at 0.
• returns {Array}

Example

{{first "['a', 'b', 'c', 'd', 'e']" 2}}
//=> '["a", "b"]'

.forEach

// example usage
// {{#forEach accounts}}
//   <a href="mailto:{{ email }}" title="Send an email to {{ name }}">
//     {{ name }}
//   </a>{{#unless isLast}}, {{/unless}}
// {{/forEach}}

.inArray

Params

• array {type}
• value {type}
• options {type}
• returns {String}

.isArray

Returns true if value is an array.

Params

• value {any}: The value to test.
• returns {Boolean}

Example

{{isArray "abc"}}
//=> 'false'

.join

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

Params

• array {Array}
• sep {String}: The separator to use.
• returns {String}

Example

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

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

.last

Returns the last item, or last n items of an array. Opposite of [first][].

Params

• array {Array}
• n {Number}: Number of items to return, starting with the last item.
• returns {Array}

Example

{{last "['a', 'b', 'c', 'd', 'e']" 2}}
//=> '["d", "e"]'

.length

Returns the length of the given array.

Params

• array {Array}
• returns {Number}: The length of the array.

Example

{{length "['a', 'b', 'c']"}}
//=> 3

.lengthEqual

Params

• array {type}
• length {type}
• options {type}
• returns {String}

.map

Returns a new array, created by calling function on each element of the given array.

Assuming that double has been registered as a helper:

Params

• array {Array}
• fn {String}: The function to
• returns {String}

Examples

function double(str) {
  return str + str;
}

{{map "['a', 'b', 'c']" double}}
//=> '["aa", "bb", "cc"]'

.sort

Sort the given array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.

Params

• array {Array}: the array to sort.
• key {String|Function}: The object key to sort by, or sorting function.

Example

{{sort "['b', 'a', 'c']"}}
//=> 'a,b,c'

{{sort "[{a: 'zzz'}, {a: 'aaa'}]" "a"}}
//=> '[{"a":"aaa"},{"a":"zzz"}]'

.sortBy

Sort the given array. If an array of objects is passed, you may optionally pass a key to sort on as the second argument. You may alternatively pass a sorting function as the second argument.

Params

• array {Array}: the array to sort.
• key {String|Function}: The object key to sort by, or sorting function.

Example

{{sortBy '["b", "a", "c"]'}}
//=> 'a,b,c'

{{sortBy '[{a: "zzz"}, {a: "aaa"}]' "a"}}
//=> '[{"a":"aaa"},{"a":"zzz"}]'

.shuffle

Shuffle the items in an array.

Params

• arr {Array}
• returns {Array}

Example

{{shuffle '["a", "b", "c"]'}}
//=> ["c", "a", "b"]

.withFirst

Use the first item in a collection inside a handlebars block expression. Opposite of [withLast][].

Params

• array {Array}
• {Number}: count
• options {Object}
• returns {*}

.withLast

Use the last item in a collection inside a block. Opposite of [withFirst][].

Params

• array {Array}
• {Number}: count
• options {Object}
• returns {*}

.withSort

Params

• array {type}
• field {type}
• options {type}
• returns {String}

.toArray

Converts a string such as "foo, bar, baz" to an ES Array of strings.

Params

• str {String}
• returns {String}

.withAfter

Use all of the items in the collection after the specified count inside a block.

Params

• array {Array}
• count {Number}
• options {Object}
• returns {Array}

.withBefore

Use all of the items in the collection before the specified count inside a block. Opposite of {{withAfter}}

Params

• array {Array}
• {Number}: count
• options {Object}
• returns {Array}

code

.embed

Embed code from an external file as preformatted text.

Params

• fp {String}: filepath to the file to embed.
• language {String}: Optionally specify the language to use for syntax highlighting.
• returns {String}

Example

{{embed 'path/to/file.js'}}

// specify the language to use
{{embed 'path/to/file.hbs' 'html')}}

.jsfiddle

Generate the HTML for a jsFiddle link with the given params

Params

• params {Object}
• returns {String}

Example

{{jsfiddle id="0dfk10ks" tabs="true"}}

comparison

.contains

Checks if a given value is present in a collection using strict equality for comparisons, i.e. ===. If fromIndex is negative, it is used as the offset from the end of the collection.

Params

• collection {Array|Object|string}: The collection to iterate over.
• target {*}: The value to check for.
• [fromIndex=0] {Number}: Optionally define the index to search from.

.any

Returns true if a value exists in the given string, array or object, or if a callback is passed checks to see if a truthy value is returned for any element in a collection or for any sub-string in a string.

Params

• val {*}: The value to check.
• pattern {*}: The pattern to check for.
• options {Object}
• returns {Boolean}

.and

Params

• a {type}
• b {type}
• options {type}
• returns {Boolean}

.gt

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.gte

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.is

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.isnt

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.lt

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.lte

Params

• value {type}
• test {type}
• options {type}
• returns {Boolean}

.if_eq

Params

• context {type}
• options {type}
• returns {Boolean}

.unless_eq

Params

• context {type}
• options {type}
• returns {Boolean}

.if_gt

Params

• context {type}
• options {type}
• returns {Boolean}

.unless_gt

Params

• context {type}
• options {type}
• returns {Boolean}

data

.stringify

JSON.stringify exposed as a helper.

Params

• obj {Object}: Object to stringify
• returns {String}

date

fs

html

.ul

Block helper for creating unordered lists (<ul></ul>)

Params

• context {Object}
• options {Object}
• returns {String}

.ol

Block helper for creating ordered lists (<ol></ol>)

Params

• context {Object}
• options {Object}
• returns {String}

.thumbnailImage

Returns a <figure> with a thumbnail linked to a full picture

Params

• 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.

i18n

index

inflection

.inflect

Params

• count {type}
• singular {type}
• plural {type}
• include {type}
• returns {String}

.ordinalize

Returns an ordinalized number (as a string).

Params

• val {String}: The value to ordinalize.
• returns {String}: The ordinalized number

Example

{{ordinalize 1}}
//=> '1st'
{{ordinalize 21}}
//=> '21st'
{{ordinalize 29}}
//=> '29th'
{{ordinalize 22}}
//=> '22nd'

logging

markdown

math

.add

Return the product of a plus b.

Params

• a {Number}
• b {Number}

.subtract

Return the product of a minus b.

Params

• {Number}: a

.divide

Divide a by b

Params

• a {Number}
• b {Number}: divisor

.multiply

Divide a by b.

Params

• a {Number}
• b {Number}: multiplier

.floor

Get the Math.floor() of the given value.

Params

• value {Number}

.ceil

Get the Math.ceil() of the given value.

Params

• value {Number}

.round

Round the given value.

Params

• value {Number}

.sum

Returns the sum of all numbers in the given array.

Params

• array {Array}: Array of numbers to add up.
• returns {Number}

Example

sum([1, 2, 3, 4, 5])
//=> '15'

.avg

Returns the average of all numbers in the given array.

Params

• array {Array}: Array of numbers to add up.
• returns {Number}

Example

avg([1, 2, 3, 4, 5])
//=> '3'

misc

.default

Params

• value {type}
• defaultValue {type}
• returns {String}

.noop

Params

• options {type}
• returns {String}

number

.phoneNumber

Output a formatted phone number

Params

• num {Number}: The phone number to format, e.g. 8005551212
• returns {Number}: Formatted phone number: (800) 555-1212

.randomize

Uses [randomatic] to generate a randomized string based on the given parameters.

See the [randomatic] docs for the full range of options.

• returns {String}

.toAbbr

Abbreviate numbers to the given number of digits.

Params

• number {String}
• digits {String}
• returns {String}

.toExponential

Params

• number {type}
• fractions {type}
• returns {Number}

.toFixed

Params

• number {type}
• digits {type}
• returns {Number}

object

.forIn

Block helper that iterates over the properties of an object, exposing each key and value on the context.

Params

• 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.

Params

• context {Object}
• options {Object}
• returns {String}

.hasOwn

Return true if key is an own, enumerable property of the given obj.

Params

• key {String}
• obj {Object}: The object to check.
• returns {Boolean}

Example

{{hasOwn obj key}}

.isObject

Return true if value is an object.

Params

• value {String}
• returns {Boolean}

Example

{{isObject "foo"}}
//=> false

.merge

Recursively combine the properties of o with the properties of other objects.

Params

• o {Object}: The target object. Pass an empty object to shallow clone.
• objects {Object}
• returns {Object}

path

.relative

Get the relative path from a to b.

Params

• a {String}
• b {String}
• returns {String}

Example

{{relative a b}}

.extname

Params

• ext {String}
• returns {String}

Example

{{extname "docs/toc.md"}}
//=> '.js'

string

.capitalize

Capitalize first word in a sentence

Params

• str {String}
• returns {String}

.capitalizeFirst

Capitalize the first word in a sentence

Params

• str {String}
• returns {String}

.capitalizeEach

Capitalize each word in a sentence

Params

• str {String}
• returns {String}

.capitalizeAll

Capitalize each word in a sentence

Params

• str {String}
• returns {String}

.center

Center a string using non-breaking spaces

Params

• {String}: str
• {String}: spaces
• returns {String}

.dashify

Replace periods in string with hyphens.

Params

• {String}: str
• returns {String}

.hyphenate

Replace spaces in string with hyphens.

Params

• {String}: str
• returns {String}

.lowercase

Make all letters in the string lowercase

Params

• {String}: str
• returns {String}

.plusify

Replace spaces in string with pluses.

Params

• {String}: str The input string
• returns {String}: Input string with spaces replaced by plus signs

.sentence

Sentence case

Params

• {String}: str
• returns {String}

.titleize

Title case. "This is Title Case"

Params

• {String}: str
• returns {String}

.uppercase

Params

• options {type}
• returns {String}

.reverse

Params

• str {type}
• returns {String}

.count

Return the number of occurrances of a string, within a string

Params

• {String}: str The haystack
• {String}: substring The needle
• returns {Number}: The number of times the needle is found in the haystack.

.replace

Replace occurrences of string "A" with string "B"

Params

• {String}: str
• {String}: a
• {String}: b
• returns {String}

.ellipsis

Truncate the input string and removes all HTML tags

Params

• {String}: str The input string.
• {Number}: limit The number of characters to limit the string.
• {String}: append The string to append if charaters are omitted.
• returns {String}: The truncated string.

.truncate

Truncates a string given a specified length, providing a custom string to denote an omission.

Params

• {String}: str
• {String}: length
• {String}: omission
• returns {String}

url

.stripQuerystring

Params

• url {type}
• returns {String}

Contributing

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

Tests

Install dev dependencies:

$ npm i -d && npm test

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

Related projects

• assemble: Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt,… more | homepage
• template-helpers: Generic JavaScript helpers that can be used with any template engine. Handlebars, Lo-Dash, Underscore, or… more | homepage

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

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

If this project doesn't do what you need, please let us know!

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2014-2015 Jon Schlinkert When this library was initially created a number of the helpers were sourced from Swag, by Elving Rodriguez. Thanks, Elving, for your hard work on Swag. Released under the MIT license.

---

This file was generated by verb-cli on September 24, 2015.