Menu

Dust.js Cheat Sheet

A quick reference guide for the Dust.js syntax in your Adaptive.js views.

A. Overview

Dust.js is the default templating engine used by Adaptive.js. This document gives an overview of the templating language.

**Dust.js Read the official Dust.js documentation at http://www.dustjs.com/.

B. Referencing Keys from the View

To reference keys in the view, surround the key name in brackets like this: {key}.

For example, in the view file, select all of the content marked as an article:

'articles': function(context) {
    return $('.article');
}

Then inside the template file, refer to these view selections with the curly brace {articles} like this:

<div class="articles">
    {articles}
</div>

The combined effect of this code in the view and in the template files is the output of all of the elements on the page with the article class name.

a. Key Contexts

It is also possible to have multiple levels of keys. In this example, we create a header key with multiple keys inside of it.

'header': {
    'nav': function(context) {
        return $('#nav');
    },
    'logo': function(context) {
        return $('#logo');
    }
}

You can template this in two different ways. In the first example, you can use the dot notation to directly reference individual keys inside of header:

<div class="x-logo">
    {header.logo}
</div>

{header.nav}

Or, you can descend into the header context and reference keys with a shorter notation:

{#header}
    <div class="x-logo">
        {logo}
    </div>

    {nav}
{/header}

Either of these approaches yields the same final markup.

C. Conditionals: {?condition}

You can conditionally include markup on the page, depending whether a key exists or not.

For example, to select a logo in your view include the code:

'logo': function(context) {
    return $('#logo');
}

We can output different markup depending on whether the logo key exists.

{?logo}
    <section class="x-logo">
        {logo}
    </section>
{:else}
    <img src="logo.png" />
{/logo}

In this example, if the logo key exists on the page, we output the selection from the view. Otherwise, we show the static logo.png image.

Else Block In these conditional structures, the else block is optional.

D. Negative Conditionals: {^condition}

Achieve the same effect of conditional markup on a page with a negative conditional.

Let's use the example in the Conditionals section with the logo key:

{^logo}
    <img src="logo.png" />
{:else}
    <section class="x-logo">
        {logo}
    </section>
{/logo}

Similarly, the else block is still optional.

E. Loops: {#condition}

To select a set of elements in the view, iterate over them in the template.

For example, if there is the following block of HTML in the desktop site version:

<div id="carousel">
    <div class="carousel-container">
        <img src="image1.jpg" />
        <img src="image2.jpg" />
        <img src="image3.jpg" />
        <img src="image4.jpg" />
        <img src="image5.jpg" />
    </div>
</div>

In the Adaptive.js view file, select on the images with the JavaScript the code snippet:

'slides': function(context) {
    return $('#carousel img');
}

Then in the template file, iterate over the images with code like:

<ul class="carousel">
    {#slides}
        <li>{.}</li>
    {/slides}
</ul>

The {.} notation refers to the current element. It iterates through each element in the slides conditional and prints out each image inside a new <li> list item tag.

In the output file, the HTML is:

<ul class="carousel">
    <li><img src="image1.jpg" /></li>
    <li><img src="image2.jpg" /></li>
    <li><img src="image3.jpg" /></li>
    <li><img src="image4.jpg" /></li>
    <li><img src="image5.jpg" /></li>
</ul>

F. Partials: {>partial/}

You can include partial templates in your template. This is useful when a piece of markup needs to be used on multiple templates.

For example, let's use the following code in the template to look for the _cartItems.dust partial:

<h1>Cart</h1>

{>_cartItems/}

The contents of the partial are:

<ul>
    <li>Bananas ($1.99)</li>
    <li>Oranges ($2.29)</li>
    <li>Strawberries ($3.99)</li>
</ul>

Now the output HTML becomes:

<h1>Cart</h1>

<ul>
    <li>Bananas ($1.99)</li>
    <li>Oranges ($2.29)</li>
    <li>Strawberries ($3.99)</li>
</ul>

Best Practice

As a best practice, prefix the partial template file names with an '_' underscore character.

G. Blocks: {+partial}

Create named blocks in your templates with the option to override them later.

Pre-define several blocks in the common base template, and then override certain blocks as necessary.

In this example, the base base.dust template has a default header:

<header>
    {+header}
        <h1>Default Header</h1>
    {/header}
</header>

This code defines the header section. You can override the contents of this section now.

H. Block Overrides: {<override}

Assuming the same base template in the previous example, we can override the default header block in a child template like this:

{>"global/base"/}

{<header}
    <h1>Home</h1>
{/header}

In this example, we inherit the base.dust template and then override itsheader block.

The final HTML will look like this:

<header>
    <h1>Home</h1>
</header>

I. Extending Blocks with {_SUPER_}

To extend a block rather than to completely override it, use the {_SUPER_} form.

Let us say that we have a base base.dust template with the block:

{+scripts}
    {trackingScripts}
{/scripts}

Here, we define a block called scripts and we populate it with a key called trackingScripts.

On another given template, we can add a new script in addition to the tracking scripts with the {_SUPER_} code.

{>"global/base"/}

{<scripts}
    {_SUPER_}
    <script>
         ...
    </script>
{/scripts}

The {_SUPER_} block refers to all of the content of the {trackingScripts} block. Then a new script is added to the page after the tracking scripts.

The final HTML looks like this:

<!-- tracking scripts -->
<script href="analytics.js"></script>

<!-- new script -->
<script>
    ...
</script>

J. Path Resolution {@getUrl}

Adaptive.js provides a Dust.js helper for resolving paths to assets. The helper takes three arguments:

Argument Name Argument Description
path The relative path to the asset
baseUrl (optional) The origin part of the assets url.
cacheBreaker (optional) A string, tacked onto the end of the URL as a querystring parameter to force caches to fetch a new version of the asset.

If you don't specify the baseUrl argument, or the cacheBreaker argument, the helper automatically fills in the proper values.

For example, use the following code in the view file:

<link href="{@getUrl path="/css/stylesheet.css" /}"
rel="stylesheet" type="text/css" />

This compiles to the following in the final output HTML:

<link href="http://localhost:8080/css/stylesheet.css?a1s2d3f4"
rel="stylesheet" type="text/css" />

K. Base Template: base.dust

The base.dust template file is the basis for all other template files on your site.

At the top of most of the template files, the template inherits from the base template:

{>"global/base"/}

{<contentBlock}
    ...
{/contentBlock}

The code snippet above includes all the code from the base.dust base template and then overrides the contentBlock block with your own template-specific content.

Edit in GitHub