How to get more out out of Mandrill’s HTML Email Templates by using Handlebars.
Being able to create your own styled emails from within the Mandrill site is great, but with inline styling and limited templating options you can soon hit a brick wall when trying to build up more interesting designs.
This is a brief guide on how to implement an efficient local workflow will let you create templates easily that can be updated really quickly. To do this we are going to use a combination of Gulp, Handlebars.js, SCSS and HTML to make the template.
Download the code from this tutorial at https://bitbucket.org/toru_aine/blog_handlebars_mandrill
Lets start with an introduction to Gulp, Handlebars.js and Mandrill, although we’ll keep it short as there are plenty of other great resources on the web that can run you through the basics, or you can just skip down to ‘Project Setup & Code’.
Handlebars.js
Handelbars.js is a minimal logic templating language, it allows the coder to use placeholders in a HTML template, that when compiled will be replaced by JSON data and rendered to the end user as regular HTML. This is great because it allows the coder to make templates that have dynamic content. Although what makes Handlebars really cool is that it allows some logic to placed into the template, this means you can keep your template neat and minimal.
Mandrill
Mandrill is a transactional email API, it is currently running over the MailChimp platform and in many respects the two platforms are very similar. The main features of Mandrill are that emails can be sent to Mandrill via PHP or JavaScript, this allows a lot of flexibility when creating web apps. Mandrill allows custom templates to be created with dynamic content, it also has some basic analytics which can provide some useful insights into bounce rates, open rate, etc.
Gulp
Gulp is a node.js based task automator. There are many plugins that can be included in the project using the Node Pluging Manager (NPM). These perform specific actions such as LiveReload, compiling SCSS to CSS, processing Handlebars.js, minifying javascript, and so on. Using Gulp you can create different tasks that run independently or chained together, and even setup different tasks depending on parameters sent to gulp on initialisation.
In the following project you will see how we can use Gulp to compile SCSS to inline styling in the template and how Handlebars can be compiled so the coder can preview the email as the recipient would view the email. So next time you need to change the template don’t worry, its going to be really quick and easy.
Project Setup & Code
Enough background, lets get to the fun bit, the code. There’s Pizza too but we’ll come back to that later.
A lot of time can be wasted by copying the template into Mandrill, triggering the email, waiting for the email to arrive, realise something else needs to be tweaked and going back to the start again. You can go through this process several times whilst designing an email.
What would be really cool is if you could view your email without having to go through all of that, so lets take care of that.
First let’s look at the folder structure for this project is very simple, there are three folders in the root of the project; input, output and preview. Inside the input folder we have two more folders json and scss. Them there are a couple of other files in the root of the project which can be ignored for now.
We’re going to start by building up a JSON file which will hold that data for the Handlebars expression, some basics that you would want in the email is the sender’s details and a logo for the company/project the email is coming from, so we’ll make an object with the key of sender and set the email, first and last name as well a providing a link for the logo. Now lets add some actual content the recipient might actually like, so how about a list of Pizzas and their toppings. If we make the list an array, Handlebars will iterate the array for us so our template can not only be efficiently minimal but it means we don’t have to restrict the number of Pizzas that have to be sent.
Now we have the JSON data we can start to build up the HTML template. In all likelihood most of your HTML template is going to be static with only a few Handlebars expressions, so let not waste time with the regular HTML and instead skip straight to using Handlebars expressions. So straight in at the deep end then, on lines 22 to 26 we have a Handlebars if statement, which uses the sender object we setup in the JSON file earlier. Handlebars also allows iteration, so lets make use of that to loop through the results array, line 31 shows the start of the loop, there is also a closing tag on line 62. Anyone familiar with Angular or jQuery might expect to have a variable ‘result’ that you need to access to get to the Pizza name and topping, but in Handlebars you can directly access the object key in the expression. All fairly simple so far right? That’s as complicated as Handlebars.js gets. As you can see from this snippet of code, there is no (or nearly no) inline styling in the template, so lets sort that next.
All of the styling for the template is contained in either global.scss or template.scss. In the example included in the references section, we have overridden some of the standard styling from Mandrill, this has gone in the global.scss file as these changes would almost certainly need to be used across all templates in a project. How you structure your SCSS is totally your choice, suffice it to say that all that’s important is that its easy to maintain and that it compiles into the Handlebars template as inline styling.
The Gulp file is the shortest file but possibly the most important part of the whole project. The Gulp file is pretty much what you see is what you get, we have an array of templates, here we can add the names of the template files. For each template we will setup its own gulp task, for each template we will create four sub-tasks, one for SCSS, one for inline SCSS, one for Handlebars and finally a watch task. The four tasks need to run in order, so that the SCSS can be compiled in CSS, which is then pulled into the Handlebars template, then Handlebars is compiled with the data from the JSON file. The full gulpfile can be seen in the demo link at the bottom of this post.
The file in the output folder is what will be copied into Mandrill, as can be seen in the image to the left, the template now includes the inline css but the Handlebars expressions are still there. We need the expressions to be left so that we may pass the data to Mandrill. Even in this small snippet there is duplication of styling and this template doesn’t have an overly complex style, so its not hard to imagine how much duplication there’ll be on a larger, more intricate template.
The snippet to the left shows how the email code will look when its been sent to the recipient, by compiling the Handlebars expressions, in conjunction with LiveReload, its really quick to fix any bugs with the design and you can see how it will look in a browser with ‘real’ data immediately, no need to wait for Mandrill to send the email anymore.
Once you are happy that the template is styled and structured as you want you are now ready to add it to Mandrill. Log into Mandrill, create a new template, setup the template name, and copy all of the code from the output HTML template into HTML text area in Mandrill and click Publish. You’re now ready to send a test email. If you do need to tweak any part of the template you can edit it, Gulp will re-build, you preview in browser and when you’re ready you can update the template in Mandrill.
Here’s the final result…
learn more about html on our website…
References
Handlebars Tutorial. http://code.tutsplus.com/tutorials/an-introduction-to-handlebars--net-27761
Mandrill & Handlebars. https://mandrill.zendesk.com/hc/en-us/articles/205582537-Using-Handlebars-for-Dynamic-Content
Gulp Tutorial. https://scotch.io/tutorials/automate-your-tasks-easily-with-gulp-js
Source Code. https://bitbucket.org/toru_aine/blog_handlebars_mandrill
