Skip to content

Layouts

Jump to bottom
Timothy Kempf edited this page Oct 11, 2013 · 17 revisions

A layout is a Handlebars view that a page renders inside of. Layouts use the context of the page, and are generally used for things like headers, footers, or other elements that don't change from page to page.

======

Creating a Layout

To create a layout, simply create a new view in /views named layout.hbs. By default, pages will use the closest layout to them, first checking the folder that they're in, then the next folder up, and so forth. You can also specify a specific layout in a page's layout option, in which case the name of the layout file no longer matters.

One unique thing about layouts is that they require a {{{body}}} statement wherever you want the page markup to appear. Since they use the page's context, they also have no configuration options.

Here's a quick example (assume this is layout.hbs):

<!DOCTYPE html>
<html>
    <head>
        <title>{{page.title}} - Example Site</title>
    </head>
    <body id="page-{{page.name}}">
        <!-- Header -->
        {{> partials/header }}
        <!-- Body -->
        <main>{{{body}}}</main>
        <!-- Footer -->
        {{> partials/footer }}
    </body>
</html>

As you can see, the layout contains the markup that would be repeated across many pages. Inside the <main> tag you see the special {{{body}}} declaration, which is where the page's markup will go. In the <title> and <body> you can see data from the page's context in use. Finally, in this layout we've separated the header and footer out into their own partials to keep our markup clean.

======

Manually Specifying a Layout

In some cases you might want to give a page a special layout, or not use a layout at all. When that happens, you'll want to use the layout page configuration option. This option can be set to the path of a specific layout (relative to the /views directory), or to false to use no layout.

Say you've got a directory structure like this:

/views
├── index.hbs
├── layout.hbs
├── special_layout.hbs
└── special.hbs

If you want special.hbs to use special_layout.hbs, just specify that in its configuration:

{{!
{
    ...
    "layout": "special_layout.hbs"
    ...
}
}}

And finally, if you want your page to use no layout at all, just set layout to false, like so:

{{!
    ...
    "layout": false
    ...
}}

NEXT: Partials

======

Solidus is still under development. If you have comments or questions, please reach out to us in our IRC channel: #solidus on irc.freenode.net

======

Clone this wiki locally