handlebars-email-renderer

v2.0.2

Published

a year ago

Allows you to create components that render to email HTML using Handlebars.js.

Downloads

0High
0Medium
0Low

xavierloue

handlebars template mail email html typescript javascript npm nodejs

HandlebarsEmailRenderer

Installation

To install the package, run the following command:

npm install handlebars-email-renderer

# or

yarn add handlebars-email-renderer

Usage

This view engine uses the architecture of the 'views' folder to structure the different views of emails. This makes it trivial to use in basic applications, but you must ensure that this folder has at least the following architecture:

Basic Usage

In this section, we will cover the basic usage of HandlebarsEmailRenderer. We will show you how to create a simple email using the default layout and a single view.

Directory Structure:

To get started, you'll need to create a views directory with the following structure:

.
├── views
│   ├── layouts
│   │   └── main.hbs
│   └── welcome.hbs

2 directories, 2 files

The layouts folder contains the different layouts that can be used to structure your emails. For this example, we only need one layout, which we'll call main.hbs. This layout defines the basic structure of the email.

The welcome.hbs file is the view that will be rendered as the body of the email. This file contains the content that will be sent to the user.

Code Explanation:

To use HandlebarsEmailRenderer in your project, you'll need to create an instance of the HandlebarsEmailRenderer class with the desired options:

const { HandlebarsEmailRenderer } = require("handlebars-email-renderer");

const renderer = new HandlebarsEmailRenderer();

// You can customize the path and name of the `views` directory by passing a `viewsPath` option when instantiating the module:

const renderer = new HandlebarsEmailRenderer({
  viewsPath: "./my-email-templates",
});

The render method is used to render the email template. By default, the method will look for a view with the same name as the first argument passed to the function in the views directory. In this example, the welcome.hbs view will be rendered with the main.hbs layout:

const email = await renderer.render("welcome");
// or synchronous method
const email = renderer.renderSync("welcome");

Warning: Using the renderSync method is discouraged, as it may crash the Node.js process and cause performance issues. Use it only if you are certain that performing this method will not impact the performance of your application.

The email variable will now contain the rendered HTML email.

views/layouts/main.hbs:

The main layout is the HTML page wrapper which can be reused for the different views of the mail. {{{body}}} is used as a placeholder for where the main content should be rendered.

<html>
  <head>
    <meta charset="utf-8" />
    <title>Example Email</title>
  </head>
  <body>
    {{{body}}}
  </body>
</html>

views/welcome.hbs:

The content for the mail welcome which will be rendered into the layout's {{{body}}}.

<h1>Welcome, new user!</h1>

Advenced Usage

In this part, we introduce to choose a custom layout and use personalized data inside your emails. We will also see how the partials which allow you to break down your code into smaller portions of reusable components in all your emails. Before going further we recommend that you read the documentation handlebars introduction

Custom Layout:

To use a layout other than the default (main.hbs), you must pass the layout argument with the name of the corresponding .hbs file in the layouts directory.

// For use 'views/layouts/admin.hbs'

const email = await renderer.render("welcome", {
  layout: "admin",
});

Expressions:

You can pass custom data to your email on the second argument of the render method:

const email = await renderer.render("welcome", {
  user: {
    firstName: "John",
    pets: [
      {
        name: "Beethoven",
        dog: true,
      },
      {
        name: "Garfield",
        dog: false,
      },
    ],
  },
});

You can pass data in the following way into layouts and partials:

<!-- views/welcome.hbs: -->

<h1>Welcome, {{user.firstName}}</h1>

Yous can use some expression that is part of the Handlebars language itself:

<!-- views/welcome.hbs: -->

<h1>Welcome, {{user.firstName}}</h1>
{{#each user.pets}}
  <p>
    Your pet is named
    {{user.pets.name}}
    {{#if user.pets.dog}}
      , it is a dog!
    {{/if}}
  </p>
{{/each}}

Helpers can be used to implement functionality that is not part of the Handlebars language itself A helper can be registered at runtime via Handlebars.registerHelper, for example in order to uppercase all characters of a string.

const renderer = new HandlebarsEmailRenderer({
  helpers: {
    toUppercase: (text) => {
      return text.toUpperCase();
    },
  },
});

<!-- views/welcome.hbs: -->

<h1>Welcome, {{toUppercase user.firstName}}</h1>

for more information on expressions, see handlbars expressions.

Partials:

Directory Structure:

# With partials and subfolder of partials
.
├── views
│   ├── layouts
│   │   └── main.hbs
│   ├── partials
│   │   ├── components
│   │   │   └── button.hbs
│   │   ├── end.hbs
│   │   ├── head.hbs
│   │   └── navbar.hbs
│   └── welcome.hbs

4 directories, 6 files

In this architecture, we add:

a partials folder to organize the different components to reuse in your layouts and/or in your views.
one or more partials subfolders, to help structure your components.
several *.hbs files containing your components (one file = one partial).

For use a partial on layout (or on view):

<!-- views/layout/main.hbs: -->
{{> head }}

{{{ body }}}

{{> end }}

<!-- views/partials/head.hbs: -->
<html>
  <head>
    <meta charset="utf-8" />
    <title>Example Email</title>
  </head>
  <body>

<!-- views/partials/end.hbs: -->
  </body>
</html>

You can pass data to your component (partial) in the following way:

<!-- views/welcome.hbs: -->

<h1>Welcome, user</h1>
{{> components/button text='Click here!' link='https://github.com/handlebars-email-renderer/handlebars-email-renderer'}}

<!-- views/partials/components/button.hbs: -->

<a href="{{link}}">{{text}}</a>

for more information on partials, see handlbars partials.

More:

For more information on advanced handlebars features read handlebars documentation.

For more information on how to use HandlebarsEmailRenderer, please refer to the API documentation.

Contributing

Contributions are welcome! If you find a bug or want to suggest a new feature, please open an issue on the GitHub repository.

Before submitting a pull request, please make sure that your changes are consistent with the code style of the project, and that all tests pass. To run the tests, use the following command:

npm test

Acknowledgments

We would like to thank the team who created and maintains the Handlebars.js package on which this module is entirely based. We also express our gratitude to the contributors of Express Handlebars who have greatly inspired this module and have been a great help to us in many projects.

License

HandlebarsEmailRenderer is licensed under the MIT License.

Donation

If you have found my work useful and would like to support me, you can donate via PayPal or Bitcoin. Thank you in advance for your support!

PayPal

Bitcoin

1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2