@swiftpost/templ NPM

@swiftpost/templ

Introduction

A system for creating and rendering HTML templates with HTML, specifically tailored for emails. It supports variables, loops, conditionals, includes, and CSS embedding, ensuring compatibility across various email clients by handling CSS appropriately and sanitizing dynamic content to prevent HTML injection.

Installation

npm install @swiftpost/templ

Usage

To render a template, use the render method provided by the Templ class. You can optionally specify a CSS file to embed styles into the HTML.

Example

import path from "path";
import { Templ } from "./templ";

const templatesDir = path.join(__dirname, "templates");
const parser = new Templ(templatesDir);

const data = {
  name: "Alice",
};

const htmlContent = await parser.render("styles-embedding.html", data, {
  css: ["styles.css"],
});
console.log(htmlContent);

Templ Options

The Templ class constructor accepts the following options:

baseDir: The base directory for your templates.

Template Syntax

Variables

Use {{var}} to output variable values:

<p>Hello, {{var}}!</p>

Loops

Use the *for attribute for iteration:

<ul>
  <li *for="item of items">{{item.name}}</li>
</ul>

You can also nest loops:

<ul>
  <div *for="list of items">
    <ul>
      <li *for="item of list">{{item.name}}</li>
    </ul>
  </div>
</ul>

Conditionals

Use the *if attribute for conditional rendering:

<div>
  <p *if="isMember">Welcome back!</p>
</div>

*if only accepts boolean, truthy values, and falsy values. You can use the ! operator to negate the condition, e.g. <span *if="!isMember">Not a member</span>.

Includes

Use the self-closing <include/> tag to embed other templates:

<include src="header.html" />
<p>Main content here</p>
<include src="footer.html" />

CSS Embedding

To embed CSS styles from a CSS file into your HTML templates, provide the CSS file name as an option to the render method. The engine will include <style> tags in both <head> and <body> for better compatibility.

Example:

<!-- template.html -->
<html>
  <head>
    <title>Welcome</title>
  </head>
  <body>
    <p class="red">This is red</p>
  </body>
</html>

/* styles.css */
p.red {
  color: red;
}

import path from "path";
import { Templ } from "./templ";

const templatesDir = path.join(__dirname, "templates");
const parser = new Templ(templatesDir);

const data = {
  name: "Alice",
};

const htmlContent = await parser.render("template.html", data, {
  css: ["styles.css"],
});
console.log(htmlContent);

Rendered Output:

<html>
  <head>
    <title>Welcome</title>
    <style>
      p.red {
        color: red;
      }
    </style>
  </head>
  <body>
    <style>
      p.red {
        color: red;
      }
    </style>
    <p class="red">This is red</p>
  </body>
</html>

`Templ.render` Parameters

Parameter	Type	Description
`template`	string	The template to render, either a string or a file path.
`data`	object	An object containing data to be used in the template.
`options`	`TemplRenderOptions`	(optional) An object containing additional options.

`TemplRenderOptions`

Option	Type	Description
`css`	string[]	(optional) An array of CSS file names to embed into the HTML.
`baseDir`	string	(optional) The base directory for your templates.

License

This project is licensed under the MIT License. See the LICENSE file for details.

render html template parser

@swiftpost/logger

@swiftpost/mail

0.0.1

8 months ago