Generic JavaScript helpers that can be used with any template engine. Handlebars, Lo-Dash, Underscore, or any engine that supports helper functions.
JavaScript
Latest commit fb0fc85 Jul 19, 2016 @jonschlinkert 0.6.7
Permalink
Failed to load latest commit information.
docs adds toc generator Jul 11, 2016
lib proper slugify helper Jul 19, 2016
recipes adds `tips-and-tricks` to recipes Mar 7, 2015
test proper slugify helper Jul 19, 2016
.editorconfig run update Jul 11, 2016
.eslintrc.json run update Apr 25, 2016
.gitattributes first commit Mar 1, 2015
.gitignore start adding coverage/custom tasks Mar 10, 2015
.travis.yml run update Jul 19, 2016
.verb.md add toc message Jul 11, 2016
LICENSE lint Feb 2, 2016
README.md generate docs Jul 19, 2016
gulpfile.js default reporter Feb 2, 2016
index.js lint, adds `titlecase` helper Apr 25, 2016
package.json 0.6.7 Jul 19, 2016
verbfile.js todo Jul 11, 2016

README.md

template-helpers NPM version NPM downloads Build Status

Generic JavaScript helpers that can be used with any template engine. Handlebars, Lo-Dash, Underscore, or any engine that supports helper functions.

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save template-helpers

In addition to the related projects listed below, also take a look at the helpers org, there are 60+ specialized helpers that can be used individually.

Usage

To get all helpers:

var helpers = require('template-helpers')();
console.log(helpers);

Get a specific helper category

// get only the math helpers
var helpers = require('template-helpers')('math');

Get multiple helper categories

// get only the math helpers
var helpers = require('template-helpers')(['math', 'string']);

Use with any template engine

Lo-Dash Example

var helpers = require('template-helpers')('array');

// pass helpers on `imports`
var imports = {imports: helpers};

// compile a template
var fn = _.template('<%= first(foo) %>', imports);

// render
fn({foo: ['a', 'b', 'c']});
//=> 'a'

Namespacing

Handlebars and Lo-Dash both allow dot notation to be used for referencing helpers. I'd be happy to add examples for other engines if someone wants to do a PR.

Example

<%= path.dirname("a/b/c/d.js") %>

This can be used as a way of working around potential naming conflicts.

API

(The following API Table of Contents is generated by verb. See the verbfile.js for more details.)

Categories

Currently 86 helpers in 10 categories:

All helpers

array helpers

Visit the: code | unit tests | issues)

code helpers

Visit the: code | unit tests | issues)

collection helpers

Visit the: code | unit tests | issues)

conditional helpers

Visit the: code | unit tests | issues)

fs helpers

Visit the: code | unit tests | issues)

html helpers

Visit the: code | unit tests | issues)

math helpers

Visit the: code | unit tests | issues)

object helpers

Visit the: code | unit tests | issues)

path helpers

Visit the: code | unit tests | issues)

string helpers

Visit the: code | unit tests | issues)

array

isArray

Returns true if value is an array.

Params

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

Example

<%= isArray('a, b, c') %>
//=> 'false'

<%= isArray(['a, b, c']) %>
//=> 'true'

arrayify

Cast val to an array.

Params

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

Example

<%= arrayify('a') %>
//=> '["a"]'

<%= arrayify({a: 'b'}) %>
//=> '[{a: "b"}]'

<%= arrayify(['a']) %>
//=> '["a"]'

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"]'

last

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

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"]'

before

Returns all of the items in an array up to the specified number 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"]'

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"]'

each

Calling fn on each element of the given array with the given context.

Assuming that double has been registered as a helper:

Params

  • array {Array}
  • fn {String}: The function to call on each element in the given array.
  • returns {String}

Examples

function double(str) {
  return str + str;
}
<%= each(['a', 'b', 'c'], double, ctx) %>
//=> '["aa", "bb", "cc"]'

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 call on each element in the given array.
  • returns {String}

Examples

function double(str) {
  return str + str;
}
<%= map(['a', 'b', 'c'], double) %>
//=> '["aa", "bb", "cc"]'

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'

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"}]'

