template-language.md

Template Language

NHP templates are HTML files with a .nhp extension. Expressions use moustache delimiters; control statements use XML-style processing instructions.

Expressions

Use JavaScript expressions inside moustaches:

<h1>{{title}}</h1>
<p>{{user.name || "Guest"}}</p>

Normal moustaches escape <, >, and attribute quotes:

<a title="{{title}}">{{title}}</a>

Use triple moustaches only for trusted HTML that should be written without escaping:

<section>{{{trustedHtml}}}</section>

The object passed to render() supplies expression variables. env is a persistent per-render object used by stateful directives.

State directives

set stores an expression result in env:

<?set heading "News"?>
<h1>{{env.heading}}</h1>

add appends a value to an array, creating it when needed:

<?add tags "node"?>
<?add tags "templates"?>
{{env.tags.join(", ")}}

map stores a value under a key, creating an object when needed:

<?map metadata "author" "NexusTools"?>
{{env.metadata.author}}

json writes an expression as JSON:

<script type="application/json"><?json data?></script>

exec runs trusted JavaScript directly. It can write output using __out.write():

<?exec __out.write("<!-- generated -->")?>

Conditions

Use if, elseif, else, and endif for conditional output:

<?if user.admin?>
  <p>Administrator</p>
<?elseif user?>
  <p>Signed in</p>
<?else?>
  <p>Guest</p>
<?endif?>

Each condition is a JavaScript expression. Use env.name for values created with set, add, or map.

Iteration

each iterates arrays and objects asynchronously in series. Close every loop with done:

<ul>
<?each entries?>
  <li>{{entry}}</li>
<?done?>
</ul>

When iterating an object, entry has key and value properties:

<?each env.metadata?>
  <dt>{{entry.key}}</dt><dd>{{entry.value}}</dd>
<?done?>

Includes

include renders another template relative to the current template's directory:

<?include "partials/header"?>
<main>{{content}}</main>
<?include "partials/footer"?>

The .nhp extension is optional. Included templates share the same render locals and env object.

Resolvers

A resolver is an asynchronous named value provider. In a template, reference one with {{#name}}:

<p>{{#currentUser}}</p>

Register the resolver before rendering. Its callback uses the Node.js error-first convention:

nhp.installResolver("currentUser", (callback) => {
    loadUser((error, user) => callback(error, user && user.name));
});

Resolver values are escaped like normal moustache output. A resolver error is rendered as an NHP error block and rendering continues.

Translation

Plain text that contains letters is passed to the render-local __ function. Supply __ to translate template text:

nhp.render("page.nhp", {
    __(text) {
        return translations[text] || text;
    }
}, callback);

When no __ function is supplied, text is returned unchanged.