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 ❤️ and support.
Install with npm:
$ npm install --save template-helpers
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']);
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'
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.
(The following API Table of Contents is generated by verb. See the verbfile.js for more details.)
Currently 101 helpers in 10 categories:
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
Visit the: code | unit tests | issues)
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'
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"]'
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"]'
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"]'
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"]'
Returns all of the items in an arry after the specified index. Opposite of <%= before() %.
Params
array {Array}: Collectionn {Number}: Starting index (number of items to exclude)returns {Array}: Array exluding n items.Example
<%= after(['a', 'b', 'c'], 1) %> //=> '["c"]'
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"]'
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 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 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"}]'
Returns the length of the given array.
Params
array {Array}returns {Number}: The length of the array.Example
<%= length(['a', 'b', 'c']) %> //=> 3
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"]'
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"]'
Return an array, free of duplicate values.
Params
array {Array}: The array to uniquifyreturns {Array}: Duplicate-free arrayExample
<%= unique(['a', 'b', 'c', 'c']) % => '["a", "b", "c"]'
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 the items in an array.
Params
arr {Array}returns {Array}Example
<%= shuffle(["a", "b", "c"]) %> //=> ["c", "a", "b"]
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') %>
Generate the HTML for a jsFiddle link with the given params
Params
params {Object}returns {String}Example
<%= jsfiddle({id: '0dfk10ks', {tabs: true}}) %>
Returns true if value exists in the given string, array or object. See any for documentation.
Params
value {any}target {any}options {Object}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"]'
Returns true when both valueA and valueB are truthy.
Params
valueA {any}valueB {any}returns {Boolean}Render a block when a comparison of the first and third arguments returns true.
Params
valueA {String}operator {String}: The operator to use for the comparison (must be a quoted string).valueB {String}returns {Boolean}Example
<%= compare("foo", "!==", "bar") %>
Returns the first truthy value.
Params
...values {...args}returns {any}Returns true when all provided values are truthy.
Params
...values {...any}returns {Boolean}Returns true when valueA is greater than valueB.
Params
valueA {String}valueB {String}returns {Boolean}Returns true when valueA is greater than or equal to valueB.
Params
valueA {String}valueB {String}returns {Boolean}Return true if key is an own, enumerable property of the given obj.
Params
object {Object}key {String}returns {Boolean}Returns true when valueA equals valueB.
Params
valueA {String}valueB {String}strict {String}returns {Boolean}Alias for is.
Params
valueA {String}valueB {String}strict {String}returns {Boolean}Returns true when valueA does not equal valueB.
Params
valueA {String}valueB {String}returns {Boolean}Alias for isnt.
Params
valueA {String}valueB {String}returns {Boolean}Returns true when valueA is less than valueB.
Params
valueA {String}valueB {String}returns {Boolean}Returns true when valueA is less than or equal to valueB.
Params
valueA {String}valueB {String}returns {Boolean}Returns valueA if thruthy, otherwise valueB.
Params
valueA {any}valueB {any}returns {any}Returns true when at least one value is truthy.
Params
...values {...any}returns {Boolean}Return true if a file exists
Params
filepath {String}: Path of the file to check.returns {Boolean}: True if the file existsExample
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
Escape HTML characters in a string.
Params
str {String}: String of HTML with characters to escape.returns {String}Example
<%= escapeHtml("<span>foo</span>") %>
//=> <span>foo</span>
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'
Return the product of a plus b.
Params
a {Number}b {Number}Example
<%= add(1, 2) %> //=> '3'
Subtract b from a.
Params
a {Number}b {Number}Example
<%= subtract(5, 2) %> //=> '3'
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 a by b.
Params
a {Number}b {Number}returns {Number}: The product of a times b.Example
<%= divide(10, 2) %> //=> '5'
Returns the largest integer less than or equal to the given number.
Params
number {Number}returns {Number}Example
<%= floor(10.6) %> //=> '10'
Returns the smallest integer greater than or equal to the given number.
Params
number {Number}returns {Number}Example
<%= ceil(10.1) %> //=> '11'
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'
Returns the sum of all numbers in the given array.
Params
number {Number}returns {Number}Example
<%= sum([1, 2, 3, 4, 5]) %> //=> '15'
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") valuereturns {any}: Either a or bExample
// when `title` is undefined, use the generic `site.title` <%= fallback(page.title, site.title) %>
Stringify an object using JSON.stringify().
Params
object {Object}returns {String}Example
<%= stringify({a: "a"}) %>
//=> '{"a":"a"}'
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'
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'
Returns an array of keys from the given object.
Params
object {Object}returns {Array}: Keys from objectExample
<%= keys({a: 'b', c: 'd'}) %>
//=> '["a", "c"]'
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'
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'
Return true if key is an own, enumerable property of the given obj.
Params
object {Object}key {String}returns {Boolean}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"}'
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
object {Object}: Object with keys to omit.keys {String}: Keys to omit.returns {Boolean}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');
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
object {Object}: Object with keys to omit.keys {String}: Keys to omit.returns {Boolean}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 o with properties of other objects.
Params
o {Object}: The target object. Pass an empty object to shallow clone.objects {Object}returns {Object}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}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'
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'
Returns the filename for the given filepath, excluding extension. Aliased as stem.
Params
filepath {String}returns {String}: Returns the file name part of the file path.Example
<%= filename("a/b/c/d.js") %>
//=> 'd'
Alias for filename.
Params
filepath {String}returns {String}: Returns the file name part of the file path.Example
<%= stem("a/b/c/d.js") %>
//=> 'd'
Return the file extension for the given filepath. Uses the node.js path module.
Params
filepath {String}returns {String}: Returns a file extensionExample
<%= extname("foo.js") %>
//=> '.js'
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'
Resolves the given paths to an absolute path. Uses the node.js path module.
Params
filepath {String}returns {String}: Returns a resolveExample
<%= resolve('/foo/bar', './baz') %>
//=> '/foo/bar/baz'
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
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 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'
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 resolveExample
// posix
<%= isAbsolute('/foo/bar') %>
//=> 'true'
<%= isAbsolute('qux/') %>
//=> 'false'
<%= isAbsolute('.') %>
//=> 'false'
// Windows
<%= isAbsolute('//server') %>
//=> 'true'
<%= isAbsolute('C:/foo/..') %>
//=> 'true'
<%= isAbsolute('bar\\baz') %>
//=> 'false'
<%= isAbsolute('.') %>
//=> 'false'
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 resolveExample
// posix
<%= isRelative('/foo/bar') %>
//=> 'false'
<%= isRelative('qux/') %>
//=> 'true'
<%= isRelative('.') %>
//=> 'true'
// Windows
<%= isRelative('//server') %>
//=> 'false'
<%= isRelative('C:/foo/..') %>
//=> 'false'
<%= isRelative('bar\\baz') %>
//=> 'true'
<%= isRelative('.') %>
//=> 'true'
camelCase the characters in string.
Params
string {String}: The string to camelcase.returns {String}Example
<%= camelcase("foo bar baz") %>
//=> 'fooBarBaz'
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") %>
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 the number of occurrances of a substring within a string.
Params
string {String}substring {String}returns {Number}: The occurances of substring in stringExample
<%= count("abcabcabc", "a") %>
//=> '3'
dot.case the characters in string.
Params
string {String}returns {String}Example
<%= dotcase("a-b-c d_e") %>
//=> 'a.b.c.d.e'
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…'
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 the characters in the given string.
Params
string {String}: The string to lowercase.returns {String}Example
<%= lowercase("ABC") %>
//=> 'abc'
PascalCase the characters in string.
Params
string {String}returns {String}Example
<%= pascalcase("foo bar baz") %>
//=> 'FooBarBaz'
snake_case the characters in string.
Params
string {String}returns {String}Example
<%= snakecase("a-b-c d_e") %>
//=> 'a_b_c_d_e'
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 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'
Strip the indentation from a string.
Params
string {String}: The string to strip indentation from.returns {String}Example
<%= stripIndent(" _ABC_") %>
//=> 'ABC'
Trim extraneous whitespace from the beginning and end of a string.
Params
string {String}: The string to trim.returns {String}Example
<%= trim(" ABC ") %>
//=> 'ABC'
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'
path/case the characters in string.
Params
string {String}returns {String}Example
<%= pathcase("a-b-c d_e") %>
//=> 'a/b/c/d/e'
Sentence-case the characters in string.
Params
string {String}returns {String}Example
<%= sentencecase("foo bar baz.") %>
//=> 'Foo bar baz.'
Replace spaces in a string with hyphens. This
Params
string {String}returns {String}Example
<%= hyphenate("a b c") %>
//=> 'a-b-c'
Reverse the characters in a string.
Params
str {String}: The string to reverse.returns {String}Example
<%= reverse("abc") %>
//=> 'cba'
Right align the characters in a string using non-breaking spaces.
Params
str {String}: The string to reverse.returns {String}: Right-aligned string.Example
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 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 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 the characters in a string.
Params
string {String}: The string to uppercase.returns {String}Example
<%= uppercase("abc") %>
//=> 'ABC'
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-wrapreturns {String}: Formatted string.Example
<%= wordwrap("a b c d e f", {width: 5, newline: '<br> '}) %>
//=> ' a b c <br> d e f'
Statements : 94.61% ( 439/464 )
Branches : 88.37% ( 190/215 )
Functions : 96.94% ( 95/98 )
Lines : 94.42% ( 389/412 )
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running TestsRunning 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 testBuilding docs
(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
You might also be interested in the following projects (also visit the github.com/helpers, where you can find 60+ additional standalone helpers!):
Jon Schlinkert
Copyright © 2018, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on November 24, 2018.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4