length

Returns the length of the given array.

Params

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

Example

<%= length(['a', 'b', 'c']) %>
//=> 3

compact

Returns an array with all falsey values removed.

Params

  • arr {Array}
  • returns {Array}

Example

<%= compact([null, a, undefined, 0, false, b, c, '']) %>
//=> '["a", "b", "c"]'

difference

Return the difference between the first array and additional arrays.

Params

  • array {Array}: The array to compare againts.
  • arrays {Array}: One or more additional arrays.
  • returns {Array}

Example

<%= difference(["a", "c"], ["a", "b"]) %>
//=> '["c"]'

unique

Return an array, free of duplicate values.

Params

  • array {Array}: The array to uniquify
  • returns {Array}: Duplicate-free array

Example

<%= unique(['a', 'b', 'c', 'c']) %
=> '["a", "b", "c"]'

union

Returns an array of unique values using strict equality for comparisons.

Params

  • arr {Array}
  • returns {Array}

Example

<%= union(["a"], ["b"], ["c"]) %>
//=> '["a", "b", "c"]'

shuffle

Shuffle the items in an array.

Params

  • arr {Array}
  • returns {Array}

Example

<%= shuffle(["a", "b", "c"]) %>
//=> ["c", "a", "b"]

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}}) %>

collection

any

Returns true if value exists in the given string, array or object. See any for documentation.

Params

  • value {any}
  • target {any}
  • options {Object}

filter

Filter the given array or object to contain only the matching values.

Params

  • arr {Array}
  • returns {Array}

Example

<%= filter(['foo', 'bar', 'baz']) %>
//=> '["a", "b", "c"]'

conditional

_if

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

Params

  • object {Object}
  • key {String}
  • returns {Boolean}

fs

exists

Return true if a file exists

Params

  • filepath {String}: Path of the file to check.
  • returns {Boolean}: True if the file exists

Example

<%= exists("foo.js") %>

read

Read a file from the file system and inject its content

Params

  • filepath {String}: Path of the file to read.
  • returns {String}: Contents of the given file.

Example

<%= read("foo.js") %>

html

escapeHtml

Escape HTML characters in a string.

Params

  • str {String}: String of HTML with characters to escape.
  • returns {String}

Example

<%= escapeHtml("<span>foo</span>") %>
//=> &lt;span&gt;foo&lt;&#x2F;span&gt;

sanitize

Strip HTML tags from a string, so that only the text nodes are preserved.

Params

  • str {String}: The string of HTML to sanitize.
  • returns {String}

Example

<%= sanitize("<span>foo</span>") %>
//=> 'foo'

math

add

Return the product of a plus b.

Params

  • a {Number}
  • b {Number}

Example

<%= add(1, 2) %>
//=> '3'

subtract

Subtract b from a.

Params

  • a {Number}
  • b {Number}

Example

<%= subtract(5, 2) %>
//=> '3'

divide

Divide a (the numerator) by b (the divisor).

Params

  • a {Number}: the numerator.
  • b {Number}: the divisor.
  • returns {Number}: The quotient of a divided by b.

Example

<%= divide(10, 2) %>
//=> '5'

multiply

Multiply a by b.

Params

  • a {Number}
  • b {Number}
  • returns {Number}: The product of a times b.

Example

<%= divide(10, 2) %>
//=> '5'

floor

Returns the largest integer less than or equal to the given number.

Params

  • number {Number}
  • returns {Number}

Example

<%= floor(10.6) %>
//=> '10'

ceil

Returns the smallest integer greater than or equal to the given number.

Params

  • number {Number}
  • returns {Number}

Example

<%= ceil(10.1) %>
//=> '11'

round

Returns the value of the given number rounded to the nearest integer.

Params

  • number {Number}
  • returns {Number}

Example

<%= round(10.1) %>
//=> '10'

<%= round(10.5) %>
//=> '11'

sum

Returns the sum of all numbers in the given array.

Params

  • number {Number}
  • returns {Number}

Example

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

object

fallback

Specify a fallback value to use when the desired value is undefined. Note that undefined variables that are not object properties with throw an error.

