email-template-builder v1.0.0

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