Email Template Builder

Email Template Builder is a tool for building html e-mail content in a easy way since writing html for e-mails is really time consuming because each client treats the html differently. All the styling and content are added in a config (JSON) and can then be generated as a static html or a handlebars template.

Installation

npm install email-template-builder

Usage

Generation with only static content

var emailTemplateBuilder = require("email-template-builder");
 
var templateConfig = {
    title: "My e-mail template",
    width: 600,
    children: [
        {
            type: "container",
            settings: [{backgroundColor: "black", color: "white"}],
            children: [
                {
                    type: "text",
                    value: "Hi {{upperCase firstName}} {{lastName}}"
                }
            ]
        }
    ]
};
 
//Generate the email template
var html = emailTemplateBuilder.generate(templateConfig);
 
console.log(html);

Generation with variable data

var emailTemplateBuilder = require("email-template-builder");
 
var templateConfig = {
    title: "My e-mail template",
    width: 600,
    children: [
        {
            type: "container",
            settings: [{backgroundColor: "black", color: "white"}],
            children: [
                {
                    type: "text",
                    value: "Hi {{upperCase firstName}} {{lastName}}"
                }
            ]
        }
    ]
};
 
var data = {
    firstName: "John",
    lastName: "Doe"
};
 
//Generate the email template
var template = emailTemplateBuilder.generate(templateConfig);
 
//Generate e-mail with data
console.log(emailTemplateBuilder.generate(data, template));

Generation with custom helper functions

var emailTemplateBuilder = require("email-template-builder");
 
var templateConfig = {
    title: "My e-mail template",
    width: 600,
    children: [
        {
            type: "container",
            settings: [{backgroundColor: "black", color: "white"}],
            children: [
                {
                    type: "text",
                    value: "Hi {{upperCase firstName}} {{lastName}}"
                }
            ]
        }
    ]
};
 
var data = {
    firstName: "John",
    lastName: "Doe"
};
 
var helpers = {
    upperCase: function(name) {
        return name.toUpperCase();
    }
};
 
//Generate the email template
var template = emailTemplateBuilder.generate(templateConfig);
 
//Generate e-mail with data
console.log(emailTemplateBuilder.generate(data, template, helpers));

Commandline

email-template-builder requires a json-file with the configurations on the template and will output a handlebars e-mail template file. The template-builder will then watch for changes and re-generate the template.

The output directory can be specified with the flag -f.

It's possible to provide data for the template in which case the template also will be generated right away and stored in a .html file.

email-template-builder ./example/example.json  --hbsData ./example/exampleData.json -f ./output

How to build an e-mail template

Here are the specification of the different components that can be used to build html e-mails. There are also some examples in the example directory.

Settings

Soon to come

Main document

The start of the document doesn't require any type and must always be in the root.

Mandatory properties

• width (int)
• title (string)

Optional properties

• children (array) Main document can only have containers as children
• settings (object) default: see settings above

Example

{
    "width": 600,
    "title": "My email template",
    "settings": {
        "backgroundColor": "#4d3e39",
        "color": "#333333"
    },
    "children": []
}

Other objects/components

Objects are differentiated by the type value which is always mandatory

Container

Mandatory properties

• type ("container")

Optional properties

• children (array)
• padding (int) default: 0
• border (string) default: "0"
• borderRadius (int) default: 0
• settings (object) default: see default settings

Example

{
    "type": "container",
    "padding": 20,
    "settings": {
        "align": "center"
    },
    "children": []
}

Column containers

Mandatory properties

• type ("twoColumnContainer"/"threeColumnContainer")
• leftColumn (object) Needs to be a column object
• middleColumn (object) Needs to be a column object, only mandatory for threeColumnContainers
• rightColumn (object) Needs to be a column object

Optional properties

• padding (int) default: 0, the padding inside each column
• margin (int) default: 0, the margin around each column
• border (string) default: "0"
• borderRadius (int) default: 0
• settings (object) default: see default settings

Example