Params

  • a {any}: The desired value.
  • b {any}: The fallback ("default") value
  • returns {any}: Either a or b

Example

// when `title` is undefined, use the generic `site.title`
<%= fallback(page.title, site.title) %>

stringify

Stringify an object using JSON.stringify().

Params

  • object {Object}
  • returns {String}

Example

<%= stringify({a: "a"}) %>
//=> '{"a":"a"}'

parse

Parse a string into an object using JSON.parse().

Params

  • str {String}: The string to parse.
  • returns {Object}: The parsed object.

Example

<%= parse('{"foo":"bar"}')["foo"] %>
//=> 'bar'

get

Use property paths (a.b.c) get a nested value from an object.

Params

  • object {Object}
  • path {String}: Dot notation for the property to get.
  • returns {String}

Example

<%= get({a: {b: 'c'}}, 'a.b') %>
//=> 'c'

keys

Returns an array of keys from the given object.

Params

  • object {Object}
  • returns {Array}: Keys from object

Example

<%= keys({a: 'b', c: 'd'}) %>
//=> '["a", "c"]'

isObject

Return true if the given value is an object, and not null or an array.

Params

  • value {Object}: The value to check.
  • returns {Boolean}

Example

<%= isObject(['a', 'b', 'c']) %>
//=> 'false'

<%= isObject({a: 'b'}) %>
//=> 'true'

isPlainObject

Return true if the given value is a plain object.

Params

  • value {Object}: The value to check.
  • returns {Boolean}

Example

<%= isPlainObject(['a', 'b', 'c']) %>
//=> 'false'

<%= isPlainObject({a: 'b'}) %>
//=> 'true'

<%= isPlainObject(/foo/g) %>
//=> 'false'

hasOwn

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

Params

  • object {Object}
  • key {String}
  • returns {Boolean}

omit

Return a copy of object exclusing the given keys.

Params

  • object {Object}: Object with keys to omit.
  • keys {String}: Keys to omit.
  • returns {Boolean}

Example

<%= omit({a: 'a', b: 'b', c: 'c'}, ['a', 'c']) %>
//=> '{b: "b"}'

forIn

Return a copy of object exclusing the given keys.

Params

  • object {Object}: Object with keys to omit.
  • keys {String}: Keys to omit.
  • returns {Boolean}

Example

<%= omit({a: 'a', b: 'b', c: 'c'}, ['a', 'c']) %>
//=> '{b: "b"}'

forOwn

Return a copy of object exclusing the given keys.

Params

  • object {Object}: Object with keys to omit.
  • keys {String}: Keys to omit.
  • returns {Boolean}

Example

<%= omit({a: 'a', b: 'b', c: 'c'}, ['a', 'c']) %>
//=> '{b: "b"}'

extend

Extend o with properties of other objects.

Params

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

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

dirname

Return the dirname for the given filepath. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns the directory part of the file path.

Example

<%= dirname("a/b/c/d") %>
//=> 'a/b/c'

basename

Return the basename for the given filepath. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns the basename part of the file path.

Example

<%= basename("a/b/c/d.js") %>
//=> 'd.js'

filename

Return the filename for the given filepath, excluding extension.

Params

  • filepath {String}
  • returns {String}: Returns the file name part of the file path.

Example

<%= basename("a/b/c/d.js") %>
//=> 'd'

extname

Return the file extension for the given filepath. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns a file extension

Example

<%= extname("foo.js") %>
//=> '.js'

ext

Return the file extension for the given filepath, excluding the ..

Params

  • filepath {String}
  • returns {String}: Returns a file extension without dot.

Example

<%= ext("foo.js") %>
//=> 'js'

resolve

Resolves the given paths to an absolute path. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns a resolve

Example

<%= resolve('/foo/bar', './baz') %>
//=> '/foo/bar/baz'

relative

Get the relative path from file a to file b. Typically a and b would be variables passed on the context. Uses the node.js path module.

Params

  • a {String}: The "from" file path.
  • b {String}: The "to" file path.
  • returns {String}: Returns a relative path.

Example

<%= relative(a, b) %>

segments

