npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

nxus-templater

v4.1.1

Published

The template manager for Nxus applications

Downloads

13

Readme

nxus-templater

Templater Module

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

Usage

import {templater} from 'nxus-templater'

Register a Template

There are three types of templates you can register.

Template File

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

templater.template('path/to/some/file.ejs')

Based on the filename, the template will be given the name file and rendered using the EJS renderer.

Optionally, you can specify another template to wrap the output (for partial style templates).

templater.template('path/to/some/file.ejs', 'page')
Template Directory

Alternatively, if you have a folder with all your templates, you can add them all using templateDir.

For example, given the following directory structure:

- /templates
  |- my-template.ejs

Templater will expose my-template as a new template.

 templater.templateDir('path/to/some/dir/')

Each template will be processed using the template function above. You can also specify a layout that the template will be wrapped in.

 templater.templateDir('path/to/some/dir/', 'page')

Alt you can specify a glob pattern to only register certain files:

 templater.templateDir('path/to/some/dir/myname-*.ejs', 'page')
Function

You can also pass in a handler method instead of a file path. Templater expects that this handler returns a string with the rendered 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(args, name) {
  return "<html>.....";
}
templater.templateFunction('default', handler)

Render content using a Template

let opts = {content: "some content"}

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

Override the template layout

If you want to specify a different layout template than was originally set, you can add a template key to the opts object.

opts.template = 'new-template'
templater.render('partial-template', opts).then((content) => {
  console.log('rendered complete content', content)l
})

Render a partial from within a template

In place of EJS' include function for rendering sub-templates, you can use the render function to use a templater-registered template name within a template:

<%- render('app-nav`) %>

or with specific options

<%- render('app-nav', navItems) %>

Provide additional context opts for rendering (scripts, etc)

Modules can provide additional context options to be available to templates. :

templater.on('renderContext', () => {return {username: 'Steve'}})

The event handler is passed the original template name and args, so if req or other is provided it is available to you, or if you want to only provide context for some templates, but you do not need to return the whole modified args:

templater.on('renderContext', (args, name) => {return {username: args.req ? args.req.user : '' }})

Templater will also fire a template specific event

templater.on('renderContext.my-template', () => {return {username: 'Steve'}}) 

Values that are arrays are concated rather than overwritten, so that for instance scripts can collect script URLs from many modules:

templater.on('renderContext', () => {return {scripts: ['/url/script.js']}})
templater.on('renderContext', () => {return {scripts: ['/url/other.js']}})

Will result in scripts containing an array with both these values. The list will be filtered to only have unique values, so you can specify scripts in dependency order and not worry if other modules are asking for the same common js files repeatedly. The default set of templates provided by this module include rendering of this scripts variable already.

Templater API


Templater

Extends NxusModule

Templater provides template registering and rendering, built on top of the renderer

Parameters

  • app

template

Registers the specified template. By default, the template name will match the file name, and the renderer used will be determined by the file extension. For example: ./templates/my-template.ejs will be registered as my-template using the EJS rendering engine.

Parameters

  • filename String the path of the template file to register.
  • layout String Optionally, the name of another template to use as a layout
  • name String Optional. Specify a different name to use to register the template file. (optional, default null)

templateDir

Registers all templates in the specified directory.

Parameters

  • dirname String Either a path or a glob of files to register
  • layout String Optionally, the name of another template to use as a layout
  • type String Optionally, the specific type of file to register. Defaults to all. (optional, default "*")

templateFunction

Register a handler function as a template. The registered function should return either a string or a Promise that resolves to string containing the template.

Parameters

  • name String The name of the template.
  • layout String Optionally, the name of another template to use as a layout
  • handler Function The handler function to use.

getTemplate

Returns the specified template if it exists

Parameters

  • name String The name of the template.

Returns Object A template object, with type and handler attributes.

getTemplates

Returns all registered templates

Returns Object An array of template object, with type and handler attributes.

render

Render a registered template with arguments

Parameters

  • name String The name of the template.
  • args Object Variables to make available to the template (optional, default {})

Returns Promise The rendered content as a string

Renderer Module

The rendering framework for Nxus applications.

Usage

import {renderer} from 'nxus-templater/lib/modules/renderer'

Defining a renderer

renderer.renderer(type, handler);

Where type is usually the filename extension and handler returns the rendered text when called with contents to render and an optional opts object.

Rendering a string

renderer.render(type, text).then((renderedText) => {console.log(renderedText)});

You can pass an optional arugment opts for options to pass to the renderer.

renderer.render(type, text, {title: 'My Title'}).then((renderedText) => {console.log(renderedText)});

Rendering a file

renderer.renderFile(type, filename).then((renderedText) => {});

You can pass an optional arugment opts for options to pass to the renderer.

Renderer API


Renderer

Extends NxusModule

Renderer renders different files and content using common rendering engines, like EJS and MarkDown.

Parameters

  • app

renderer

Provide a renderer for a particular type (file extension)

Parameters

  • type string The type (e.g. 'html') this renderer should handle
  • handler function Function to receive (content, options) and return rendered content

render

Request rendered content based on type

Parameters

  • type string The type (e.g. 'html') of the content
  • content string The contents to render
  • opts object Options for the renderer context (optional, default {})

Returns Promise The rendered content

renderFile

Provide a renderer for a particular type (file extension)

Parameters

  • filename string Path to content to render
  • opts object Options for the renderer context (optional, default {})

Returns Promise The rendered content