Overview

Dust.js is the templating engine used by Mobify Design Suite. Selections made in the konf can be written out to the page via the template file. The following document gives an overview of the templating language.

Official Dust.js documentation


Referencing Keys in the Konf

You can reference keys in the konf by surrounding the key name in brackets like this: {key}

For example, you can make selections in the konf:

KONF:

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

Then, refer to those konf selections in the template:

TEMPLATE:

{articles}

This will output all the elements on the page with the class name article

Key Contexts

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

KONF:

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

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

TEMPLATE:

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

{header.nav}

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

TEMPLATE:

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

    {nav}
{/header}

Either of these approaches will yield the same final markup.


Conditionals: {?condition}

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

For example:

KONF:

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

We can output different markup depending if logo exists or not.

TEMPLATE:

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

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

Note: The else block is optional.


Negative Conditionals: {^condition}

You can achieve the same effect using a negative conditional.

Using the same example as above:

TEMPLATE:

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

Similarly, the else block is still optional.


Loops: {#condition}

When selecting a set of elements in the konf, we can iterate over them in the template.

DESKTOP HTML:

<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>

You can select on the images in the konf:

KONF:

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

Then, we can iterate over them in the konf:

TEMPLATE:

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

The {.} notation refers to the current element. This will iterate through each element in slides and print out each image in a new <li>

OUTPUT HTML:

<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>

Partials: {>partial/}

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

TEMPLATE:

<h1>Cart</h1>

{>_cartItems/}

<a href="javascript:history.go(-1);">Back</a>

This piece of code will look for _cartItems.tmpl and insert it in place.

OUTPUT HTML:

<h1>Cart</h1>

<ul>
    <li>Bananas ($1.99)</li>
    <li>...</li>
</ul>

<a href="javascript:history.go(-1);">Back</a>

Blocks: {+partial}

You can create named blocks in your templates which can be overridden. We pre-define several blocks in the common root template, and we override certain blocks as necessary.

In this example, the root template has a default header:

ROOT TEMPLATE (root.tmpl):

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

We have defined a section named header which can now be overridden.


Block Overrides: {<override}

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

PAGE TEMPLATE (home.tmpl):

{>root/}

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

In this example, we are inheriting root.tmpl, then overriding its header block.

The final HTML will look like this:

OUTPUT HTML:

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

Extending Blocks with {_SUPER_}

If we want to extend a block rather than completely overriding it, we can use {_SUPER_}:

Let's say we have a root template with this block:

ROOT TEMPLATE (root.tmpl):

{+scripts}
    {trackingScripts}
{/scripts}

Here, we are defining a block called scripts and, by default, populating it with a key called trackingScripts

On a given template, we might want to add a new script, in addition to the tracking scripts. We can do that using {_SUPER_}

PAGE TEMPLATE (product.tmpl):

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

{_SUPER_} refers to all of the content of {trackingScripts}, and then a new script is added to the page, after the tracking scripts.

The final HTML will look like this:

OUTPUT HTML:

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

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

Root Template: root.tmpl

There is one template file that is the basis for all other template files on your site: root.tmpl

You'll notice that at the top of most page template files, we inherit from the root template:

PAGE TEMPLATE (eg. home.tmpl)

{<root/}

{<main}
    ...
{/main}

What happens here is we include all the code from root.tmpl, then override the main block with our own template-specific content.

Template Class: .x-<templateName>

The main part of the root template body is #x-root. Its main feature is that it has the class name which is related to the current page template.

For example, if you are on the home template, then #x-root will have the class x-home:

OUTPUT HTML:

<section id="x-root" class="x-home">
    ...
</section>

This class is great for namespacing your CSS styles.

Last Edited