Get specific (joined) segments of a file path by passing a range of array indices.

Params

  • filepath {String}: The file path to split into segments.
  • returns {String}: Returns a single, joined file path.

Example

<%= segments("a/b/c/d", "2", "3") %>
//=> 'c/d'

<%= segments("a/b/c/d", "1", "3") %>
//=> 'b/c/d'

<%= segments("a/b/c/d", "1", "2") %>
//=> 'b/c'

join

Join all arguments together and normalize the resulting filepath. Uses the node.js path module.

Note: there is also a join() array helper, dot notation can be used with helpers to differentiate. Example: <%= path.join() %>.

Params

  • filepaths {String}: List of file paths.
  • returns {String}: Returns a single, joined file path.

Example

<%= join("a", "b") %>
//=> 'a/b'

isAbsolute

Returns true if a file path is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns a resolve

Example

// posix
<%= isAbsolute('/foo/bar') %>
//=> 'true'
<%= isAbsolute('qux/') %>
//=> 'false'
<%= isAbsolute('.') %>
//=> 'false'

// Windows
<%= isAbsolute('//server') %>
//=> 'true'
<%= isAbsolute('C:/foo/..') %>
//=> 'true'
<%= isAbsolute('bar\\baz') %>
//=> 'false'
<%= isAbsolute('.') %>
//=> 'false'

isRelative

Returns true if a file path is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory. Uses the node.js path module.

Params

  • filepath {String}
  • returns {String}: Returns a resolve

Example

// posix
<%= isRelative('/foo/bar') %>
//=> 'false'
<%= isRelative('qux/') %>
//=> 'true'
<%= isRelative('.') %>
//=> 'true'

// Windows
<%= isRelative('//server') %>
//=> 'false'
<%= isRelative('C:/foo/..') %>
//=> 'false'
<%= isRelative('bar\\baz') %>
//=> 'true'
<%= isRelative('.') %>
//=> 'true'

string

camelcase

camelCase the characters in string.

Params

  • string {String}: The string to camelcase.
  • returns {String}

Example

<%= camelcase("foo bar baz") %>
//=> 'fooBarBaz'

centerAlign

Center align the characters in a string using non-breaking spaces.

Params

  • str {String}: The string to reverse.
  • returns {String}: Centered string.

Example

<%= centerAlign("abc") %>

chop

Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string.

Params

  • string {String}: The string to chop.
  • returns {String}

Example

<%= chop("_ABC_") %>
//=> 'ABC'

<%= chop("-ABC-") %>
//=> 'ABC'

<%= chop(" ABC ") %>
//=> 'ABC'

count

Count the number of occurrances of a substring within a string.

Params

  • string {String}
  • substring {String}
  • returns {Number}: The occurances of substring in string

Example

<%= count("abcabcabc", "a") %>
//=> '3'

dotcase

dot.case the characters in string.

Params

  • string {String}
  • returns {String}

Example

<%= dotcase("a-b-c d_e") %>
//=> 'a.b.c.d.e'

ellipsis

Truncate a string to the specified length, and append it with an elipsis, .

Params

  • str {String}
  • length {Number}: The desired length of the returned string.
  • ch {String}: Optionally pass custom characters to append. Default is .
  • returns {String}: The truncated string.

Example

<%= ellipsis("<span>foo bar baz</span>", 7) %>
//=> 'foo bar…'

isString

Returns true if the value is a string.

Params

  • val {String}
  • returns {Boolean}: True if the value is a string.

Example

<%= isString('abc') %>
//=> 'true'

<%= isString(null) %>
//=> 'false'

lowercase

Lowercase the characters in the given string.

Params

  • string {String}: The string to lowercase.
  • returns {String}

Example

<%= lowercase("ABC") %>
//=> 'abc'

pascalcase

PascalCase the characters in string.

Params

  • string {String}
  • returns {String}

Example

<%= pascalcase("foo bar baz") %>
//=> 'FooBarBaz'

snakecase

snake_case the characters in string.

Params

  • string {String}
  • returns {String}

Example

<%= snakecase("a-b-c d_e") %>
//=> 'a_b_c_d_e'

