A package with common Handlebars helpers.
npm install just-handlebars-helpers --save
yarn add just-handlebars-helpers
<!-- Load handlebars -->
<script src="/path/to/handlebars/dist/handlebars.min.js"></script>
<!-- Load just-handlebars-helpers -->
<script src="/path/to/just-handlebars-helpers/dist/h.min.js"></script>
<script type="text/javascript">
// Register just-handlebars-helpers with handlebars
H.registerHelpers(Handlebars);
</script>
<!-- Load handlebars -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.1.2/handlebars.min.js"></script>
<!-- Load just-handlebar-helpers -->
<script src="https://unpkg.com/just-handlebars-helpers@1.0.19/dist/h.min.js"></script>
<script type="text/javascript">
// Register just-handlebars-helpers with handlebars
H.registerHelpers(Handlebars);
</script>
// Require handlebars and just-handlebars-helpers
const Handlebars = require("handlebars");
const H = require("just-handlebars-helpers");
// Register just-handlebars-helpers with handlebars
H.registerHelpers(Handlebars);
Helper | Description |
---|---|
eq | Strict equality === |
eqw | Equality == |
neq | Strict inequality !== |
neqw | Inequality != |
lt | Less than < |
lte | Less than or equal <= |
gt | Greater than > |
gte | Greater than or equal >= |
not | Not ! |
ifx | Imitates conditional operator ?: |
empty | Check if an array is empty |
count | Length of an array |
and | Logical AND operation |
or | Logical OR operation |
coalesce | Returns first non-falsy value from list of parameters |
includes | Check for a value inside an array |
excerpt | Extract a sub-string from a string |
sanitize | Sanitize a string to url friendly dash/kebab case |
newLineToBr | Replace new line with line breaks <br> of a string |
capitalizeEach | Capitalize the first letter of each word in a string |
capitalizeFirst | Capitalize the first letter of a string |
sprintf | String produced according to the formatting format |
lowercase | String to lowercase |
uppercase | String to uppercase |
first | First element of an array |
last | Last element of an array |
concat | Concatenate two or more strings |
join | Join elements of an array using a delimeter |
sum | Sum of two numbers |
difference | Difference of two numbers |
multiplication | Multiplication of two numbers |
division | Division of two numbers |
remainder | Remainder of two numbers |
ceil | Round a number upward to its nearest integer |
floor | Round a number downward to its nearest integer |
abs | Find the absolute value of a number |
formatDate | Format date to specified format |
showIf | Show HTML element if expression is true |
hideIf | Hide HTML element if expression is true |
selectedIf | Select <option> if expression is true |
checkedIf | Check the <input> checkbox if expression is true |
options | Generate <option> list for <select> |
formatCurrency | Format currency value according to country |
Helpers formatDate, formatCurrency and sprintf depend on an external dependency and it is up to the user to install these dependencies. Check the helper documentation for what dependencies to install.
Determine whether or not two values are equal (===).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{eq '3' 3}} => false
{{#if (eq foo 'bar')}}
Hello
{{/if}}
Determine whether or not two values are equal (==) i.e. weak checking.
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{eqw '3' 3}} => true
{{#if (eqw foo 'bar')}}
Hello
{{/if}}
Determine whether or not two values are not equal (!==).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{neq 4 3}} => true
{{#if (neq foo 'bar')}}
Hello
{{/if}}
Determine whether or not two values are not equal (!=) weak checking.
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{neqw '3' 3}} => false
{{#if (neqw foo 'bar')}}
Hello
{{/if}}
Check for less than condition (a < b).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{lt 2 3}} => true
{{#if (lt 2 5)}}
Hello
{{/if}}
Check for less than or equals condition (a <= b).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{lte 2 3}} => true
{{#if (lte 5 6)}}
Hello
{{/if}}
Check for greater than condition (a > b).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{gt 2 3}} => false
{{#if (gt 10 7)}}
Hello
{{/if}}
Check for greater than or equals condition (a >= b).
Parameters:
value1 [any] First value to be compared with second. (Required)
value2 [any] Second value to be compared with first. (Required)
Returns boolean
Usage:
{{gte 3 3}} => true
{{#if (gte 10 2)}}
Hello
{{/if}}
Logical NOT of any expression. Equivalent to !
operator.
Parameters:
expression [any] Any expression.
Returns boolean
Usage:
{{not true}} => false
{{not false}} => true
{{#if (not (eq foo 'bar'))}}
Hello
{{/if}}
Helper to imitate the ternary conditional operator ?:. E.g. 5 > 7 ? 'foo' : 'bar'
.
Parameters:
condition [boolean] Satisfying condition for getting first value. Either true of false. (Required)
value1 [any] First value to be displayed as result. (Required)
value2 [any] Second value to be displayed as result. Defaults to an empty string (Optional)
Returns any
Usage:
{{ifx true 'Foo' 'Bar'}} => Foo // return (true) ? 'Foo' : 'Bar'
{{ifx false 'Foo' 'Bar'}} => Foo // return (false) ? 'Foo' : 'Bar'
{{ifx (eq value 1) 5 6}} => 6 // return (value === 1) ? 5 : 6
{{ifx (not (eq value 1)) 5 6}} => 6 // return (value !== 1) ? 5 : 6
<!-- The third parameter is optional, and by default it will be blank string ('') -->
{{ifx true 'active'}} => 'active'
{{ifx false 'active'}} => ''
Check if an array is empty.
Parameters:
array [array] Array/object to be checked. (Required)
Returns boolean
Usage:
var array = [5, 6]; // An array.
{{empty array}} => false
{{#if (empty array)}}
Hello
{{/if}}
Determine the length of an array. Equivalent to array.length
operator in JavaScript.
Parameters:
array [array] Array whose elements to be counted. (Required)
Returns number|false
Usage:
var array = [5, 6]; // An array.
{{count array}} => 2;
Returns the logical AND of two or more parameters passed i.e it is true iff all the parameters are true.
Parameters:
params [any] Any number of boolean parameters. (Required)
Returns boolean
Usage:
var value1 = value2 = true;
{{and value1 value2}} => true
var value1 = false, value2 = true;
{{and value1 value2}} => false
{{#if (and value1 value2)}}
// do something
{{else}}
// do something else
{{/if}}
Returns the logical OR of two or more parameters passed i.e it is true if any of the parameters is true.
Parameters:
params [any] Any number of boolean parameters. (Required)
Returns boolean
Usage:
var value1 = true, value2 = false;
{{or value1 value2}} => true
var value = value2 = false;
{{or value1 value2}} => false
{{#if (or value1 value2)}}
// do something
{{else}}
// do something else
{{/if}}
Returns the first non-falsy value from the parameter list. Works quite similar to the SQL's COALESCE() function, but unlike this checks for the first non-false parameter.
Parameters:
params [any] Any number of parameters. (Required)
Returns any
Usage:
var fullName = 'Foo Bar', nickName = 'foob';
{{coalesce fullName nickName 'Unknown'}} => 'Foo Bar'
var fullName = '', nickName = 'foob';
{{coalesce fullName nickName 'Unknown'}} => 'foob'
Returns true if an array includes a value. It checks for the existence of the value in array strictly(value + data type) by default. Can check non-strictly(value only) by sending third argument as false.
Parameters:
params [array] The array. (Required)
params [any] The value to be checked for existence in the array. (Required)
params [boolean] FALSE for non-strict checking. TRUE by default. (Optional)
Returns boolean
Usage:
var array = [1, 2, 3];
var value = 2;
{{includes array value}} => true
var value = '2'
{{includes array value}} => false
{{includes array value true}} => false
{{includes array value false}} => true
{{#if (includes array value)}}
<!-- Do something -->
{{/if}}
{{ifx (includes array value) 'Yes' 'No'}}
Extract a sub-string from a string.
Parameters:
string [string] The string from which characters are to be extracted. (Required)
length [int] Number of characters to be extracted from string. Default value is 50. (Optional)
Returns string
Usage:
{{excerpt 'Just Wow' 4}} => 'Just...'
Converts a string to URL friendly dash-case string removing special characters.
Parameters
string [string] The string to be converted to URL. (Required)
Returns string
Usage:
{{sanitize 'JuSt #Wow'}} => 'just-wow'
Replace \n
with <br>
tags.
Parameters:
string [string] The string that needs replacement of \n by <br> tags. (Required)
Returns string
Usage:
{{{newLineToBr 'newLineToBr helper \n is very \n useful.'}}} => newLineToBr helper <br> is very <br> useful.
Capitalize the first letter of each word in a string.
Parameters
string [string] The sentence/string to be capitalized. (Required)
Returns string
Usage:
{{capitalizeEach 'just wow'}} => 'Just Wow'
Capitalize the first letter of a string.
Parameters:
string [string] The sentence/string to be capitalized. (Required)
Returns string
Usage:
{{capitalizeFirst 'just wow'}} => 'Just wow'
sprintf
helper sends formatted data as string output.
Note: To use sprintf
helper install sprintf-js.
npm install sprintf-js --save
Parameters:
format [string] The message/string that uses different formats of variables. (Required)
args [arbitrary arguments] Any number of parameters/values. (Required)
Returns string
Usage:
{{sprintf '%s %s!' 'Hello' 'Kabir' }}
{{sprintf '%s %s %d %s %d' 'Foo' 'Bar' 55 'Baz' '20'}}
{{sprintf '%(greeting)s %(name)s! How are you?' obj }}
{{sprintf '%(greeting)s %(name)s! ' greeting='Hello' name='Kabir'}}
Changes the string to lowercase.
Parameters:
param [string] The string to be converted to lower case. (Required)
Returns string
Usage:
{{lowercase 'JUST WOW!!!'}} => 'just wow!!!'
Changes the string to uppercase.
Parameters:
param [string] The string to be converted to upper case. (Required)
Returns string
Usage:
{{uppercase 'just wow!!!'}} => 'JUST WOW!!!'
Get the first element of a collection/array.
Parameters:
collection [array] The collection/array of objects(strings, integers). (Required)
Returns string
Usage:
someArray = ['David', 'Miller', 'Jones'];
{{first someArray}} => 'David'
Get the last element of a collection/array.
Parameters:
collection [array] The collection/array of objects(strings, integers). (Required)
Returns string
Usage:
someArray = ['David', 'Miller', 'Jones'];
{{last someArray}} => 'Jones'
Concat two or more strings.
Parameters:
params [arguments] Any number of arguments. (Required)
Returns string
Usage:
{{concat 'Hello' ' world' '!!!'}} => 'Hello world!!!'
Join the elements of an array using a delimeter.
Parameters:
array [array] An array of elements to be joined. (Required)
delimeter [string] The delimeter using which the elements of array are to be joined. (Required)
Returns string
Usage:
someArray = ['Hands', 'legs', 'feet'];
{{join someArray ' & '}} => 'Hands & legs & feet'
A sum
helper calculating the sum of two numbers.
Parameters:
value1 [number] First number. (Required)
value2 [number] Second number. (Required)
Returns number
Usage:
{{sum 1 2}} => 3
{{sum 5.6 6.7}} => 12.3
A difference
helper calculating the difference of two numbers.
Parameters:
value1 [number] First number. (Required)
value2 [number] Second number. (Required)
Returns number
Usage:
{{difference 5 2}} => 3
{{difference 7.2 3.4}} => 3.8
A multiplication
helper calculating the multiplication of two numbers.
Parameters:
value1 [number] First number. (Required)
value2 [number] Second number. (Required)
Returns number
Usage:
{{multiplication 5 2}} => 10
{{multiplication 5.2 6.4}} => 33.28
A division
helper calculating the division of two numbers.
Parameters:
value1 [number] First number. (Required)
value2 [number] Second number. (Required)
Returns number
Usage:
{{division 4 2}} => 2
{{division 5.2 1.6}} => 3.25
A remainder
helper calculating the remainder of two numbers.
Parameters:
value1 [number] First number. (Required)
value2 [number] Second number. (Required)
Returns number
Usage:
{{remainder 5 3}} => 2
{{remainder 5.2 2.5}} => 0.20000000000000018
A ceil
helper to find the ceil value of the number. Equivalent to Math.ceil()
in JavaScript.
Parameters:
value1 [number] Number to be rounded to nearest greater integer. (Required)
Returns integer
Usage:
{{ceil 5.6}} => 6
A floor
helper to find the floor value of the number. Equivalent to Math.floor()
in JavaScript.
Parameters:
value [number] Number to be rounded to nearest lower integer. (Required)
Returns integer
Usage:
{{floor 5.6}} => 5
An abs
helper to find the absolute value of the number. Equivalent to Math.abs()
in JavaScript.
Parameters:
value [number] Number to perform absolute value operation on. (Required)
Returns number
Usage:
{{abs -5.6}} => 5.6
Note: To use DateTime helpers install moment.
npm install moment --save
A formatDate
helper to format date using moment.js
Parameters:
formatString [string] Format string based on moment.js (Required)
date [date] The date/date-time that needs to be formatted. (set to current Date() if not provided)
localeString [string] ISO 3166-1 locale code represented in https://github.com/moment/moment/tree/develop/locale
or an array of possible locale codes, of which moment will use the first one it has a localization for.
Returns string
Usage:
var date = new Date(); // Date | Date-time
{{formatDate 'MM/DD/YYYY' date}}
var date = new Date('01/22/2016');
var possibleI8nCodes = ['xy', 'aa', 'de'];
{{formatDate 'YYYY-MM-DD' date}} => 2016-01-22
{{formatDate 'LLLL', date, 'es'}} => 'viernes, 22 de enero de 2016 0:00'
{{formatDate 'LLLL', date, possibleI8nCodes}} => 'Freitag, 22. Januar 2016 00:00'
A showIf
helper for showing any HTML element.
Parameters:
expression [boolean] Condition to be checked. (Required)
Returns string
Usage:
{{showIf true}} => ''
{{showIf false}} => 'hidden'
A hideIf
helper for hiding any HTML element.
Parameters:
expression [boolean] Condition to be checked. (Required)
Returns string
Usage:
{{hideIf true}} => 'hidden'
{{hideIf false}} => ''
A selectedIf
helper for dropdown and radio boxes.
Parameters:
expression [boolean] Condition to be checked. (Required)
Returns string
Usage:
{{selectedIf true}} => 'selected'
A checkedIf
helper for checkboxes.
Parameters:
expression [boolean] Condition to be checked. (Required)
Returns string
Usage:
{{checkedIf true}} => 'checked'
An options
helper for generating <option>
list for <select>
dropdowns.
Parameters:
data [array] List of data (Required)
id [string] Name of identifier key from the data list, defaults to id (Optional)
text [string] Name of description key from the data list, defaults to description (Optional)
selected [string] Id to be set as selected (Optional)
Usage:
{{{options data}}}
{{{options data selected="value"}}}
{{{options data id="id" text="description"}}}
A simple example:
const data = [
{
id: 1,
description: 'Foo'
},
{
id: 2,
description: 'Bar'
},
{
id: 3,
description: 'Foo Bar'
}
];
{{{options data selected="2"}}}
will generate HTML:
<option value="1">Foo</option>
<option value="2" selected>Bar</option>
<option value="3">Foo Bar</option>
You can also override the default key names for id
& description
using the id
& text
options in the helper.
const data = [
{
value: 1,
text: 'New York'
},
{
value: 2,
text: 'London'
}
];
{{{options data selected="1" id="value" text="text"}}}
will generate HTML:
<option value="1" selected>New York</option>
<option value="2">London</option>
Format the currency value according to country code and locale.
Note: To use the formatCurrency
helper install currencyformatter.js.
npm install currencyformatter.js --save
Parameters:
value [number] The numerical value of currency. (Required)
args [arbitrary arguments] The currency formatting parameters. (Optional)
Returns: string
Usage:
{{formatCurrency 1234567.89 code='USD'}} => $1,234,567.89
{{formatCurrency 1234567.89 code='EUR'}} => 1.234.567,89 €
{{formatCurrency 1234567.89 code='EUR' locale="en"}} => €1,234,567.89
Note: The currency formatting parameters are used from https://github.com/osrec/currencyFormatter.js.
Project participants should adhere to the Code of Conduct. If you are unsure about how to contribute please file an issue.
Start here: src/H.js
# Install dependencies
$ yarn
# Lint source code
$ yarn lint
# Compile everything
$ gulp
# Run all the tests
$ yarn test
Check the CHANGELOG for change log and release history.
Licensed under The MIT License.