Package Exports

helper-lib

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (helper-lib) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Helper Library v0.1.4

A growing collection of useful Handlebars helpers.

Quick start

These quick start options are available:

with npm

Install the module with: npm install helpers

var helpers = require('helpers');

without npm

Download the latest release.
Clone the repo: git clone git://github.com/assemble/helper-lib.git.
Install with Twitter's Bower: bower install helper-lib.

Overview

Handlebars.js ships with some built-in helpers, such as {{#each}}, {{#if}} and {{#unless}}. Here is how helpers work:

A Handlebars helper call is a simple identifier, followed by zero or more parameters (separated by space).
Each parameter is a Handlebars expression.
Handlebars helpers can be accessed from any context in a template.

Handlebars.js is currently the default template library for assemble.

The Helpers

Strings

hyphenate

Replace spaces in string with hyphens.
Parameters: none

{{hyphenate "make this all hyphenated"}}

// Result 
make-this-all-hyphenated

dashify

Same as hyphenate, but replaces dots in string with hyphens.
Parameters: none

{{dashify "make.this.all.hyphenated"}}

// Result
make-this-all-hyphenated

lowercase

Turns a string to lowercase.
Parameters: none

{{lowercase "MAKE THIS ALL LOWERCASE"}}

// Result
make this all lowercase

uppercase

Turns a string to uppercase. Opposite of {{lowercase}}.
Parameters: none

 {{uppercase "make this all uppercase"}}

// Result
MAKE THIS ALL UPPERCASE

capitalizeFirst

Capitalizes the first word in a string.
Parameters: none

{{capitalizeFirst "capitalize first word in this sentence"}}

// Result
Capitalize first word in this sentence

capitalizeEach

Capitalizes each word in a string.
Parameters: none

{{capitalizeEach "capitalize EACH word in this sentence"}}

// Result
Capitalize EACH Word In This Sentence

titleize

Capitalizes all words within a string. Taken from the templating library Walrus by Jeremy Ruppel.
Parameters: none

{{titleize "capitalize EACH word in this sentence"}}

// Result
Capitalize Each Word In This Sentence.

sentence

Capitalizes the first word of each sentence in a string and converts the rest of the sentence to lowercase. Parameters: none

{{sentence "capitalize the FIRST word in each sentence. but make the OTHER words lowercase."}}

// Result
Capitalize the first word in each sentence. But make the other words lowercase.

reverse

Reverses a string.
Parameters: none

{{reverse "bender should NOT be allowed on TV."}}

// Result
.VT no dewolla eb TON dluohs redneb

truncate

Truncates a string given a specified length, providing a custom string to denote an omission.
Parameters:

length: int- The number of characters to keep (Required).
omission: string - A string to denote an omission (Optional).

{{truncate "Bender should not be allowed on tv." 31 "..."}}

// Result
Bender should not be allowed...

center

Centers a string using non-breaking spaces.
Parameters: spaces: int - The number of spaces. (Required)

{{center "Bender should not be allowed on tv." 10}}

// Result:
|              Bender should not be allowed on tv.              |

newLineToBr

Converts new line characters \n to line breaks <br>.
Parameters: none

{{{newLineToBr "Bender \n should \n not \n be allowed on tv."}}}

// Result:
Bender <br> should <br> not <br> be allowed on tv.

nl2br

Convert new lines (\r\n, \n\r, \r, \n) to line breaks
Parameters: none

{{nl2br <br>description}}

// Result: 
<br>

Collections

first

Returns the first item in a collection.
Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{first collection}}

// Result:
Amy Wong

withFirst

Use the first item in a collection inside a block.
Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{#withFirst collection}}
  <p>{{this}} is smart.</p>
{{/withFirst}}

// Result:
<p>Amy Wong is smart.</p>

last

Returns the last item in a collection. Opposite of first.
Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{last collection}}

// Result:
Scruffy

withLast

Use the last item in a collection inside a block. Opposite of withFirst.
Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{#withLast collection}}
  <p>{{this}} is lazy.</p>
{{/withLast}}

// Result:
<p>Scruffy is lazy.</p>

after

Returns all of the items in the collection after the specified count.
Parameters: count int - How many items to omit from the beginning. (Required)

// Date
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{after collection 5}}

// Result:
Leela, Professor Farnsworth, Scruffy

withAfter

Use all of the items in the collection after the specified count inside a block.
Parameters: count int - How many items to omit from the beginning. (Required)

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{#withAfter collection 5}}
    {{titleize this}}
{{/withAfter}}

// Result:
Leela Professor Farnsworth Scruffy

before

Returns all of the items in the collection before the specified count. Opposite of after.
Parameters: count int - How many items to omit from the end. (Required)

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{before collection 5}}

// Result:
Amy Wong, Bender, Dr. Zoidberg

withBefore

Use all of the items in the collection before the specified count inside a block. Opposite of withAfter.
Parameters: count int - How many items to omit from the end. (Required)

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{#withBefore collection 5}}
    {{reverse this}}
{{/withBefore}}

// Result:
gnoW ymA redneB grebdioZ .rD

join

Joins all elements of a collection into a string using a separator if specified.
Parameters: separator string - A string to use as a separator between the items. (Optional)

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{join collection " & "}}

// Result:
Amy Wong & Bender & Dr. Zoidberg & Fry & Hermes Conrad & Leela & Professor Farnsworth & Scruffy

sort

Returns the collection sorted. Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{sort collection}}

