Nutritious Pumpkin Masses

    just-handlebars-helpers

    1.0.19 • Public • Published

    Just Handlebars Helpers

    NPM Version NPM Downloads Travis Codecov

    A lightweight package with common Handlebars helpers.

    Installation

    npm install just-handlebars-helpers --save
    yarn add just-handlebars-helpers

    Usage

    Browser

    General Usage

    <!-- 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>

    Recommended Usage (CDN)

    <!-- 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>

    Node

    // 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);

    Helpers

    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.

    Conditional

    eq

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

    eqw

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

    neq

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

    neqw

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

    lt

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

    lte

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

    gt

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

    gte

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

    not

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

    ifx

    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'}}  => ''
    

    empty

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

    count

    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;
    

    and

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

    or

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

    coalesce

    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'
    

    includes

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

    Strings

    excerpt

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

    sanitize

    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'
    

    newLineToBr

    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.
    

    capitalizeEach

    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'
    

    capitalizeFirst

    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

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

    lowercase

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

    uppercase

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

    first

    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'
    

    last

    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

    Concat two or more strings.

    Parameters:

    params [arguments] Any number of arguments. (Required)
    

    Returns string

    Usage:

    {{concat 'Hello' ' world' '!!!'}} => 'Hello world!!!'
    

    join

    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'
    

    Math

    sum

    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
    

    difference

    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
    

    multiplication

    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
    

    division

    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
    

    remainder

    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
    

    ceil

    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
    

    floor

    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
    

    abs

    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
    

    DateTime

    Note: To use DateTime helpers install moment.

    npm install moment --save

    formatDate

    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'
    

    HTML

    showIf

    A showIf helper for showing any HTML element.

    Parameters:

    expression [boolean] Condition to be checked. (Required)
    

    Returns string

    Usage:

    {{showIf true}}     => ''
    {{showIf false}}    => 'hidden'
    

    hideIf

    A hideIf helper for hiding any HTML element.

    Parameters:

    expression [boolean] Condition to be checked. (Required)
    

    Returns string

    Usage:

    {{hideIf true}}     => 'hidden'
    {{hideIf false}}    => ''
    

    selectedIf

    A selectedIf helper for dropdown and radio boxes.

    Parameters:

    expression [boolean] Condition to be checked. (Required)
    

    Returns string

    Usage:

    {{selectedIf true}}     => 'selected'
    

    checkedIf

    A checkedIf helper for checkboxes.

    Parameters:

    expression [boolean] Condition to be checked. (Required)
    

    Returns string

    Usage:

    {{checkedIf true}}      => 'checked'
    

    options

    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>
    

    Formatters

    formatCurrency

    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.

    Contributing

    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

    Inspired by

    Change Log

    Check the CHANGELOG for change log and release history.

    License

    Licensed under The MIT License.

    Install

    npm i just-handlebars-helpers

    DownloadsWeekly Downloads

    43,926

    Version

    1.0.19

    License

    MIT

    Unpacked Size

    1.02 MB

    Total Files

    20

    Last publish

    Collaborators

    • leapfrogsuperadmin
    • mesaugat
    • kabirbaidhya
    • sanjeevkpandit
    • gurungsuman15