Layouts

Most templates share a lot of code, particularly headers, footers, sidebars, etc. These are things that generally don't change from one page to another. By using a layout, you can reduce duplicate code and make your templates much easier to read.

Layouts can be a difficult concept to understand at first, so let's learn from an example. Consider the following template.

<!DOCTYPE html>
<html lang="en">
<head>
<title>{meta.title}</title>
<meta name="description" content="{meta.description}">
<meta charset="UTF-8">
<link rel="stylesheet" href="path/to/stylesheet.css">
</head>

<body>
<main>
{+body/}
</main>

<script src="path/to/script.js"></script>
</body>
</html>

This is a fairly minimal example. A real website will have more metadata, more scripts, and a more complex structure. The amount of code can grow rather quickly.

Since most of this code will remain the same from one template to another, it doesn't make much sense to copy and paste it into every single template. That would be very tedious and it would make updating your templates more difficult.

Instead, let's create a layout file called default.dust and put the code in there. The filename doesn't really matter, but it's a good practice to use default.dust for your default layout.

Blocks

Now that you've created a layout file called default.dust, the next step is to incorporate it into each of your templates. In the example above, you may have noticed a strange tag called {+body/}. This is called a block.

A block is a named chunk of code surrounded by {+blockName} and {/blockName}. It can contain default content, or it can be empty as in the example above. When empty, the syntax for a block can be reduced to {+blockName/}.

You can have any number of blocks in your layout, but for the sake of simplicity, we'll continue with just one.

Using Layouts

To use the layout file you created, simply include it at the top of each template like a partial. Then override the {+body/} block with the custom content for that template.

{! Use the default layout !}
{>"default"/}

{! This is the body of the page. It will get rendered
where the {+body/} block appears in the layout. !}
{<body}
<p>Your custom content here</p>
{/body}

The {<body} syntax tells Dust.js to override the block named body that you defined in your layout. Note the required {/body} closing tag.

When your template is rendered, the resulting HTML will look like this:

<!DOCTYPE html>
<html lang="en">
<head>
<title>Meta Title</title>
<meta name="description" content="Meta Description">
<meta charset="UTF-8">
<link rel="stylesheet" href="path/to/stylesheet.css">
</head>

<body>
<main>
<p>Your custom content here</p>
</main>

<script src="path/to/script.js"></script>
</body>
</html>

Notice how the body of the template has been combined with the layout. This is a great way to maintain a layout while keeping templates lean.

To learn more about blocks in Dust.js, refer to the Blocks and Inline Partials guide on the Dust.js website.

For a real life example of a layout file, check out the default theme's templates folder.