template-helpers

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

Install with npm

npm i template-helpers --save

Usage

To get all helpers grouped by collection:

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

// All helpers are on the `_` property
console.log(helpers._);

Get a specific collection

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

// get only the math helpers
var math = helpers.math;

Use with any template engine

Lo-Dash Example

var context = {arr: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']};

// pass helpers on `imports`
var imports = {imports: helpers.arrays};
var template = _.template('<%= first(foo) %>', imports);

// pass context
template({foo: ['a', 'b', 'c']});
//=> 'a'

Namespacing

Handlebars and Lo-Dash both allow dot notation to be used for referencing helpers. Other engines may allow this too, I'd be happy to add this information to readme 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.

Code coverage

Statements   : 97.58% ( 363/372 )
Branches     : 96.92% ( 189/195 )
Functions    : 98.78% ( 81/82 )
Lines        : 97.2% ( 312/321 )

Docs

.isArray

Returns true if value is an array.

Params

value {*}: 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 {*}: 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"]'

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

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

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

.any

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

Params

value {*}
target {*}
options {Object}

._if

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

Params

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

.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") %>

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

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

.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 {*}: The desired value.
b {*}: The fallback ("default") value
returns {*}: 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"}'

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

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

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

.uppercase

Uppercase the characters in a string.

Params

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

Example

<%= uppercase("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'

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

.stripIndent

Strip the indentation from a string.

Params

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

Example

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

.camelcase

camelCase the characters in string.

Params

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

Example

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

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

.dotcase

dot.case the characters in string.

Params

string {String}
returns {String}

Example

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

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

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

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

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

.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") %>

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

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

.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…'

Related projects

handlebars-helpers: 120+ Handlebars helpers in ~20 categories, for Assemble, YUI, Ghost… more
utils: Fast, generic JavaScript/node.js utility functions.

Also take a look at the helpers org, there are dozens of specialized helpers that can be downloaded individually.

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

Author

Jon Schlinkert

License

This file was generated by verb-cli on April 25, 2015.

Template-helpers

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

template-helpers

Install with npm

TOC

Usage

Use with any template engine

Namespacing

Code coverage

Docs

Related projects

Running tests

Contributing

Author

License