view-gate

v1.1.0

Published

4 months ago

An express js templating engine with clean syntax and support for builtin layout and all loops

0High
0Medium
0Low

felix-ongom

View gate

Overview

This is a lightweight CommonJS template engine for Node.js/Express that supports:

<% %> JavaScript code blocks
{{ }} → Text and number output
{{{ }}} → Raw HTML output
include() → Partial templates
layout() → Layouts with nested templates
Global and per-render helpers
Template caching for performance

It is designed to be simple, flexible, and easy to integrate with Express.

Or include it locally in your project:

const { renderFile, registerHelper } = require("view-gate");

Features

1. JavaScript Code Blocks

Use <% %> to run arbitrary JavaScript in your templates:

<% for (let i = 0; i < items.length; i++) { %>
  <li>{{ i }} - {{ items[i] }}</li>
<% } %>

Supports:

for, while, do…while
if, else if, else
forEach, map
Any valid JavaScript code

2. Variable Interpolation

Escaped Output

Syntax: {{ expression }}
Automatically escapes HTML to prevent XSS attacks.

<p>User Name: {{ user.name }}</p>

Raw Output

Syntax: {{{ expression }}}
Inserts raw HTML without escaping.

<p>HTML Content: {{{ user.htmlContent }}}</p>

3. Layouts

You can wrap your template in a layout:

{{ layout("layouts/main", { title: "Homepage" }) }}

Layout files can contain {{ body }} or {{{ body }}} for inner template content.
Additional variables can be passed as the second argument.

Example layouts/main.html:

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
</head>
<body>
  {{{ body }}}
</body>
</html>

4. Includes (Partials)

Include partial templates with optional data:

{{ include("partials/header", { user }) }}

Paths are relative to the current template.
Variables can be passed as an object.

5. Helpers

Global Helpers

You can register helpers once, and they are available in all templates:

registerHelper("upper", str => String(str).toUpperCase());
registerHelper("lower", str => String(str).toLowerCase());
registerHelper("repeat", (str, n) => String(str).repeat(n));

Usage in templates:

<p>{{ upper(user.name) }}</p>
<p>{{ lower(user.name) }}</p>
<p>{{ repeat("-", 10) }}</p>

Per-render Helpers

You can also pass helpers per render:

res.render("home", {
  data,
  helpers: {
    shout: s => s.toUpperCase() + "!!!"
  }
});

Per-render helpers override global helpers if names collide.

6. Template Caching

Compiled templates are cached in memory for faster rendering.
The engine automatically reuses compiled functions for repeated renders.

API

`renderFile(filePath, data, callback)`

Render a template file.

renderFile(filePath, data, (err, html) => {
  if (err) throw err;
  console.log(html);
});

filePath → path to the template file
data → object containing variables and optionally helpers
callback(err, html) → receives the rendered HTML

`registerHelper(name, fn)`

Registers a global helper function.

registerHelper("upper", str => str.toUpperCase());

Express Integration

const express = require("express");
const path = require("path");
const { renderFile, registerHelper } = require("./templateEngine");

const app = express();

// Register the engine
app.engine("html", renderFile);
app.set("views", path.join(__dirname, "views"));
app.set("view engine", "html");

// Global helpers
registerHelper("upper", s => String(s).toUpperCase());
registerHelper("lower", s => String(s).toLowerCase());

app.get("/", (req, res) => {
  res.render("home", {
    user: { name: "Felix", age: 21 },
    items: ["Apple", "Banana", "Orange"]
  });
});

app.listen(3000, () => console.log("Server running on http://localhost:3000"));

Example Template (`views/home.html`)

{{ layout("layouts/main", { title: "Homepage" }) }}

<h2>User Information</h2>
<p>Name (escaped): {{ user.name }}</p>
<p>Name (raw): {{{ user.name }}}</p>

<p>Uppercase (helper): {{ upper(user.name) }}</p>

<h3>Items List</h3>
<ul>
<% items.forEach((item, i) => { %>
  <li>{{ i }} - {{ item }} </li>
<% }) %>
</ul>

{{ include("partials/footer") }}

Notes & Best Practices

HTML Escaping: Use {{ }} for user input to prevent XSS. Use raw versions only for trusted content.
Helpers: Use global helpers for reusable functions. Per-render helpers are useful for one-off templates.
Includes & Layouts: Paths are relative to the template file. Pass variables via objects.
Caching: Templates are cached automatically; restarting the server reloads them.
JS Blocks: Any valid JS code is allowed inside <% %> blocks. Use them for loops, conditionals, and variable manipulation.

Syntax Summary

| Feature | Syntax Examples | Description | | ------------------ | ------------------------------------------ | --------------------------------- | | Escaped Output | {{ name }} | HTML-escaped text | | Raw Output | {{{ htmlContent }}} | Raw HTML | | JS Code | <% for(let i=0;i<items.length;i++){ %> <li>{{ i }}<li> <%}%> | JS block for loops/conditions. The same concept in all kind of loops | | Include Partial. | {{ include("header") }} | Insert partial template | | Layout | {{ layout("main") }} | Apply layout wrapping | | Global Helpers | {{ upper(name) }} | Registered via registerHelper() | | Per-render Helpers | {{ shout(name) }} | Passed via helpers in render |