split

Split string by the given character.

Params

  • string {String}: The string to split.
  • returns {String} character: Default is ,

Example

<%= split("a,b,c", ",") %>
//=> ['a', 'b', 'c']

strip

Strip substring from the given string.

Params

  • substring {String|RegExp}: The string or regex pattern of the substring to remove.
  • string {String}: The target string.

Example

<%= strip("foo-bar", "foo-") %>
//=> 'bar'

stripIndent

Strip the indentation from a string.

Params

  • string {String}: The string to strip indentation from.
  • returns {String}

Example

<%= stripIndent("  _ABC_") %>
//=> 'ABC'

trim

Trim extraneous whitespace from the beginning and end of a string.

Params

  • string {String}: The string to trim.
  • returns {String}

Example

<%= trim("  ABC   ") %>
//=> 'ABC'

dashcase

dash-case the characters in string. This is similar to slugify, but slugify makes the string compatible to be used as a URL slug.

Params

  • string {String}
  • returns {String}

Example

<%= dashcase("a b.c d_e") %>
//=> 'a-b-c-d-e'

pathcase

path/case the characters in string.

Params

  • string {String}
  • returns {String}

Example

<%= pathcase("a-b-c d_e") %>
//=> 'a/b/c/d/e'

sentencecase

Sentence-case the characters in string.

Params

  • string {String}
  • returns {String}

Example

<%= sentencecase("foo bar baz.") %>
//=> 'Foo bar baz.'

hyphenate

Replace spaces in a string with hyphens. This

Params

  • string {String}
  • returns {String}

Example

<%= hyphenate("a b c") %>
//=> 'a-b-c'

reverse

Reverse the characters in a string.

Params

  • str {String}: The string to reverse.
  • returns {String}

Example

<%= reverse("abc") %>
//=> 'cba'

rightAlign

Right align the characters in a string using non-breaking spaces.

Params

  • str {String}: The string to reverse.
  • returns {String}: Right-aligned string.

Example

<%= rightAlign(str) %>

replace

Replace occurrences of a with b.

Params

  • str {String}
  • a {String|RegExp}: Can be a string or regexp.
  • b {String}
  • returns {String}

Example

<%= replace("abcabc", /a/, "z") %>
//=> 'zbczbc'

titlecase

Truncate a string by removing all HTML tags and limiting the result to the specified length.

Params

  • str {String}
  • length {Number}: The desired length of the returned string.
  • returns {String}: The truncated string.

Example

<%= titlecase("big deal") %>
//=> 'foo bar'

truncate

Truncate a string by removing all HTML tags and limiting the result to the specified length.

Params

  • str {String}
  • length {Number}: The desired length of the returned string.
  • returns {String}: The truncated string.

Example

<%= truncate("<span>foo bar baz</span>", 7) %>
//=> 'foo bar'

uppercase

Uppercase the characters in a string.

Params

  • string {String}: The string to uppercase.
  • returns {String}

Example

<%= uppercase("abc") %>
//=> 'ABC'

wordwrap

Wrap words to a specified width using word-wrap.

Params

  • string {String}: The string with words to wrap.
  • object {Options}: Options to pass to word-wrap
  • returns {String}: Formatted string.

Example

<%= wordwrap("a b c d e f", {width: 5, newline: '<br>  '}) %>
//=> '  a b c <br>  d e f'

Code coverage

Statements   : 94.61% ( 439/464 )
Branches     : 88.37% ( 190/215 )
Functions    : 96.94% ( 95/98 )
Lines        : 94.42% ( 389/412 )

About

Related projects

  • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
  • handlebars-helpers: More than 130 Handlebars helpers in ~20 categories. Helpers can be used with Assemble, Generate… more | homepage
  • helper-cache: Easily register and get helper functions to be passed to any template engine or node.js… more | homepage
  • template: Render templates using any engine. Supports, layouts, pages, partials and custom template types. Use template… more | homepage
  • utils: Fast, generic JavaScript/node.js utility functions. | homepage
  • verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

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

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.


This file was generated by verb, v0.9.0, on July 19, 2016.