helper-lib v0.2.6

Extensive collection of Handlebars helpers.

Quick start

For linting and testing this project uses Grunt ~0.4.1, but Grunt is not required to use the helpers. Check out the Getting Started guide to learn more about Grunt.

npm install helper-lib --save

Once helper-lib has been installed, it may be used within your application with the following JavaScript:

var handlebars = require('Handlebars');
var helpers = require('helper-lib');
helpers.register(Handlebars);

Now your handlebars instance will have access to the helpers.

Features unique to helper-lib

Some helpers offer useful functionality that is unique to this project, such as:

File globbing using minimatch patterns
Access to assemble options.
Ability to render either markdown or HTML conditionally based on the file extension of the generated file.

Lots more...

Table of Contents

The Helpers

Markdown helpers

Markdown helpers only work with assemble, Grunt.js plugin for generating sites.

Include markdown from specified file(s), and render it to HTML

Template:

{{md "file/to/include/post.md"}}

Any content inside the "included" markdown file will be rendered as HTML.

Block helper for embedding markdown content inside HTML, and rendering it to HTML at build time.

Template:

<h1>My Blog</h1>

{{#markdown}}
## Post of the day

Vestibulum posuere, quam sed bibendum posuere
Pellentesque habitant morbi tristique senectus
Pellentesque nulla augue, volutpat vitae

[Read more...](https://github.com/assemble/jonschlinkert)

In hac habitasse platea dictumst. Morbi non rutrum risus.

{{/markdown}}

Renders to:

<h1>My Blog</h1>

<h2>Post of the day</h2>

<p>Vestibulum posuere, quam sed bibendum posuere
Pellentesque habitant morbi tristique senectus
Pellentesque nulla augue, volutpat vitae</p>

<a href="https://github.com/assemble/jonschlinkert">Read more...</a>

<p>In hac habitasse platea dictumst. Morbi non rutrum risus.</p>

Code helpers

Embed code from specified file(s)

Parameters:

String|File : path to the file you want to embed
String|Language (optional): Optional second parameter to "force" a specific language to use fo syntax highlighting.

Unless overridden by a given extension, the helper will automatically use the extension of the specified file as the language to use for syntax highlighting. You may also force the helper to use a language that is different than the extension of the file.

For example, here we will force highlighting as javascript instead of json

{{ embed 'src/example.json' 'js' }}

When embedding a markdown snippet (.md|markdown|markd), the helper automatically converts any code fences inside the snippet their unicode equivalent (```)

{{embed 'src/example.md'}}

File globbing

The embed helper also accepts globbing patterns:

{{embed 'src/code-examples/*.*'}}

When globbing file is used, the code from each file will be embedded separately, and the file extension of each file will be used to identify the language to use for syntax highlighting. You may of course override the language, but whatever language you use will be applied to every embedded file.

use globbing carefully! Until you have the hang of it try to be on the safe side and be more specific with your patterns

Embed public GitHub Gists by adding only the Id of the Gist. The helper also accepts an optional second parameter for targeting a specific file on the Gist..

Parameters: String Default: undefined Usage: {{ gist [id] }}

Example:

{{gist '5193239'}}

Output:

<script src="https://gist.github.com/5193239.js"></script>

Easily embed a jsFiddle in a page, requiring only the ID of the fiddle.

Credit: octopress

Parameters: {{ jsfiddle "id" "tabs" "skin" "height" "width" }}

id: full URL to the fiddle excluding http://jsfiddle.net
tabs: tabs to be displayed, and the order specified
skin: the skin to be used, light or presentation are the only options available.
height: the height of the rendered <iframe>
width: the width of the rendered <iframe>

Template:

{{ jsfiddle 'ccWP7' }}

Fiddle tabs

You may also adjust the tabs shown and/or the order in which tabs are displayed.

Default tabs and display order: js,resources,html,css,result

Options:

js, html, css: tabs for displaying code
result: tab for displaying the rendered result of the code
resources: tabs for displaying the list of external resources used. This tab will not be displayed if no resources were used.

Template:

{{jsfiddle 'ccWP7' 'result,js,html,css'}}

Renders to:

<iframe style="width: 100%; height: 210px"src="http://jsfiddle.net/ccWP7/embedded/result,js,html,css/"></iframe>

You may remove the tabs you don't need:

Template:

{{jsfiddle 'ccWP7' 'js,result'}}

Renders to:

<iframe style="width: 100%; height: 210px"src="http://jsfiddle.net/abc123/embedded/js,result/"></iframe>

Fiddle skins

A third optional parameter may be used to specify the "skin" for the fiddle. At time of writing, the only skins available are light and presentation. However as jsFiddle announces new skins they may be used immediately.

Default: light

Template:

{{jsfiddle 'ccWP7' 'result,js,html,css' 'presentation'}}

Renders to:

<iframe style="width: 100%; height: 210px"src="http://jsfiddle.net/ccWP7/embedded/js,result/presentation/"></iframe>

Path helpers

Path helpers are node.js utilities for handling and transforming file paths. As with node.js:

"these helpers perform only string transformations. The file system is not consulted to check whether paths are valid."

Derive the relative path from one absolute path to another (e.g from path A, to path B).
Parameters: string (the value to test against)
Default: none

Example:

{{relative "from" "to"}}

Usage:

<a href="{{relative "src" "dist"}}/assets/css/styles.css"></a>

Renders to:

<a href="../../dist/assets/css/styles.css"></a>

"Return the extension of the path, from the last '.' to end of string in the last portion of the path. If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string."

Parameters: string (the value to test against). Default: none

Template:

{{extname 'index.html'}}

Renders to:

.html

Template:

{{extname 'index.'}}

Renders to:

Template:

{{extname 'index'}}

Returns nothing.

Return the directory name of a path. Similar to the Unix dirname command.

Template:

{{dirname '/foo/bar/baz/asdf/quux'}}

Renders to:

'/foo/bar/baz/asdf'




## URL helpers
URL helpers are [node.js](http://nodejs.org/api/url.html) `url` utilities for URL resolution and parsing. As with node.js: 

> "Parsed URL objects have some or all of the following fields, depending on whether or not they exist in the URL string. Any parts that are not in the URL string will not be in the parsed object."

#### {{url_resolve}}
_Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag._

<br>Template:
``` haskell
{{url_resolve url href}}

Example:

<a href="{{url_resolve "http://example.com/one" "/two"}}"></a>

Renders to:

<a href="http://example.com/two"></a>

Take a URL string, and return an object.

Params:

url
Output format: yaml or json. Default: json

Template:

{{url_parse "http://example.com/one"}}

Renders to:

{
  "protocol": "http:",
  "slashes": true,
  "auth": null,
  "host": "example.com",
  "port": null,
  "hostname": "example.com",
  "hash": null,
  "search": null,
  "query": null,
  "pathname": "/one",
  "path": "/one",
  "href": "http://example.com/one"
}

Or with yaml as the second param:

{{url_parse "http://foo.com/bar/baz?key=value" "yaml"}}

Renders to:

protocol: "http:"
slashes: true
auth: null
host: "foo.com"
port: null
hostname: "foo.com"
hash: null
search: "?key=value"
query: "key=value"
pathname: "/bar/baz"
path: "/bar/baz?key=value"
href: "http://foo.com/bar/baz?key=value"
parse: 
format: 
resolve: 
resolveObject: 
parseHost:

File helpers

Include external files.

Pattern: {{include [name] [data]}}
Parameters:

name (required): [string] - The name or path of the file in which your template is defined. (Required)
data (optional): [int|string|collection] - Data you want to use inside the include.

Data (collection): planet-express.json

[
  "Professor Farnsworth", 
  "Fry", 
  "Bender"
]

Include (partial to be "included"): planet-express.hbs

{{sort this}}

Template:

<p>{{include "planet-express.hbs" data}}</p>

Renders to:

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

example helpers, not for actual use! Why do this? The goal is to inspire other concepts that build from this one.

Use globbing patterns to embed content from specified file or files.
Parameters: String
Default: undefined

Examples:

{{glob 'src/files/*.md'}}
{{glob 'src/files/*.{txt,md}'}}

example helpers, not for actual use! Why do this? The goal is to inspire other concepts that build from this one.

Example helper, copies file A to path B.
Parameters: String
Default: undefined

Example:

{{copy 'a.html' '../dir/b.txt'}}

README helpers

Generates a list of markdown-formatted project authors from the AUTHORS file in the root of a project. Since Handlebars enforces case sensitivity with helper names, this helper comes in two different flavors: {{AUTHORS}} or {{authors}}.

Params: none Usage: {{authors}} or {{authors "path/to/AUTHORS"}}

Data (AUTHORS file in the root of our project):

Brian Woodward (http://github.com/doowb)
Jon Schlinkert (http://github.com/jonschlinkert)

Template (lowercase version):

{{authors}}

Renders to:

* [Brian Woodward](http://github.com/doowb)  
* [Jon Schlinkert](http://github.com/jonschlinkert)

Or the uppercase version:

{{AUTHORS}}

Renders to:

**Jon Schlinkert**

+ [http://twitter.com/jonschlinkert](http://twitter.com/jonschlinkert)
+ [http://github.com/jonschlinkert](http://github.com/jonschlinkert)

**Brian Woodward**

+ [http://twitter.com/doowb](http://twitter.com/doowb)
+ [http://github.com/doowb](http://github.com/doowb)

Travis CI

Creates a "full" Travis CI link in markdown format.

Params: branch Type: String Usage: {{travis [branch]}}

Template:

{{travis}}`

Renders to:

# [helper-lib v2.0.0](https://github.com/assemble/helper-lib)[![Build Status](https://travis-ci.org/assemble/helper-lib.png)](https://travis-ci.org/assemble/helper-lib)

Template with branch:

{{travis 'master'}}

Renders to:

# [helper-lib v2.0.0](https://github.com/assemble/helper-lib)[![Build Status](https://travis-ci.org/assemble/helper-lib.png?branch=master)](https://travis-ci.org/assemble/helper-lib)

Creates a Travis CI link in markdown format.

Params: none Usage: {{travis-badge}}

Template

{{travis}}`

Renders to:

[![Build Status](https://travis-ci.org/assemble/helper-lib.png)](https://travis-ci.org/assemble/helper-lib)

A few convenience helpers that read data in YAML format, and do interesting things with the data. Well... they "do things" with the data. Anyway I guess only nerds like me find it interesting.

NOTE: These helpers will throw an error if the source files are not valid YAML format, using the following conventions:

A couple things to keep in mind about YAML:

YAML is picky, so don't be surprised if the parser throws an error from improperly placed quotation marks.
Seriously, don't be surprised. If you even come onto the issues and act surprised when it happens, an automated message will tell you to read the first bullet.

Example of the format to follow in your CHANGELOG file:

v0.1.2
  date: "2014-04-09"
  changes:
    - The future sucks.
    - This is my third and last commmit from the future.
v0.1.1
  date: "2014-04-08"
  changes:
    - Second commit from the future.
    - The future is more boring that I thought it would be.
v0.1.0
  date: "2014-03-07"
  changes:
    - First commit... from the future. Yes!

Of coure, you are under no obligation to make your changelog entries as interesting as these, and you may record your entries at any point in whatever timeline you prefer, but whatever you write must be valid YAML when you do it.

The output will look like this:

* 2013-03-15    v0.1.2    Update README.md with documentation, examples.
* 2013-03-06    v0.1.0    First commit.

More info here: js-yaml
See the tests here: test/helpers/special_test.js

HTML helpers

Easy way to add an uncommonly used doctype.

Default: HTML 5 (<!DOCTYPE html>), although tThis is probably only useful on projects that use anything besides HTML 5.

Template:

{{DOCTYPE 'svg 1.1'}}

Renders to:

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

Available doctypes:

HTML 5 (default)

<!DOCTYPE html>
examples: {{doctype '5'}}, {{doctype 'html5'}}
aliases: 5, html, html5

XML

<?xml version="1.0" encoding="utf-8" ?>
example: {{doctype 'xml'}}
aliases: xml

XHTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
example: {{doctype 'strict'}}
aliases: strict
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
aliases: transitional
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
aliases: frameset
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
aliases: 1.1, xhtml 1.1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
aliases: basic
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">
aliases: mobile

HTML 4.01

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
aliases: 4, 4.01, 4.01 strict
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
aliases: 4.01 trans
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
aliases: 4.01 frameset

SVG

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
aliases: svg, svg 1.1, svg1.1
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
aliases: svg 1.0, svg1.0, svg1

Planned...

Create a blockquote. Outputs a string with a given attribution as a quote.

Template:

{{#blockquote '@doowb' 'http://github.com/source/for/your/quote' 'This is the title' }}
  This is your quote.
{{/blockquote}}

Renders to:

<blockquote>
  <p>This is your quote.</p>
  <footer> 
    <strong>@doowb</strong>
    <cite> 
      <a href="http://github.com/source/for/your/quote">This is the title</a>
    </cite>
  </footer>
</blockquote>

Planned...

Iterates through an array, letting the contents know whether a timeline entry belongs in the left or right column.

Parameters:

array to iterate over,
string: CSS class name for left columns
string: CSS class name for right columns

Credit: by @jonschlinkert, and based on striped helper from treehouse blog

Usage:

<div class="timeline">
 {{#timeline myArray "left" "right"}}
 <div class="{{columnClass}}">
   {{> entry}}
 </div>
 {{else}}
   <em>There aren't any entries.</em>
 {{/timeline}}
</div>

Generate the appropriate icon based on the extension of the given file.

Since this helper generates classes that are very specific, feel free to copy the code and use it as inspiration for your a helper that works for you.

Usage:

{{exticon 'file.png'}}
{{exticon 'file.pdf'}}
{{exticon 'file.doc'}}
{{exticon 'file.txt'}}
{{exticon 'file.csv'}}
{{exticon 'file'}}

Output:

<img src="img/img-icon.png"><i>file.png</i>
<img src="img/pdf-icon.png"><i>file.pdf</i>
<img src="img/word-icon.png"><i>file.doc</i>
<img src="img/txt-icon.png"><i>file.txt</i>
<img src="img/csv-icon.png"><i>file.csv</i>
<img src="img/other-icon.png"><i>file</i>

Creates an unordered list.

Parameters: Hash|HTML attributes, Optional

HTML attributes to use on the ul element.

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

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

Same as the ul helper but creates and ordered list. Returns <br> tags based on a count.

Parameters: Hash, HTML attributes, Optional

HTML attributes to use on the ol element.

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

Template:

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

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

Renders <br> elements in the output, based on the number given as a parameter. Not really recommended for general use, but it's here if you need it.

Parameters: Integer|Count, Optional

The number of br elements to render.

template.hbs

{{br 5}}

renders to:

`<br><br><br><br><br>`

String helpers

Evaluate string A, and count the occurrences of string B within string A
Default: undefined
Parameters:

String A (required): The string to evaluate
String B (required): The string to look for and count in "string A"

{{occurrences "evaluate this string" "evaluate"}}

Result :

Replace spaces in string with hyphens.
Parameters: none

{{hyphenate "make this all hyphenated"}}

Result :

make-this-all-hyphenated

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

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

Renders to:

make-this-all-hyphenated

Turns a string to lowercase.
Parameters: none

{{lowercase "MAKE THIS ALL LOWERCASE"}}

Renders to:

make this all lowercase

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

 {{uppercase "make this all uppercase"}}

Renders to:

MAKE THIS ALL UPPERCASE

Capitalizes the first word in a string.
Parameters: none

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

Renders to:

Capitalize first word in this sentence

Capitalizes each word in a string.
Parameters: none

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

Renders to:

Capitalize EACH Word In This Sentence

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

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

Renders to:

Capitalize Each Word In This 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."}}

Renders to:

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

Reverses a string.
Parameters: none

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

Renders to:

.VT no dewolla eb TON dluohs redneb

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

Renders to:

Bender should not be allowed...

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

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

Renders to:

|              Bender should not be allowed on tv.              |

Output a formatted phone number

Credit: Treehouse Blog

Data:

number: 4444444444

Template:

{{formatPhoneNumber number}}

Renders to:

(444) 444-4444

Collections helpers

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

Renders to:

Amy Wong

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

Renders to:

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

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

Renders to:

Scruffy

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

Renders to:

<p>Scruffy is lazy.</p>

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

Renders to:

Leela, Professor Farnsworth, Scruffy

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

Renders to:

Leela Professor Farnsworth Scruffy

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

Renders to:

Amy Wong, Bender, Dr. Zoidberg

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

Renders to:

gnoW ymA redneB grebdioZ .rD

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

Renders to:

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

Returns the collection sorted. Parameters: none

Data:

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

Template:

{{sort collection}}

Renders to:

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

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

Renders to:

Fry: -12
Bender: 239
Leela: 8021

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

Renders to:

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

Renders to:

There are 3 people in Planet Express.

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

Data:

collection = []

Template:

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

Renders to:

Good news everyone!

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

Data:

collection = ['Professor Farnsworth']

Template:s

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

Renders to:

Good news everyone!

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

Template:s

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

Renders to:

I'm walking on sunshine!

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

Template:s

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

Renders to:

Professor Farnsworth is 0, Fry is 1, Bender is 2

Loop through an objects properties
Parameters: none

Data:

TODO...

Template:s

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

Renders to:

TODO...

Math helpers

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

Data:

value = 5

Template:

{{add value 5}}

Renders to:

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

Renders to:

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

Data:

value = 5

Template:

{{divide value 5}}

Renders to:

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

Data:

value = 5

Template:

{{multiply value 5}}

Renders to:

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

Data:

value = 5.6

Template:

{{floor value}}

Renders to:

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

Data:

value = 5.6

Template:

{{ceil value}}

Renders to:

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

Data:

value = 5.69

Template:

{{round value}}

Renders to:

Returns the sum of multiple numbers. Similar to {{#add}} block helper but accepts multiple arguments.
Parameters: none

Data:

value = {
  a: 1,
  b: 2,
  c: 3
}

Template:

{{sum value.a value.b value.c}}

Renders to:

Numbers helpers

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

Renders to:

5.532

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

Renders to:

555.3

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

Renders to:

5.00000e+0

Returns an integer.

Parameters: none

Data:

value = '22.2abc'

Template:

{{toInt value}}

Renders to:

Returns a floating point number.

Parameters: none

Data:

value = '22.2abc'

Template:

{{toFloat value}}

Renders to:

22.2

Returns the number in abbreviation formats based on a value. The number is rounded to a particular decimal place.

Parameters: digits int - The number of digits to appear after the decimal point. (Optional)

Default: 2

Data:

value = 123456789

Template:

{{toAbbr value}}

Renders to:

123.457m

Adds commas to a number.

Parameters: none

Data:

value = 2222222

Template:

{{addCommas value}}

Renders to:

2,222,222

Comparisons: "equal" helpers

Conditionally render a block if the condition is true (if x = y).

Parameters: string|int (the value to test against) Default: undefined

Example #1:

Data:

---
number = 5
---

Template:

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

Renders to:

Kiss my shiny metal ass!

Example #2:

If you are using Assemble, data from YAML front matter or any specified JSON and/or YAML source files will get passed through to the context in your templates.

Data and Templates:

---
page:
  title: About Us
---

{{#is page.title "Home"}}
    <h1> About Us </h1>
{{else}}
    <h1> My Blog </h1>
{{/is}}

Renders to:

<h1> About Us </h1>

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

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

Renders to:

Never mind :(

Conditionally render a block if one of the values is truthy.

Parameters: values string|int - the values to test against.

Data:

great = no
magnificent = true

Template:

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

Renders to:

Kiss my shiny metal ass!

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

Renders to:

Kiss my shiny metal ass!

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

Comparisons: "greater than" helpers

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

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

Renders to:

Never mind :(

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

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

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

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

Renders to:

Kiss my shiny metal ass!

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

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

Comparisons: "less than" helpers

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

Renders to:

Never mind :(

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

Renders to:

Kiss my shiny metal ass!

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

Parameters: none

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

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

Dates helpers

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, required The format string, according to these tokens: strftime

Given this data:

date = new Date()

And these templates:

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

The output would be:

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

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

Renders to:

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

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

Renders to:

4 days ago

Inflections helpers

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

Renders to:

enemies
1 friend

Turns a number into an ordinal string. Taken from the templating library Walrus by Jeremy Ruppel.

Parameters: none

Template:

{{ordinalize 3}}
{{ordinalize 1}}
{{ordinalize 22}}

Renders to:

3rd
1st
22nd

Logging helpers

Simple console.log()

Parameters: none

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

Renders to:

Hi console :)

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

Renders to:

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

Return a unique, JSON-formatted array of all file or directory paths that match the given globbing pattern(s)

Parameters: String Default: undefined

Template:

{{expandJSON './src/**/*.md'}}

Renders to:

[
  "./src/content/blockquotes.md",
  "./src/content/chapters/01-getting-started.md",
  "./src/content/chapters/02-language-features.md",
  "./src/content/chapters/03-advanced-materials.md",
  "./src/content/code.md",
  "./src/content/emphasis.md",
  "./src/content/headings.md",
  "./src/content/images.md",
  "./src/content/links.md",
  "./src/content/lists.md",
  "./src/content/markdown-here.md",
  "./src/content/paragraphs.md",
  "./src/content/post.md",
  "./src/content/reference-links.md",
  "./src/content/reference.md",
  "./src/content/tables.md",
  "./src/content/test.md"
]

Return a unique, YAML-formatted array of all file or directory paths that match the given globbing pattern(s)

Parameters: String

Default: undefined

Template:

{{expandYAML './src/**/*.md'}}

Renders to:

- "./src/content/blockquotes.md"
- "./src/content/chapters/01-getting-started.md"
- "./src/content/chapters/02-language-features.md"
- "./src/content/chapters/03-advanced-materials.md"
- "./src/content/code.md"
- "./src/content/emphasis.md"
- "./src/content/headings.md"
- "./src/content/images.md"
- "./src/content/links.md"
- "./src/content/lists.md"
- "./src/content/markdown-here.md"
- "./src/content/paragraphs.md"
- "./src/content/post.md"
- "./src/content/reference-links.md"
- "./src/content/reference.md"
- "./src/content/tables.md"
- "./src/content/test.md"

Miscellaneous helpers

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 "No title available."}}

Renders to:

No title available.

TODO...

How Handlebars Helpers Work

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.

Creating Helpers

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

Handlebars is advantageous 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.

Also, if you use Assemble be sure to visit the assemble docs to learn about registering custom helpers.

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.

Authors

Credit

Many of these helpers come from the following repos:

Copyright and license

MIT License

Release History

2013-05-11 v0.2.3 File globbing added to some helpers. Including md and some file helpers.
2013-05-07 v0.2.0 A bunch of new tests for markdown and special helpers. Refactored most of the rest of the helpers to separate functions from Handlebars registration.
2013-05-02 v0.1.32 Updated utils and a number of helpers, including value, property, and stringify.
2013-04-21 v0.1.31 Fixing relative helper
2013-04-20 v0.1.30 Refactoring helpers-collection module to separate the functions from the Handlebars helper registration process.
2013-04-16 v0.1.25 Adding defineSection and renderSection helpers to try to get sections populated in a layout from the page.
2013-04-07 v0.1.21 Add markdown helpers back, add more tests.
2013-04-06 v0.1.20 Generalized helpers structure, externalized utilities.
2013-04-05 v0.1.11 New authors and gist helpers, general cleanup and new tests.
2013-04-04 v0.1.10 Externalized utility javascript from helpers.js
2013-03-28 v0.1.8 Gruntfile updated with mocha tests for 71 helpers, bug fixes.
2013-03-18 v0.1.7 New path helper "relative", for resolving relative path from one absolute path to another.
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.

Authored by assemble

This file was generated using Grunt and assemble on Thu Jun 13 2013 16:52:04.

Name		Name	Last commit message	Last commit date
Latest commit History 257 Commits
docs		docs
lib		lib
src		src
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.jshintrc		.jshintrc
.travis.yml		.travis.yml
AUTHORS		AUTHORS
CHANGELOG		CHANGELOG
Gruntfile.js		Gruntfile.js
LICENSE-MIT		LICENSE-MIT
README.md		README.md
ROADMAP		ROADMAP
bower.json		bower.json
index.js		index.js
package.json		package.json

License

Arkkimaagi/assemble-handlebars-helpers

Folders and files

Latest commit

History

Repository files navigation

Quick start

Features unique to helper-lib

Markdown helpers

{{md}}

{{markdown}}

Code helpers

{{embed}}

{{gist}}

{{jsfiddle}}

Fiddle tabs

Fiddle skins

Path helpers

{{relative}}

{{extname}}

{{dirname}}

{{url_parse}}

File helpers

{{include}}

{{glob}}

{{copy}}

README helpers

{{authors}}

Travis CI

{{travis}}

{{travis-badge}}

{{changelog}}

HTML helpers

{{doctype}}

{{blockquote}}

{{timeline}}

{{exticon}}

{{ul}}

{{ol}}

{{br}}

String helpers

{{occurrences}}

{{hyphenate}}

{{dashify}}

{{lowercase}}

{{uppercase}}

{{capitalizeFirst}}

{{capitalizeEach}}

{{titleize}}

{{sentence}}

{{reverse}}

{{truncate}}

{{center}}

{{formatPhoneNumber}}

Collections helpers

{{first}}

{{withFirst}}

{{last}}

{{withLast}}

{{after}}

{{withAfter}}

{{before}}

{{withBefore}}

{{join}}

{{sort}}

{{withSort}}

{{length}}

{{lengthEqual}}

{{empty}}

{{any}}

{{inArray}}

{{eachIndex}}

{{eachProperty}}

Math helpers

{{add}}

{{subtract}}

{{divide}}

{{multiply}}

{{floor}}

{{ceil}}