src/index.js

Build Status

Templates are markup (html, ejs, etc) that Nxus modules can use to render a UX. The Templater module provides a common API for defining and accessing templates. Specifically, you can use partials and templates defined by other modules, meaning you write less code for common components.

Installation

> npm install @nxus/templater --save

Parsers

Templater supports EJS and HTML as default template types. If you'd like to add in additional parsers, check out the @nxus/renderer documentation.

Namespacing

All templates share a single namespace, so its a good idea to add a prefix to your template names to avoid conflicts. For example mymodule-mytemplate.

Usage

Register a Template

If you would like to register a single template, you can use the template provider and specify a file:

app.get('templater').template('default', 'ejs', 'path/to/some/file')

You can also pass in a handler method instead of a file path. Templater expects that this handler returns a string with the template content, or a Promise that resolves to a string. The handler will be passed in the name of the template requested, as well as any render options specified.

var handler = function(name, args) {
  return ".....";
}
app.get('templater').template('default', 'ejs', handler)

Registering a Template Directory

Alternatively, you can register a directory. Templater will define a new template for every file in the directory with the specified type extension.

app.get('templater').templateDir('ejs', 'path/to/some/dir')

For example, given the following directory structure:

- /templates
  |- my-template.ejs

Templater will expose my-template as a new template.

Alternatively, you can supply a third argument that will be used to namespace the templates.

app.get('templater').templateDir('ejs', 'path/to/some/dir', 'custom')

For example, given the following directory structure:

- /templates
  |- my-template.ejs

Templater will expose custom-my-template as a new template.

Render content using a Template

let opts = {content: "some content"}

app.get('templater').render('default', opts).then((content) => {
  console.log('rendered content', content)
})

Render a partial using a Template

If you've defined a partial you would like wrapped in another template, use the renderPartial request and specify a template in which the partial will be wrapped.

app.get('templater').renderPartial('path/to/my/partial', 'wrapper-template', opts).then((content) => {
  console.log('rendered partial content', content)l
})

Alternatively, you can specify a previously defined template as your partial:

app.get('templater').renderPartial('partial-template', 'wrapper-template', opts).then((content) => {
  console.log('rendered partial content', content)l
})

API


Templater

src/index.js

Templater provides a template layer, built on top of the Nxus Renderer

Instance members

#render(name, [args])

Renders a template

render(name, [args])

src/index.js

Renders a template

Parameters

  • string name :

    The name of the registered template to render

  • Object = (default {}) args :

    The arguments to pass to the template

Returns

Promise :

A promise for the rendered content

#renderPartial(partial, filePath, baseName, [args])

Renders the specified template as a partial, rendering the content in a parent template.

renderPartial(partial, filePath, baseName, [args])

src/index.js

Renders the specified template as a partial, rendering the content in a parent template.

Parameters

  • string partial :

    Either a template name or a path to a partial file

  • filePath :
  • string baseName :

    The parent template to use to render the partial

  • Object = (default {}) args :

    The arguments to pass to the partial and the template for rendering

Returns

Promise :

A promise for the rendered content.

#template(name, type, handler)

Define a new template

template(name, type, handler)

src/index.js

Define a new template

Parameters

  • string name :

    A name for the template

  • string type :

    Templating engine used with the template. Should map to an installed @nxus/renderer type.

  • ( string | function ) handler :

    Either a filepath or a callback function which returns a promise that resolves to rendered content.

#templateDir(type, dir, [namespace])

Convenience function to crawl a directory and register all matching files as a template.

templateDir(type, dir, [namespace])

src/index.js

Convenience function to crawl a directory and register all matching files as a template.

Parameters

  • string type :

    File extension of files to import as templates

  • string dir :

    The directory to crawl

  • String = (default "") namespace :

    An optional namespace to append to the front of the template name