{
    "type": "twoColumnContainer",
    "margin": 20,
    "padding": 20,
    "leftColumn":  {"type": "column"},
    "rightColumn": {"type": "column"}
}

Column

Important: Only used together with Column containers

Mandatory properties

• type ("column")

Optional properties

• border (string) default: "0"
• borderRadius (int) default: 0
• settings (object) default: see default settings
• children (array)

Example

{
    "type": "column",
    "children": [
        {"type": "text", "value": "foo"}
    ]
}

Text

Mandatory properties

• type ("text")
• value (string) Text to be shown.

Optional properties

• settings (object) default: see default settings
• links (array) array of links, needs identifier in value string that matches identifier in links, example shown below

Example

{
    "type": "text",
    "value": "This is a text string with a ||git-link||.",
    "links": [
        {
          "identifier": "git-link",
          "href": "https://www.github.com",
          "value": "Git link",
          "settings": {"color": "#db7447"}
        }
    ]
}

Link

Mandatory properties

• type ("link")
• value (string) Text to be shown.
• href (string) url that the link should point to.

Optional properties

• settings (object) default: see default settings

Example

{
    "type": "link",
    "href": "https://www.github.com",
    "value": "Git link",
    "settings": {"color": "#db7447"}
}

Image

Mandatory properties

• type ("image")
• src (string) url pointing to image used.
• alt (string) Alternative text to be used if image is not found or blocked by e-mail client

Optional properties

• width (int) width in pixels, if not present the width is set to 100%.
• settings (object) default: see default settings

Example

{
    "type": "image",
    "src": "https://example.com/image.png",
    "alt": "One image",
    "width": 136,
    "settings": {"align":"center"}
}

Spacing

Mandatory properties

• type ("spacing")
• spacing (int) pixels that vertical space should be.

Example

{"type": "spacing", "spacing": 20}

Separator

Mandatory properties

• type ("separator")
• size (int) size of separator line in pixels
• style (string) style of line/border can be none/dotted/dashed/solid
• color (string) line color

Example

{
    "type": "separator",
    "size": 1,
    "style": "solid",
    "color": "#918e89"
},

Table

Mandatory properties

• type ("table")

Optional properties

• width (int) width in pixels, if not present the width is set to 100%.
• children (array) a table can only have children of type "row"
• settings (object) default: see default settings

Example

{
    "type": "table",
    "settings": {"align": "left", "lineHeight": 20},
    "children": [
        {
            "type": "row",
            "children": [
                {
                    "type": "cell",
                    "value": "Post"
                },
                {
                    "type": "cell",
                    "settings": {"align": "right"},
                    "value": "Sum"
                }
            ]
        }
    ]
}

Row

Mandatory properties

• type ("row")

Optional properties

• children (array) a row can only have children of type "cell"
• settings (object) default: see default settings

Example

See example for table

Cell

Mandatory properties

• type ("cell")

Optional properties

• value (string/array) a string or an array showing text, if value is not present children can be added instead
• children (array) only used if value doesn't exist
• colSpan (int) number of columns the cell should span over, default 1.
• settings (object) default: see default settings

Example

See example for table

Pre header

Pre header is a text that's not visible in the e-mail itself since it's hidden with styling but visible next to the subject in some e-mail clients.

Mandatory properties

• type ("preHeader")
• value (string)

Example

{
    "type": "preHeader",
    "value": "This part will be visible next to the subject in some e-mail clients"
}

Handlebars repeater (each)

If a handlebars e-mail template is generated rather than a static e-mail template then this component can be used to repeat certain components (creates an each hbs helper)

Mandatory properties

• type ("hbsEach")
• identifier (string) name of the key to repeat over
• children (string) childrens that should be repeated for each value in array

Example

hbsContext.json
{
    "names": [
        "John",
        "Paul"
    ]
}
 
emailTemplate.json
{
    "type": "hbsEach",
    "identifier": "names",
    "children": [
        {
            "type": "text",
            "value": "{{this}}"
        }
    ]
}

License

This project is under the MIT-license