api.md

API Reference

const NHP = require("nhp");

new NHP(constants?, options?)

Creates an NHP renderer. constants are copied into every render context. options configures output handling.

const nhp = new NHP(
    { siteName: "Example" },
    { tidyOutput: true }
);

Options

Option	Default	Meaning
tidyOutput	true	Parse and normalize rendered HTML output.
tidyAttribs	['false', 'null', 'undefined']	Attribute values omitted during output tidying.
tidyComments	'not-if'	Removes ordinary comments while retaining conditional comments.

Set tidyOutput: false when the destination should receive the raw output written by the template.

Rendering

nhp.render(filename, locals, callback)

Compiles, caches, and renders a template. The callback receives (error, html).

nhp.render("views/page.nhp", { title: "Docs" }, (error, html) => {
    if (error)
        return handleError(error);
    response.send(html);
});

nhp.renderToStream(filename, locals, stream, callback)

Renders to a writable stream and closes it when rendering completes.

nhp.renderToStream("views/page.nhp", locals, response, (error) => {
    if (error)
        response.destroy(error);
});

nhp.template(filename, mutable?)

Returns a cached Template. NHP appends .nhp when the filename has no extension. Templates are mutable by default and watch their source file for changes. Pass false for one-shot or build-time rendering:

const template = nhp.template("views/page", false);
template.render({ title: "Static" }, callback);

nhp.genSource(filename, callback)

Compiles a template and returns its generated JavaScript source with (error, source).

nhp.__express()

Returns a function compatible with Express's view-engine signature.

Constants

Method	Description
setConstant(name, value)	Adds a constant. Throws when the name already exists.
constant(name)	Gets a constant value.
hasConstant(name)	Tests whether a constant is set.
deleteConstant(name)	Deletes a constant and returns whether it was deleted.
assignConstants(values)	Merges values into the constant context.

Extensions

Resolvers

installResolver(name, resolver) registers an asynchronous provider for {{#name}}. The resolver receives an error-first callback:

nhp.installResolver("buildId", (callback) => {
    callback(undefined, process.env.BUILD_ID);
});

Processors

installProcessor(name, processor) registers a processing-instruction factory. A processor receives the source text inside <?name ...?> and returns an instruction. The built-in instruction constructors are exposed as NHP.Instructions for advanced extensions.

nhp.installProcessor("notice", (text) => {
    return new NHP.Instructions.Custom(() => {
        return "__out.write(" + JSON.stringify(text) + ");";
    });
});

Use processingInstruction(name, data) to create an instruction through the currently registered processor map. It throws for an unknown name.

Lifecycle

destroy() closes file watchers for every cached template. Call it when a short-lived process has finished rendering or when an application shuts down:

process.on("SIGTERM", () => {
    nhp.destroy();
    process.exit(0);
});