## Usage

Register the helper with [assemble][]:

```js
var assemble = require('assemble');
var app = assemble();

app.helper('collection', require('{%= name %}'));
```

**Add some templates**

```js
// add some "pages" ("pages" is a built-in collection)
app.page('foo.hbs', {content: 'this is foo', data: {title: 'Foo'}});
app.page('bar.hbs', {content: 'this is bar', data: {title: 'Bar'}});
app.page('baz.hbs', {content: 'this is baz', data: {title: 'Baz'}});


// add some "posts" ("posts" is not built-in, 
// so we need to create it first)
app.create('posts'); //<= that's it :)

// now we can add some posts
app.post('aaa.hbs', {content: 'this is aaa', data: {title: 'AAA'}});
app.post('bbb.hbs', {content: 'this is bbb', data: {title: 'BBB'}});
app.post('ccc.hbs', {content: 'this is ccc', data: {title: 'CCC'}});
```

### Usage inside templates

By default, the `collection` helper will get the name of the current collection being rendered. With [assemble][], this would most likely be "pages".

```handlebars
<ul>
{{#collection}}
  <!-- the collection's views (pages in this case) are 
  exposed as "items" inside the block -->
  {{#each items as |item|}}
  <li>{{item.data.title}}</li>
  {{/each}}
{{/collection}}
</ul>
```

**Specify a collection**

Or specify the collection to iterate over:

```handlebars
<ul>
{{#collection "posts"}}
  <!-- posts are "items" -->
  {{#each items as |item|}}
  <li>{{item.data.title}}</li>
  {{/each}}
{{/collection}}
</ul>
```

**Sort items**

Or specify the collection to iterate over:

```handlebars
<ul>
{{#collection}}
{{#each (sortBy items "data.title") as |item|}}
  <li>{{item.data.title}}</li>
{{/each}}
{{/collection}}
</ul>
```

**Dynamic selection**

Dynamically specify the collection to iterate over from the assemble config or front-matter (this is the real advantage of this helper over assemble's built-in helpers, since dynamically naming the collection allows you to define this logic in a partial somewhere, then use it for several collections - like "docs", "posts", and "pages").

In this example, `someCollectionName` represents a custom variable that you might define somewhere on the context, like front-matter.

```handlebars
<ul>
{{#collection someCollectionName}}
{{#each items as |item|}}
  <li>{{item.data.title}}</li>
{{/each}}
{{/collection}}
</ul>
```