Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
191 lines (150 sloc) 6.12 KB
---
title: Partials
area: docs
section: templates
categories:
- templates
tags:
- includes
- partials
logo:
URL: media/images/logo.png
classes:
- logo
- main
width: 80
height: 40
title: Assemble This!
hide-partial-YFM:
class: ""
---
> Like "includes", partials are reusable fragments of code that can be included in a page and rendered. Partials are useful when you have blocks of reusable code that are applicable in different contexts.
## Assemble, Mustache, Handlebars and Partials
Partials are a part of the [Mustache template language](http://mustache.github.io/) of which Handlebars is superset. More information about partials in general can be found in the [Mustache documentation](http://mustache.github.io/mustache.5.html). Assemble, when used with the [Handlebars](http://handlebarsjs.com/) engine, allows partials to be defined and used.
## An Example with Handlebars
Let us consider a simple partial as an example that would be used to generate an HTML `img` tag:
`img.hbs`
```html
<img src="\{{assets}}/images/\{{URL}}"
class="\{{#each classes}}\{{this}} \{{/each}}"
id="\{{#if id}}\{{id}}\{{else}}\{{slugify title}}\{{/if}}"
width="\{{width}}"
height="\{{height}}"
title="\{{title}}"
alt="\{{#if alt}}\{{alt}}\{{else}}\{{title}}\{{/if}}"/>
```
As you can see, Handlebars tags are used as placeholders for inserting various properties. For example, the `\{{URL}}` tag will insert a property `URL` from the current context.
Now that we have defined a partial, we can include the partial in a template via the standard Mustache syntax `\{{> [partial-name w/o extension]}}`. Using our `img.hbs` partial example above and the following HTML template:
`header.html`
```html
---
{{#logo}}
logo:
URL: {{URL}}
classes:
{{#classes}}
- {{.}}
{{/classes}}
width: {{width}}
height: {{height}}
title: {{title}}
{{/logo}}
---
<header class="root">
\{{#page.logo}}
\{{> img}}
\{{/page.logo}}
</header>
```
Assemble would produce the following output:
```html
<header class="root">
{{#logo}}
{{> img}}
{{/logo}}
</header>
```
Note that we enclosed our `\{{> img}}` partial invocation inside the `\{{#page.logo}} .. \{{/page.logo}}` section to setup the context in which the partial properties will be evaluated. In this case they are coming from the YAML front matter we defined in `header.html`, though the context can be set via the many methods supported by Assemble and Handlebars.
Handlebars provides a more convenient syntax for invoking a partial with a given context via `\{{> [partial-name] [context]}}`. Thus, we could change our `header.html` template as follows:
`header.html`
```html
---
{{#logo}}
logo:
URL: {{URL}}
classes:
{{#classes}}
- {{.}}
{{/classes}}
width: {{width}}
height: {{height}}
title: {{title}}
{{/logo}}
---
<header class="root">
\{{> img page.logo}}
</header>
```
and Assemble would produce the same output as above. With this syntax, the desired context in which to evaluate the partial is passed explicitly as a paramter to the partial.
## Configuration
To use partials in Assemble, we must specify where partials can be found in the configuration options for the `assemble` Grunt task:
`Gruntfile.js`
```js
assemble: {
options: {
// setup default partials locations
partials: ['templates/includes/**/*.{hbs,md}']
}
}
```
as well as within a collection's options:
`Gruntfile.js`
```js
assemble: {
my-collection: {
options: {
partials: ['my-collection/templates/partials/**/*.{hbs,md}']
}
}
}
```
## YAML Front Matter in Partials
Though partials can have YAML front matter, currently in Handlebars there is a [known issue](https://github.com/wycats/handlebars.js/pull/182) which causes the YAML front matter in a partial to be ignored if the partial is invoked within *any* context. Thus, the following updated `img.hbs` partial from above with YAML front matter:
`img.hbs`
```html
---
class: image
---
<img src="\{{assets}}/images/\{{URL}}"
class="\{{#each classes}}\{{this}} \{{/each}}\{{class}}"
id="\{{#if id}}\{{id}}\{{else}}\{{slugify title}}\{{/if}}"
width="\{{width}}"
height="\{{height}}"
title="\{{title}}"
alt="\{{#if alt}}\{{alt}}\{{else}}\{{title}}\{{/if}}"/>
```
would produce the same output as above, neglecting to add on the `\{{class}}` property as listed in the partial.
Fortunately Assemble provides two helpers which will merge the partial's YAML front matter into the context and give the expected results:
* [handlebars-helper-partial](https://github.com/helpers/handlebars-helper-partial)
* [handlebars-helper-include](https://github.com/helpers/handlebars-helper-include)
So taking our updated example partial, we could use the Assemble `partial` helper in the following way to be sure our partial's YAML front matter data is merged into the overall context when evaluated:
`header.html`
```html
<header class="root">
\{{partial 'img' page.logo}}
</header>
```
Note how when using the `\{{partial}}` helper we must put the name of the partial to include in quotes.
Finally, Assemble would produce the following output:
```html
<header class="root">
{{partial 'img' page.logo}}
</header>
```
with the partial's own YAML front matter included in the context, producing the extra `image` class attribute value.
## Partials in Handlebars Specifics
The `Handlebars.registerPartial` method, which registers a partial, accepts the name of the partial as its first argument and either a _template source string_ or a _compiled template_ as its second argument. Accepting a compiled template as the second argument enables you to, for example, use the partial in a loop that outputs a list but also append items to the list later using the partial's template function. For an example of this, check out the [handlebars-helpers-include](https://github.com/helpers/handlebars-helper-include/blob/master/index.js) code.
{{#draft}}
To use a partial from a template, simply include `\{{> partial-name }}`. For example:
{{/draft}}
#### Also see [options.partials][options-partials] →