In the Getting Started guide, you learned how to write Dust templates. Now, let’s look at how to use your templates to render pages.

Compile, Load, and Render

Warning: Compiling a template is much slower than rendering it, so when it’s time to deploy to production, you should precompile your templates as part of your build process.

We’ll look at how to compile, load, and render templates in several different ways.

Browser: Basic

Warning: Although compiling directly in the browser can be useful during development, you should not do it on your live site or pages will render slowly.

In addition, access to the functions dust.compile and dust.renderSource in the browser requires that you include dust-full.js, which is larger than dust-core.js.

<script type="text/dust" id="hello">Hello {world}!</script>
<script type="text/javascript">
var src = document.getElementById('hello').textContent;
// Compile the template under the name 'hello'
var compiled = dust.compile(src, 'hello');
// Register the template with Dust
dust.loadSource(compiled);
// Render the template
dust.render('hello', { world: "Earth" }, function(err, out) {
  // `out` contains the rendered output.
  document.getElementById('output').textContent = out;
});
</script>

As a shortcut, you can use dust.renderSource:

// compiles, loads, and renders
dust.renderSource(src, { world: "Alpha Centauri" }, function(err, out) { ... });

As of Dust 2.7.0, a template name is optional when compiling a template. dust.loadSource will return a template function that you can pass directly to dust.render.

var compiled = dust.compile(src);
var tmpl = dust.loadSource(compiled);
dust.render(tmpl, { world: "Betelgeuse" }, function(err, out) { ... });

Browser: Precompiled Templates

<!-- precompiled templates -->
<script type="text/javascript" src="/lib/templates.js"></script>
<script type="text/javascript">
// The templates are already registered, so we are ready to render!
dust.render('hello', { world: "Saturn" }, function(err, out) {
  document.getElementById('output').textContent = out;
})
</script>

Browser: AMD (Require.js)

First, read the guide on loading Dust as an AMD module. You must have Dust version 2.6.0 or higher.

You can compile your templates as AMD modules by setting dust.config.amd to true. The easiest way to create AMD templates is by using dustc with the --amd flag. (To learn how to use dustc, see the dustc docs.)

If a template is not included via require, Dust will attempt to load it by passing the template’s name to require. To make use of this feature, templates should be compiled with names that an AMD loader would expect. For example, a template located at tmpl/home/main.js must be named tmpl/home/main for Dust to load it correctly. If you use the dustc compiler this is handled for you.

<script src="r.js"></script>
<script type="text/javascript">
    define.amd.dust = true;
    require(["lib/dust-core"], function(dust) {
      dust.render('tmpl/hello', { world: "Jupiter" }, function(err, out) {
        // dust will call `require(['tmpl/hello'])` since that template isn't loaded yet
      });
    });
</script>

You can preload templates by calling require yourself. As of Dust 2.7.0, you can pass the template object directly to dust.render instead of a template name.

require(["lib/dust-core", "tmpl/hello"], function(dust, helloTemplate) {
  // Dust >= 2.6.0
  dust.render('tmpl/hello', { world: "Mars" }, function(err, out) { ... });
  // Dust >= 2.7.0
  dust.render(helloTemplate, { world: "Pluto" }, function(err, out) { ... });
})

Node: Basic

Warning: Although compiling directly on the server can be useful during development, you should not do it on your live site or pages will render slowly.

var src = fs.readFileSync('/views/hello.dust', 'utf8');
var compiled = dust.compile(src, 'hello');
dust.loadSource(compiled);
dust.render('hello', { world: "Venus" }, function(err, out) {
  // `out` contains the rendered output.
  console.log(out);
});

Node: Load Precompiled Templates

// Pre-2.7
fs.readFile(templateName + '.js', { encoding: 'utf8' }, function(err, data) {
  dust.loadSource(data);
  dust.render(templateName, {}, function(err, out) {
    console.log(out);
  });
});

// Precompile as CommonJS modules-- as of Dust 2.7
app.get('/hello', function(req, res) {
  var tmpl = require('./views/hello.js')(dust);
  tmpl({world: 'Neptune'}, function(err, out) {
    res.send(out);
  });
});

Node: Dynamically Load Templates

For a production application with more than a few templates, it’s best to tell Dust how to load templates rather than loading them all manually. To do this, you must configure a dust.onLoad function.

Disable Caching

Once Dust has registered a template, it won’t try to load it again. This is great for performance, but makes it hard to make changes to a template and reload to see them.

As of Dust 2.7.0, you can set dust.config.cache to false to disable the cache in development, so Dust will try to reload the template every time.

Dust and Express.js

Many developers want to use Dust to render pages from their Node server using Express. There are several Express rendering engines for Dust that handle template loading, compiling, and caching for you. Among them are:

Precompiling Templates

If you’re not using an Express view engine, the best way to use Dust is to compile templates as part of your build process. Some of the most common ways to accomplish this are:

Fork me on GitHub