/zup

A simple, fast template engine for node.js

Primary LanguageJavaScriptMIT LicenseMIT

Description

A simple, fast template engine for node. The syntax is very close to that of other template engines, especially ejs.

One special feature of zup is that it ignores any 'end markers' that may appear in string literals inside a code block or expression. This is something that some other template engines (that usually use regexps for parsing) do not take into account and could lead to surprising results. For example:

<h1>[[- "Look ma, a fake ]]!" ]]</h1>

In this particular case, zup will correctly render this template like:

<h1>Look ma, a fake ]]!</h1>

Benchmark results can be found here.

Requirements

  • node.js -- v4.0.0 or newer, although v6.0.0+ is recommended for best performance.

Install

npm install zup

Example

var compile = require('zup');

var fn = compile(`
<html>
  <head>
    <title>My First Article</title>
  </head>
  <body>
    <h1>[[=z.heading.length > 16 ? z.heading.slice(0,16) + '...' : z.heading]]</h1>
    [[ if (z.alert) { ]]
      <h3>[[=z.alert]]</h3>
    [[ } ]]
    <pre>[[-z.content>>]]</pre>
  </body>
</html>
`);

console.log(fn({
  heading: 'This title will be truncated',
  content: `
    My life story, and I'm not kidding this time...
  `,
  alert: '<b>HI MOM!</b>'
}));

// Displays:
//
// <html>
//   <head>
//     <title>My First Article</title>
//   </head>
//   <body>
//     <h1>This title will ...</h1>
//     
//       <h3>&lt;b&gt;HI MOM!&lt;/b&gt;</h3>
//     
//     <pre>My life story, and I'm not kidding this time...</pre>
//   </body>
// </html>
//

Syntax

zup expressions/code blocks are enclosed by (customizable) start and end markers.

Special symbols placed right inside the start and end markers control the output of expressions.

Symbols that can be used after start markers:

  • = - This indicates that the output resulting from the expression should have some special characters converted to their respective html entity names:

    • <, >, &, ', "

  • - - (opposite of =) This indicates that the output resulting from the expression should not have special characters converted to their respective html entity names.

  • (none) - This indicates a generic code block, useful for control flow (e.g. if, while, for, etc.) and other such statements.

Symbols that can be used before end markers:

  • > - If just a single >, this indicates that only newlines ('\r' and '\n') will be trimmed from the beginning and end of the output returned from the expression.

  • >> - This indicates that all whitespace ('\r', '\n', '\t', ' ', and '\f') will be trimmed from the beginning and end of the output returned from the expression.

There is also an include() helper available inside templates:

  • include(< string >name[, < object >data]) - (void) - Inserts the rendered output of the template specified by name at the current position in the current template. data is an optional value that you can pass to the template's render function to use as a data source. How the template identified by name is looked up is described below in the description of cache.get().

API

require('zup') returns the template compiler function.

  • compile(< string >template[, < object >options]) - function - Creates and returns a compiled template as a renderer function. The following are valid options properties:

    • objName - string - This is the name of the object used to access data variables. Default: 'z'

    • start - string - The start marker used to indicate the start of a zup expression or code block. Default: '[['

    • end - string - The end marker used to indicate the end of a zup expression or code block. Default: ']]'

    • basePath - string - This is the default base path used for looking up templates referenced by calls to include() in a template. Default: (the directory of the "main" script)

    • cache - object - This object should contain get() and set() functions:

      • get(< string >name) - (mixed) - name is the string passed to the include() function inside a template. Return a function to use that for rendering the requested template. If no value/undefined is returned, then the template will be searched for on the local file system using the configured basePath and appending '.ztpl' to the end of name.

      • set(< string >name, < string >filepath, < function >compiled) - (void) - name is the string passed to the include() function inside a template, filepath is the absolute path of the newly compiled template, and compiled is the resulting renderer function. Store compiled somewhere for use in get() to avoid repeated template parsing/compilation.