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
Usage
- Use with any template engine
- Namespacing
API
- array
- code
- collection
- conditional
- fs
- html
- index
- math
- object
- path
- string
- Code coverage
About

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

All helpers

_if (code | [no tests])

fs helpers

Visit the: code | unit tests | issues)

exists (code | unit tests)
read (code | unit tests)

html helpers

Visit the: code | unit tests | issues)

escapeHtml (code | unit tests)
sanitize (code | unit tests)

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)

camelcase (code | unit tests)
centerAlign (code | [no tests])
chop (code | unit tests)
count (code | unit tests)
dotcase (code | unit tests)
ellipsis (code | unit tests)
isString (code | [no tests])
lower (code | unit tests)
lowercase (code | unit tests)
pascalcase (code | unit tests)
snakecase (code | unit tests)
split (code | [no tests])
strip (code | unit tests)
stripIndent (code | unit tests)
trim (code | unit tests)
dashcase (code | unit tests)
pathcase (code | unit tests)
sentencecase (code | unit tests)
hyphenate (code | unit tests)
slugify (code | unit tests)
reverse (code | unit tests)
rightAlign (code | [no tests])
replace (code | unit tests)
titleize (code | [no tests])
titlecase (code | unit tests)
truncate (code | unit tests)
upper (code | unit tests)
uppercase (code | unit tests)
wordwrap (code | unit tests)

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

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

timopulkkinen / template-helpers Goto Github PK