Home

Awesome

template-helpers NPM version NPM monthly downloads NPM total downloads Linux Build Status

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

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

$ npm install --save template-helpers

Usage

To get all helpers:

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

Get a specific helper category

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

Get multiple helper categories

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

Template-engine agnostic

Lo-Dash Example

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

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

// compile a template
const 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.

Helpers

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

Categories

Currently 101 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

Example

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

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

arrayify

Cast val to an array.

Params

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

Example

<%= first(['a', 'b', 'c', 'd', 'e'], 2) %>
//=> '["a", "b"]'

last

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

Params

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

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

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

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

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

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

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

Example

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

compact

Returns an array with all falsey values removed.

Params

Example

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

difference

Return the difference between the first array and additional arrays.

Params

Example

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

unique

Return an array, free of duplicate values.

Params

Example

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

union

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

Params

Example

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

shuffle

Shuffle the items in an array.

Params

Example

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

code

embed

Embed code from an external file as preformatted text.

Params

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

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

filter

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

Params

Example

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

conditional

and

Returns true when both valueA and valueB are truthy.

Params

compare

Render a block when a comparison of the first and third arguments returns true.

Params

Example

<%= compare("foo", "!==", "bar") %>

find

Returns the first truthy value.

Params

every

Returns true when all provided values are truthy.

Params

gt

Returns true when valueA is greater than valueB.

Params

gte

Returns true when valueA is greater than or equal to valueB.

Params

_if

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

Params

is

Returns true when valueA equals valueB.

Params

eq

Alias for is.

Params

isnt

Returns true when valueA does not equal valueB.

Params

notEq

Alias for isnt.

Params

lt

Returns true when valueA is less than valueB.

Params

lte

Returns true when valueA is less than or equal to valueB.

Params

or

Returns valueA if thruthy, otherwise valueB.

Params

some

Returns true when at least one value is truthy.

Params

fs

exists

Return true if a file exists

Params

Example

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

read

Read a file from the file system and inject its content

Params

Example

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

html

escapeHtml

Escape HTML characters in a string.

Params

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

Example

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

math

add

Return the product of a plus b.

Params

Example

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

subtract

Subtract b from a.

Params

Example

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

divide

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

Params

Example

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

multiply

Multiply a by b.

Params

Example

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

floor

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

Params

Example

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

ceil

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

Params

Example

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

round

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

Params

Example

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

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

sum

Returns the sum of all numbers in the given array.

Params

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

Example

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

stringify

Stringify an object using JSON.stringify().

Params

Example

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

parse

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

Params

Example

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

get

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

Params

Example

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

keys

Returns an array of keys from the given object.

Params

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

Example

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

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

isPlainObject

Return true if the given value is a plain object.

Params

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

omit

Return a copy of object exclusing the given keys.

Params

Example

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

forIn

Iterate over the own and inherited enumerable properties of an object, and return an object with properties that evaluate to true from the callback. Exit early by returning false.

Params

Example

const context = { values: { a: 'b', c: 'd' } };
const str = '<% forIn(values, function(val, key) { %><%= val %><% }) %>';
const fn = _.template(str, { imports: helpers });
assert.equal(fn(context), 'bd');

forOwn

Iterate over the own enumerable properties of an object, and return an object with properties that evaluate to true from the callback. Exit early by returning false

Params

Example

const context = { values: { a: 'b', c: 'd' } };
const str = '<% forOwn(values, function(val, key) { %><%= key %><% }) %>';
const fn = _.template(str, { imports: helpers });
console.log(fn(context)) //=> 'ac'

extend

Extend o with properties of other objects.

Params

merge

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

Params

path

dirname

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

Params

Example

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

basename

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

Params

Example

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

filename

Returns the filename for the given filepath, excluding extension. Aliased as stem.

Params

Example

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

stem

Alias for filename.

Params

Example

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

extname

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

Params

Example

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

ext

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

Params

Example

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

resolve

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

Params

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

Example

<%= relative(a, b) %>

segments

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

Params

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

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

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

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

Example

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

centerAlign

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

Params

Example

<%= centerAlign("abc") %>

chop

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

Params

Example

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

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

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

count

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

Params

Example

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

dotcase

dot.case the characters in string.

Params

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

Example

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

isString

Returns true if the value is a string.

Params

Example

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

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

lowercase

Lowercase the characters in the given string.

Params

Example

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

pascalcase

PascalCase the characters in string.

Params

Example

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

snakecase

snake_case the characters in string.

Params

Example

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

split

Split string by the given character.

Params

Example

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

strip

Strip substring from the given string.

Params

Example

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

stripIndent

Strip the indentation from a string.

Params

Example

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

trim

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

Params

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

Example

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

pathcase

path/case the characters in string.

Params

Example

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

sentencecase

Sentence-case the characters in string.

Params

Example

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

hyphenate

Replace spaces in a string with hyphens. This

Params

Example

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

reverse

Reverse the characters in a string.

Params

Example

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

rightAlign

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

Params

Example

<%= rightAlign(str) %>

replace

Replace occurrences of a with b.

Params

Example

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

titlecase

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

Params

Example

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

truncate

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

Params

Example

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

uppercase

Uppercase the characters in a string.

Params

Example

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

wordwrap

Wrap words to a specified width using word-wrap.

Params

Example

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

Coverage

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

About

<details> <summary><strong>Contributing</strong></summary>

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

</details> <details> <summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test
</details> <details> <summary><strong>Building docs</strong></summary>

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb
</details>

Related projects

You might also be interested in the following projects (also visit the github.com/helpers, where you can find 60+ additional standalone helpers!):

Contributors

Author

Jon Schlinkert

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.


This file was generated by verb-generate-readme, v0.8.0, on November 24, 2018.