// Result:
Amy Wong, Bender, Dr. Zoidberg, Fry, Hermes Conrad, Leela, Professor Farnsworth, Scruffy

withSort

Uses the sorted collection inside the block.
Parameters: field string - String name of the field or property to sort by. (Optional)

// Data
collection = [
  name: 'Leela'
  deliveries: 8021,

  name: 'Bender'
  deliveries: 239,

  name: 'Fry'
  deliveries: -12
]

// Template
{{#withSort collection "deliveries"}}
    {{name}}: {{deliveries}} <br>
{{/withSort}}

// Result:
Fry: -12
Bender: 239
Leela: 8021

length

Returns the length of the collection.
Parameters: none

// Data
collection = [
  'Amy Wong', 
  'Bender', 
  'Dr. Zoidberg', 
  'Fry', 
  'Hermes Conrad', 
  'Leela', 
  'Professor Farnsworth', 
  'Scruffy'
]

// Template
{{length collection}}

// Result:
8

lengthEqual

Conditionally render a block based on the length of a collection.
Parameters: length int - The value to test against. (Required)

// Data
collection = [
  name: 'Leela'
  deliveries: 8021,

  name: 'Bender'
  deliveries: 239,

  name: 'Fry'
  deliveries: -12
]

// Template
{{#lengthEqual collection 3}}
        There are 3 people in Planet Express.
{{else}}
        This is not Planet Express.
{{/lengthEqual}}

// Result:
There are 3 people in Planet Express.

empty

Conditionally render a block if the collection is empty.
Parameters: none

// Data
collection = []

// Template
{{#empty collection}}
        Good news everyone!
{{else}}
        Bad news everyone!
{{/empty}}

// Result:
Good news everyone!

any

Conditionally render a block if the collection isn't empty. Opposite of empty
Parameters: none

// Data
collection = ['Professor Farnsworth']

// Templates
{{#any collection}}
        Good news everyone!
{{else}}
        Bad news everyone!
{{/any}}

// Result:
Good news everyone!

inArray

Conditionally render a block if a specified value is in the collection.
Parameters: value string|int - A value to test against. (Required)

// Data
collection = ['Professor Farnsworth', 'Fry', 'Bender']

// Templates
{{#inArray collection "Fry"}}
        I'm walking on sunshine!
{{else}}
        I'm walking on darkness.
{{/any}}

// Result:
I'm walking on sunshine!

eachIndex

Current implementation of the default Handlebars loop helper {{#each}} adding index (0-based index) to the loop context.
Parameters: none

// Data
collection = ['Professor Farnsworth', 'Fry', 'Bender']

// Templates
{{#eachIndex collection}}
    {{this}} is {{index}}
{{/eachIndex}}

// Result:
Professor Farnsworth is 0, Fry is 1, Bender is 2

eachProperty

Loop through an objects properties
Parameters: none

// Data
TODO...

// Templates
{{#eachProperty object}}
    {{property}}: {{value}}<br/>
{{/eachProperty }}

// Result
TODO...

Math

add

Returns the sum of two numbers.
Parameters: value int - The number to add to the expression. (Required)

// Data
value = 5

// Template
{{add value 5}}

// Result:
10

subtract

Returns the difference of two numbers. Opposite of add
Parameters: value int - The number to subtract from the expression. (Required)_

// Data
value = 5

// Template
{{subtract value 5}}

// Result:
0

divide

Returns the division of two numbers.
Parameters: value int - The number to divide the expression. (Required)

// Data
value = 5

// Template
{{divide value 5}}

// Result:
1

multiply

Returns the multiplication of two numbers.
Parameters: value int - The number to multiply the expression. (Required)

// Data
value = 5

// Template
{{multiply value 5}}

// Result:
25

floor

Returns the value rounded down to the nearest integer.
Parameters: none

// Data
value = 5.6

// Template
{{floor value}}

// Result:
5

ceil

Returns the value rounded up to the nearest integer.
Parameters: none

// Data
value = 5.6

// Template
{{ceil value}}

// Result:
6

round

Returns the value rounded to the nearest integer.
Parameters: none

// Data
value = 5.69

// Template
{{round value}}

// Result:
6

Numbers

toFixed

Returns exactly digits after the decimal place. The number is rounded if necessary, and the fractional part is padded with zeros if necessary so that it has the specified length.
Parameters: digits int - The number of digits to appear after the decimal point. (Optional)

// Data
value = 5.53231

// Template
{{toFixed value 3}}

// Result:
5.532

toPrecision

Returns the number in fixed-point or exponential notation rounded to precision significant digits.
Parameters: precision int - The number of digits. If omitted, it returns the entire number (without any formatting). (Optional)

// Data
value = 555.322

// Template
{{toPrecision value 4}}

// Result:
555.3

toExponential

Returns the number in exponential notation with one digit before the decimal point, rounded to fractions digits after the decimal point.
Parameters: fractions int - An integer specifying the number of digits after the decimal point. (Optional)

// Data
value = 5

// Template
{{toExponential value 5}}

// Result:
5.00000e+0

toInt

Returns an integer.
Parameters: none

// Data
value = '22.2abc'

// Template
{{toInt value}}

// Result:
22

toFloat

Returns a floating point number.
Parameters: none

// Data
value = '22.2abc'

// Template
{{toFloat value}}

// Result:
22.2

addCommas

Adds commas to a number.
Parameters: none

// Data
value = 2222222

// Template
{{addCommas value}}

// Result:
2,222,222

Comparisons

Equal

is

Conditionally render a block if the condition is true.
Parameters: value string|int - the value to test against.

// Data
number = 5

// Template
{{#is number 5}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/is}}

// Result:
Kiss my shiny metal ass!

if_eq

Same as is, consider consolidating Conditionally render a block if the condition is true (If x = y). Parameters: none

{{#if_eq x compare=y}} ... {{/if_eq}}

isnt

Conditionally render a block if the condition is false. Opposite of is.
Parameters: value string|int - the value to test against.

// Data
number = 5

// Template
{{#isnt number 5}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/isnt}}

// Result:
Never mind :(

or

Conditionally render a block if one of the values is truthy.
Parameters: values string|int - the values to test against.

great = no
magnificent = true

// Template
{{#or great magnificent}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/or}}

// Result:
Kiss my shiny metal ass!

and

Conditionally render a block if both values are truthy.
Parameters: values string|int - the values to test against.

// Data
great = true
magnificent = true

// Template
{{#and great magnificent}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/and}}

// Result:
Kiss my shiny metal ass!

unless_eq

Same as isnt, consider consolidating Conditionally render a block if the condition is false (Unless x = y). Opposite of is. Parameters: none

{{#unless_eq x compare=y}} ... {{/unless_eq}}

Greater Than

if_gt

Conditionally render a block if the value is greater than a given number (If x > y). Parameters: none

{{#if_gt x compare=y}} ... {{/if_gt}}

gt

Same as if_gt, consider consolidating Conditionally render a block if the value is greater than a given number (If x > y).
Parameters: value string|int - the value to test against.

// Data
number = 5

// Template
{{#gt number 8}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/gt}}

// Result:
Never mind :(

unless_gt

Unless greater than (Unless x > y) Parameters: none

{{#unless_gt x compare=y}} ... {{/unless_gt}}

if_gteq

Conditionally render a block if the value is greater or equal than a given number (If x >= y). Parameters: none

{{#if_gteq x compare=y}} ... {{/if_gteq}}

gte

Same as if_gteq, consider consolidating Conditionally render a block if the value is greater or equal than a given number (If x >= y).
Parameters: value string|int - the value to test against.

number = 5

// Template
{{#gte number 5}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/gte}}

// Result:
Kiss my shiny metal ass!

unless_gteq

Render block, unless given value is greater than or equal to. Parameters: none Unless x >= y

{{#unless_gteq x compare=y}} ... {{/unless_gteq}}

Less Than

lt

Conditionally render a block if the value is less than a given number. Opposite of gt.
Parameters: value string|int - the value to test against.

number = 5

{{#lt number 3}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/lt}}

// Result:
Never mind :(

lte

Conditionally render a block if the value is less or equal than a given number. Opposite of gte.
Parameters: value string|int - the value to test against.

number = 5

// Template
{{#lte number 5}}
    Kiss my shiny metal ass!
{{else}}
    Never mind :(
{{/lte}}

// Result:
Kiss my shiny metal ass!

unless_lt

Render block, unless value is less than a given number (Unless x < y) Parameters: none

{{#unless_lt x compare=y}} ... {{/unless_lt}}

unless_lteq

Render block, unless value is less than or equal to a given number (Unless x <= y) Parameters: none

{{#unless_lteq x compare=y}} ... {{/unless_lteq}}

Special

formatPhoneNumber

Output a formatted phone number Credit: Treehouse Blog

phoneNumber: 4444444444

{{formatPhoneNumber phoneNumber}}

Result:

(444) 444-4444

Dates

formatDate

Formats a date into a string given a format. Accepts any value that can be passed to new Date(). This helper is a port of the formatDate-js library by Michael Baldry.
Parameters: format string - The format string, according to these tokens: strftime (Required)

// Data
date = new Date()

// Template
{{formatDate date "%m/%d/%Y"}}
{{formatDate date "%I:%M%p"}}
{{formatDate date "%F"}}
{{formatDate date "%Y%m%dT%H%M%S%z"}}

// Result:
07/26/2012
11:38PM
2012-07-26
20120726T233805-0004

now

Returns the current date.
Parameters: format string - The format string, according to these tokens: http://www.ruby-doc.org/core-1.9.3/Time.html#method-i-strftime (Optional)

// Template
{{now}}
{{now "%m/%d/%Y"}}

// Result:
Thu Jul 26 2012 23:41:02 GMT-0400 (AST)
07/26/2012

timeago

Returns a human-readable time phrase from the given date.
Parameters: none

// Data
date = 'Thu Jul 22 2012 23:41:02 GMT-0400 (AST)'

// Template
{{timeago date}}

// Result:
4 days ago

Inflections

inflect

Returns the plural or singular form of a word based on a count.
Parameters:

singular string - The singular form of the word. (Required)
plural string - The plural form of the word. (Required)
include boolean - whether or not to include the count before the word. (Optional)

// Data
enemies = 0
friends = 1

// Template
{{inflect enemies "enemy" "enemies"}}
{{inflect friends "friend" "friends" true}}

// Result:
enemies
1 friend

#### ordinalize
_Turns a number into an ordinal string. Taken from the templating library [Walrus](https://github.com/jeremyruppel/walrus) by [Jeremy Ruppel](https://github.com/jeremyruppel)._
<br>Parameters: `none`
``` html
// Template
{{ordinalize 3}}
{{ordinalize 1}}
{{ordinalize 22}}

// Result:
3rd
1st
22nd

HTML

ul

Creates an unordered list.
Parameters: hash html attributes - HTML attributes to use on the ul element. (Optional)

// Data
collection = [
        name: 'Leela'
        deliveries: 8021
    ,
        name: 'Bender'
        deliveries: 239
    ,
        name: 'Fry'
        deliveries: 1
]

// Template
{{#ul collection class="deliveries-list"}}
{{name}} - {{inflect deliveries "delivery" "deliveries" true}}
{{/ul}}

// Result:
<ul class="deliveries-list">
    <li>
        Leela - 8021 deliveries
    </li>
    <li>
        Bender - 239 deliveries
    </li>
    <li>
        Fry - 1 delivery
    </li>
</ul>

ol

br

Same as the ul helper but creates and ordered list. Returns <br> tags based on a count.
Parameters: Count int - The number of br elements to render. (Optional)

// Template
{{br 5}}

// Result:
`<br><br>`

Logging

log

Simple console.log()
Parameters: none

// Template
{{log "Hi console :)"}}

// Result:
Hi console :)

debug

Simple console.debug() that shows the current context.
Parameters: none

// Data
collection = [
        name: 'Leela'
        deliveries: 8021
    ,
        name: 'Bender'
        deliveries: 239
    ,
        name: 'Fry'
        deliveries: 1
]

// Template
{{#withFirst collection}}
{{debug name}}
{{/withFirst}}

// Result:
Context: { deliveries: 8021, name: "Leela" }
Value: Leela

Miscellaneous

default

Provides a default or fallback value if a value doesn't exist.
Parameters: defaultValue string|int - The default value to use. title = ''

// Template
{{default title "Not title available."}}

// Result:
Not title available.

partial (NOT USED IN ASSEMBLE)

Provides an easy way to register and use partials inside your templates.

This helper only works if you define your templates as common.js modules, since it uses the common.js require function to find and register your templates with Handlebars.registerPartial. It was created with brunch in mind (which I use a lot), because brunch automatically wraps your scripts and templates in common.js modules to use in the browser.

Parameters:

name string - The name or path of the file in which your template is defined. (Required)
data int|string|collection - The data you want to use inside the partial. (Optional)

// Path to your templates from where you override config.partialsPath
// The path must finish with a foward slash '/'
config.partialsPath = '../views/templates/'

// Data
collection = [
  'Professor Farnsworth', 
  'Fry', 
  'Bender'
]

// Your Partial (planet_express.hbs)
{{sort this}}

// Your template
<p>{{partial "planet_express" collection}}</p>

// Result:
<p>Bender, Fry, Professor Farnsworth</p>

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Adding Custom Helpers

Contributions welcome! Please consider adding your own helpers to this library.

Handlebars accels over other templating libraries when it comes to creating your own custom helpers. Just register your function into Handlebars with the Handlebars.registerHelper method, and that helper will be available to any template you compile afterwards.

Handlebars allows two different kinds of helpers:

Expression helpers are basically regular functions that take the name of the helper and the helper function as arguments. Once an expression helper is registered, it can be called anywhere in your templates, then Handlebars takes the expression's return value and writes it into the template.
Block helpers There are a few block helpers included by default with Handlebars, {{#each}}, {{#if}} and {{#unless}}. Custom block helpers are registered the same way as exptression helpers, but the difference is that Handlebars will pass the contents of the block compiled into a function to the helper.

Release History

2013-03-16 v0.1.3 New helpers, "formatPhoneNumber" and "eachProperty"
2013-03-15 v0.1.2 Update README.md with documentation, examples.
2013-03-06 v0.1.0 First commit.

Roadmap

Separate into modules
Proper testing for each helper

Authors

Jon Schlinkert

Brian Woodward

Credit

Many of these helpers come from the following repos: