handlebars-email-renderer
v2.0.2
Published
Allows you to create components that render to email HTML using Handlebars.js.
Downloads
3
Maintainers
Readme
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