Ha-pugmail NPM

PUGMAIL

WHY MOVE TEMPLATES OVER TO PUG?

Pug does everything that JSP does, is clearer and easier to read, is less verbose and provides some very useful functionality ,like block prepending and appending, that makes modularization easier. It also is a good first step to breaking away from JSP and backend-land while still tying in to legacy comm structure.

CONVENTIONS

Importing - Every file should import everything that it needs and only what it needs! This is simple to do with less, and the pug structure has been set up so this should be relatively easy to do there as well.
Wherever Possible, Reuse - Reuse mixins that have been provided. There are some complicated gotchas regarding JSP in pug that we have tried to minimize by providing helper mixins in /mixins/shared/. You're welcome to try to re-invent the wheel, we just don't think it's a good use of your time.
Prefer attributes over arguments - One of the advantages of pug over JSP is it's ability to pass attributes around as a plain old object. This means that an included module doesn't have to take and handle a long list of arguments for separate use cases. Instead, you can just expand the attributes object on an element using &attributes(attributes).

FOLDER STRUCTURE

.
├── Gruntfile.js --------------- The job runner. Please see the file for specifics on what it can do.
├── README.md ------------------ This file!
├── comms ---------------------- The email definitions. These will extend a template and include a bunch of mixins to
│                                create a single comm. Each file should have the templateId as it's name.
├── headers -------------------- This mimics the `comms` directory but defines unique headers for each template.
├── mixins --------------------- This folder contains all the mixins to create the comms including headers, footers,
│   │                            layout helpers, elements like buttons, etc.
│   ├── consumer --------------}
│   ├── handy -----------------} Mixins that are specific to certain brands.
│   ├── oldConsumer -----------}
│   ├── pro -------------------}
│   ├── shared ----------------- These mixins should have no styling and therefore are usable in different branded comms.
│   └── utils ------------------ Utility mixins that don't display anything but help you structure your emails.
│       ├── conditions.pug ----- Conditionals like `if` and `switch` statements.
│       ├── jspImport_*.pug ---- Will export the required jsp tags to import the right helper files for jsps to render.
│       ├── loops.pug ---------- Allows you to use loops in your emails.
│       └── trackingPixel.pug -- Import our comm tracking pixel.
├── style ---------------------- This directory has a very similar structure to the mixins directory and is broken down by
│   │                            brand styles and then shared styles.
│   ├── comms ------------------ Styles specific to certain template Ids.
│   ├── consumer --------------- Consumer specific styles.
│   ├── default.less ----------- Some default styling that will help make html emails more consistent.
│   ├── global.css ------------- A few randome styles that are included in the head of comms to make clients play nicely.
│   ├── handy ------------------ Handy specific styles.
│   ├── oldConsumer ------------ Consumer specific styles that are not our latest template design.
│   ├── pro -------------------- Pro specific styles.
│   └── shared ----------------- Shared styles.
│       └── variables.less ----- Currently just defines several color variables. WILL PROBABLY REMOVE THIS!
├── templates ------------------ Defines a template for each of our brands so that we can be more consistent.)
└── test
    └── mocks ------------------ When running `grunt buildTestmail`, any json in this directory with the same templateId as
                                 a comm you are working in will be pulled in as the model data and can be accessed using
                                 the `testData` object. You can also check `testBuild` which is a boolean saying whether
                                 you are building for root or for production.

Rules for Successful Emails

Available Tags

Only use the following tags:


`table`	`tr`	`td`	`span`	`a`	`img`

Anything else is not guaranteed to work properly.

More Complicated Elements

In order to create more complicated elements (like buttons), use the mixins provided. If there is not a mixin for the specific element you are trying to create, please contact Isaac Doub to arrange for a new mixin to be added to the repository.

Note on XHTML Transitional

Because the doctype is defined as xhtml 1.0 transitional, there are some more limitations to what you can do with html than you may be used to. For example, you can't put block level elements inside inline elements. Please use the W3C Markup Validation Service to verify that your rendered code is valid in addition to using Litmus to verify that it works across clients.

Finally

As terrible as it sounds, it's sometimes best to use empty elements to arrange your content as you'd like. An empty td with width and height defined is honored by all email clients and may save you a big headache in the long run.

Gotchas

Including JSP tags

JSP tags are used both as top level xml tags as well as in attributes and there are some odd things you have to do to get them to render correctly in each situation.

As xml tags

Pug automatically renders out anything within < > as plain text, so if you don't need any pug variable attributes within the tag, such as jsp includes <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> you can simply type those out. This will also work if you just need a jsp variable as an attribute, such as <c:forEach var="i" begin="1" end="${ratingInt}"> as it will render out the ${ratingInt} as is in the generated file.

However, if you do need a pug variable who's value is rendered out in the final jsp, you can't just print it as a string. Instead you'll have to ommit the < > and just use the tag name. Thankfully pug doesn't stumble over custom tags unless they start with some special character lik % # . :. Usually this won't be an issue, so you can just use c:if(condition=cond) to render <c:if condition="whatever-cond-was"></c:if> (example in /mixins/shared/functions/conditions.pug).

If it is an issue, good luck.

As attributes

JSP allows you to insert JSP tags anywhere in a file, including in attribute values like <a href="<comm:url url='${todoVo.envUrl} .... Unfortunately, files in this repository go through a series of compilation steps to produce the JSP which can mangle such includes if not written correctly. In general we recommend you avoid doing this yourself as we have provided the two use cases we know of, comm urls and images, but if you do have to write another you can get it to work by using the following advice.

a(href!="<comm:url url='"+url+"' entryPointId='${"+epId+"}'/>")

Use != to disable pugs string escaping
Wrap the html tag attribute value in DOUBLE QUOTES - e.g. href="<comm:url ... />"
Wrap the jsp tag attributes value in SINGLE QUOTES - e.g. comm:url url='/something'
If you need to use pug variables, use STRING CONCATENATION WITHOUT SPACES rather than any fancy interpolation. - e.g. url='"+url+"'