cbT.js

A Node.js server-side template engine that supports multi-level template inheritance.

[ English | 中文 ]

Table of Contents

• Installation
• Features
• Example
• Usage
• Options
  • cbT.leftDelimiter
  • cbT.rightDelimiter
  • cbT.basePath
  • cbT.cachePath
  • cbT.defaultExtName
• API
  • cbT.compile(str)
  • cbT.compileFile(filename, options, callback)
  • cbT.render(str, data)
  • cbT.renderFile(filename, data, options, callback)
  • cbT.getInstance()
• Template Syntax
  • Template Inheritance (Layout)
    • extends tag
    • block tag
    • parent tag
    • child tag
    • slot tag
    • call tag
    • use tag
    • Example
  • Other Syntax
    • Escaped variable output
    • Unescaped variable output
    • URL-escaped variable output
    • HTML attribute escaped variable output
    • Escaped array output
    • Money formatting
    • Content truncation
    • URL protocol adaptation
    • Escaped function return value output
    • Unescaped function return value output
    • Variable definition
    • Array iteration
    • Conditional output
    • Sub-template definition
    • Sub-template invocation

Installation

$ npm install cb-template

Features

• Supports template inheritance (Layout)
• Modular templates
• Flexible template syntax

Example

<% if (user) %>
  <p><%=user.name%></p>
<% /if %>

Usage

const cbT = require('cb-template');

const template = cbT.compile(str);
template(data);
// => Rendered HTML string

cbT.render(str, data);
// => Rendered HTML string

// Supports template inheritance
cbT.renderFile(filename, data, options, (err, data) => {
  if (!err) {
    // => data is rendered HTML string
  }
});

Options

cbT.leftDelimiter

Defines the left delimiter, default value: <%

cbT.rightDelimiter

Defines the right delimiter, default value: %>

cbT.basePath

Defines the root directory for reading template files, default value is an empty string.

For example, if you want to use /my/template as the root directory for all templates, set cbT.basePath = '/my/template'

cbT.cachePath

Template cache directory, default value is the system temporary directory.

cbT.defaultExtName

Default extension for template files, default value is .html

API

cbT.compile(str)

Compiles a template string and returns a template function. Does not support template inheritance.

Parameters:

• str: String, input template content

Return value:

Type: Function, template function for subsequent direct template rendering.

Template function parameters:

• data: Object, input data

Example:

const template = cbT.compile(`<title><%=title%></title><p><%=nickname%></p>`);
template({ title: 'Title', nickname: 'Nickname' });
// => Rendered HTML string

cbT.compileFile(filename, options, callback)

Reads a template file and returns a template function. Supports template inheritance.

Parameters:

• filename: String, template file path. If cbT.basePath is set, basePath is used as the root directory. Absolute paths are recommended.
• options: Object, compilation parameters.
  • cache: Boolean, whether to enable compilation cache, default is enabled
• callback: Function, callback function executed after compilation.
  • Callback function parameters: err: whether there is an error; template: template function

Example:

cbT.compileFile('/your/path/filename.html', {}, (err, template) => {
  template({ title: 'Title', nickname: 'Nickname' });
  // => Rendered HTML string
});

cbT.render(str, data)

Compiles a template string and returns the rendered result. Does not support template inheritance.

Parameters:

• str: String, input template content
• data: Object, data for rendering. Object keys are automatically converted to variable names in the template

Return value:

Type: String, rendered string

Example:

cbT.render(`<title><%=title%></title><p><%=nickname%></p>`, { title: 'Title', nickname: 'Nickname' });
// => Rendered HTML string

cbT.renderFile(filename, data, options, callback)

Reads a template file and returns the rendered result. Supports template inheritance.

Parameters:

• filename: String, template file path. If cbT.basePath is set, basePath is used as the root directory. Absolute paths are recommended.
• data: Object, data for rendering. Object keys are automatically converted to variable names in the template
• options: Object, compilation parameters.
  • cache: Boolean, whether to enable compilation cache, default is enabled
  • cacheName: String, set cache name, default value changba-template-cache. This value is invalid if cbT.cachePath is set
• callback: Function, callback function executed after compilation.
  • Callback function parameters: err: whether there is an error; content: rendered result

Example:

cbT.renderFile('/your/path/filename.html', { title: 'Title', nickname: 'Nickname' }, {}, (err, content) => {
  console.log(content);
  // => Rendered HTML string
});

cbT.getInstance()

Gets a new instance of the template engine. Generally used to set individual options of the template engine, such as setting left and right delimiters separately.

Example:

const myInstance = cbT.getInstance();
myInstance.render(`<title><%=title%></title><p><%=nickname%></p>`, { title: 'Title', nickname: 'Nickname' });
// => Rendered HTML string

Note: The new instance cannot perform getInstance() operations. You can only getInstance() from cbT.

Template Syntax

The default template delimiters are <% %>, for example: <% block %>

Template Inheritance (Layout)

extends tag

<% extends template_path %>

For example <% extends /welcome/test %>

This refers to inheriting from the template basePath/welcome/test.html.

Note: The extends tag must be at the first character position of the first line of the template file. Also, this tag does not need a closing tag.

block tag

<% block name %>
  content...
<% /block %>

Using block in a parent template means defining a block named "name".

Using block in a child template means replacing the block with the same name in the parent template.

<% block name hide %>
  content...
<% /block %>

The hide attribute means hiding the block with the same name in the parent template in the child template.

parent tag

<% block name %>
  <% parent %>

  content...
<% /block %>

The parent tag can only be used within block tags. Its function is to place the content of the parent template's block with the same name at the position where parent is located in the current block.

child tag

<% block name %>
  <% child %>

  content...
<% /block %>

The child tag can only be used within block tags. Its function is to place the content of the child template's block with the same name at the position where child is located in the current block.

slot tag

<% block name %>
  <% slot slot_name %>
    content
  <% /slot %>

  content...
<% /block %>

slot tag can only be used within block tags.

The slot tag is used to define slot positions in parent templates. Child templates will replace the content at the same slot name position in the parent template.

call tag

<% block name %>
  <% call other_block_name %>
    <% slot slot_name %>
      content
    <% /slot %>
  <% /call %>

  content...
<% /block %>

<% block name %>
  <% call other_block_name slot1="slot_content_1" slot2="slot_content_2" %>
    <% slot slot3 %>
      slot_content_3
    <% /slot %>
  <% /call %>

  content...
<% /block %>

call is used to replace the content at the call position with the content of other block names in the current file (supports all parent templates). The meaning of slot is the same as in the previous section, it will replace the corresponding content.

use tag

<% block name %>
  <% use other_block_name slot1="slot_content_1" slot2="slot_content_2" %>

  content...
<% /block %>

use is a simplified version of call.

Example

Parent template parent.html:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Welcome to <% block title %>Test Title<% /block %></title>
</head>
<body>
  <h1>Welcome to <% block name %>Test Content<% /block %>!</h1>
  <p>
    <% block test-1 %>
      Test Content-1
    <% /block %>
  </p>

  <p>
    <% block test-2 %>
      <small><% child %></small>
      Test Content-2
    <% /block %>
  </p>
</body>
</html>