assemble-helpers

assemble-helpers

Plugin that adds helpers for assemble projects. Includes both sync and async helpers that take advantage of assemble's powerful features.

Install

Install with npm:

$ npm install --save assemble-helpers

Usage

var assembleHelpers = require('assemble-helpers');
var assemble = require('assemble');
var app = assemble();

app.use(assembleHelpers());

Helpers

{{content}}

Returns the stringified contents from a view object, or just returns the value if view is a string.

Params

• view {String|Object}
• returns {String}: Returns view.contents or the value if it's a string.

Example

app.view('foo', {contents: 'This is contents'});

// {{contents foo}}
//=> "This is contents"

{{find}}

Get the first view with the given name from any collection, or the specified collection. If no collection is passed only renderable collections will be searched ("renderable" collections are any collections not specified as partials and layouts).

Params

• name {String}: The name/key (view.stem, view.basename, view.relative or view.path) of the view to find. It's good practice to use a longer path when practical.
• collection {String}: (optional)
• returns {Object|undefined}: Returns the view if found, or undefined if not.

Example

{{find "foo"}}
{{find "foo.hbs" }}
{{find "a/b/c/foo.hbs"}}

<!-- optionally specify a collection -->
{{find "foo" "pages"}}
{{find "foo.hbs" "posts"}}
{{find "a/b/c/foo.hbs" "partials"}}

{{getView}}

Get a view from the specified collection.

Params

• collection {String}: (required)
• name {String}
• returns {Object}

Example

{{getView "pages" "foo"}}
{{getView "pages" "foo.hbs" }}
{{getView "pages" "a/b/c/foo.hbs"}}

{{config}}

Get the value of prop from app.options or the context. Dot-notation may be used. Context values from app.cache.data will override values from app.options, and values from locals will override all other values.

Params

• prop {String}
• locals {Object}: (optional) Locals to merge onto the options.
• returns {any}

Example

app.option({a: {b: 'c'}, x: 'z'});
app.data({a: {b: 'd'}});
app.data({foo: {a: {b: 'ABC'}}});

// {{config "x"}}     => 'z'
// {{config "a.b.c"}} => 'eee'
// {{config "a.b"}}   => '{c: 'eee'}'

// with locals
// {{config foo "a.b.c"}} => 'ABC'
// {{config foo "a.b"}}   => '{c: 'ABC'}'

{{option}}

Return the value of prop from app.options.

Params

• prop {String}
• returns {any}

Example

app.option({a: {b: 'c'}});

// {{option "a"}}   => '{b: 'c'}'
// {{option "a.b"}} => 'c'

{{enabled}}

Return true if the value of prop on app.options is strictly `true.

Params

• prop {String}
• returns {Boolean}

Example

app.option('foo', false);
app.option('bar', true);
app.enable('baz'); //<= convenience method for setting an option to true

// {{enabled "foo"}} => false
// {{enabled "bar"}} => true
// {{enabled "baz"}} => true

{{disabled}}

Return the given value of prop from this.options.

Params

• prop {String}
• returns {any}

Example

app.option('foo', false);
app.option('bar', true);
app.disable('baz'); //<= convenience method for setting an option to false

// {{disabled "foo"}} => true
// {{disabled "bar"}} => false
// {{disabled "baz"}} => false

{{matchView}}

Returns a function for matching a view in subexpressions. The returned function takes a

Params

• prop {String}
• returns {any}

Example

{{#eachItems "posts" filter=(matchView "!index")}}
  {{stem}}
{{/eachItems}}

{{items}}

Returns an array of items from the views in collection name.

Params

• name {String|Object|Array}: Collection name, or collection/list instance, or array of list items.
• options {Object}
• returns {Array}

Example

{{#items "posts"}}
  {{#each .}}
    <!-- using the "titleize" helper from handlebars-helpers -->
    {{titleize data.title}}
  {{/each}}
{{/items}}

{{eachItems}}

Block helper that iterates over the items in collection name and exposes each item in the collection as "this" inside the block.

Hash options:

• sortBy: function or property path to sort the collection by. Dot-notation may be used for getting nested properties.
• filter: function, glob pattern, or filepath for filtering items in the collection.

Params

• name {String}: (required) Collection name
• locals {Object}: (optional)
• options {Object}: Handlebars options
• returns {Array}

Example

// built-in "pages" collection
app.pages('templates/pages/*.hbs');
// {{#eachItems "pages" filter="!index"}}
//   {{log stem}}
// {{/eachItems}}

// custom "posts" collection
app.create('posts'); //<= create the collection first
app.posts('templates/posts/*.hbs');
// {{#eachItems "posts" sortBy="data.date"}}
//   {{log stem}}
// {{/eachItems}}

{{sortItems}}

Sort and filter the items in a collection to match the order of an array of strings. Given you have three pages, aaa.hbs, bbb.hbs, and ccc.hbs, the following will sort the items in the order specified in front-matter:

Params

• items {Array}: (required) Array of items from a collection
• locals {Object}: (optional)
• options {Object}: Handlebars options
• returns {Array}

Example

---
order: ['bbb', 'ccc', 'aaa']
---
<!-- use the "items" helper to get "pages" -->
{{#each (sortItems (items "pages") order) as |item|}}
  {{item.basename}}
{{/each}}

<!-- or, use the built-in "pages" helper to expose "items" -->
{{#pages}}
  {{#each (sortItems items order) as |item|}}
    {{item.basename}}
  {{/each}}
{{/pages}}

{{link-to}}

Returns a relative path from the view being rendered to destination path of the specified view.

Params

• path {String}
• collection {String}: (optional) Collection name
• lookups {Array}: (optional) Array of property paths to use for resolving views.
• returns {String}: Relative path to the specified view.

Example

<!-- link to "index" (resolves the first view with "index" in the path) -->
{{link-to "index"}}
<!-- link to "index" -->
{{link-to "index" "posts"}}

{{render}}

Render the given view.

Params

• view {Object|String}: View object or the name of the view to render.
• returns {String}

Example

{{render "foo.hbs"}}

{{assets}}

Returns the relative path to the assets directory defined on app.options or the context. Alias for the asset helper, to provide a semantic alternative depending on usage.

Params

• filepath {String}: (optional) Filepath to append to the assets path.
• returns {String}

Example

<link rel="stylesheet" href="{{assets 'css/styles.css'}}">
<link rel="stylesheet" href="{{assets}}/css/styles.css">

{{asset}}

Returns the relative path to filename from the assets directory defined on app.options or the context. Alias for the assets helper, to provide a semantic alternative depending on usage.

Params

• filepath {String}: (optional) Filepath to append to the asset path.
• returns {String}

Example

<link rel="stylesheet" href="{{asset 'css/styles.css'}}">
<link rel="stylesheet" href="{{asset}}/css/styles.css">

{{root}}

Returns the relative path to filename from either the root or dest directory defined on app.options or the context.

Params

• filepath {String}: (optional) Filepath to append to the root path.
• returns {String}

Example

<a href="{{root 'sitemap.xml'}}"></a>
<a href="{{root}}/sitemap.xml"></a>

About

Related projects

• handlebars-helpers: More than 130 Handlebars helpers in ~20 categories. Helpers can be used with Assemble, Generate… more | homepage
• helper-link-to: Templates helper that returns a link path from the current view to the another view. | homepage
• template-helpers: Generic JavaScript helpers that can be used with any template engine. Handlebars, Lo-Dash, Underscore, or… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.4.2, on February 24, 2017.