Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/groupon/gleemail
Making email template development fun! Sort of!
https://github.com/groupon/gleemail
Last synced: 16 days ago
JSON representation
Making email template development fun! Sort of!
- Host: GitHub
- URL: https://github.com/groupon/gleemail
- Owner: groupon
- License: other
- Created: 2014-09-20T15:41:26.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2015-06-19T12:58:12.000Z (over 9 years ago)
- Last Synced: 2024-08-01T02:26:13.142Z (3 months ago)
- Language: CoffeeScript
- Size: 834 KB
- Stars: 293
- Watchers: 16
- Forks: 24
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Gleemail
*Remember when developing HTML emails used to be fun?* **Nope, neither do I.**
Gleemail is an attempt to change that. It's a local development environment for creating HTML emails that removes a lot of the headaches.
## Features
* Build email templates with [Mustache](http://mustache.github.io/).
* Write CSS using [Stylus](http://learnboost.github.io/stylus/).
* Custom Gleemail HTML tags cleanly render into unsightly nested table structures.
* Automatically inlines CSS styles for you.
* Export templates to other templating engines (MailChimp, Eloqua, FreeMarker, etc.)
* Share Mustache and Stylus partials between email templates.
* Live browser preview refreshes whenever you save changes to files.
* View both HTML and text previews of an email in the browser.
* Automatically upload images to S3, automatically reference them in test emails.
* One-click test email delivery.
* One-click project creation in Litmus and Eloqua.
* Automatically render templates with dummy data from a JSON file.
* CLI for rendering templates from the command line.
[Demo Presentation](https://vimeo.com/108481023)
## Getting Started
Install Node.js, then install the `gleemail` npm package globally:
```shell
npm install -g gleemail
```
Create a new project directory:
```shell
gleemail project my-project-dir-name
```
Edit `config.json` with your email, [S3](http://aws.amazon.com/s3) and [Litmus](https://litmus.com) credentials, then start the server:
```shell
cd ./my-project-dir-name
gleemail start
```
Now you should be able to visit http://localhost:4433 *in Chrome* and you will be able to see the example email template.
Use the UI to bootstrap your own templates, and the changes you make will be immediately displayed in the browser.
## Rendering from the Command Line
To programmatically render templates in a script or from the command line, use the `gleemail render` command:
```shell
cd /path/to/project
# Render the HTML version with the first dummy data to stdout
gleemail render your-template-name > my-email.html
# Render using the third piece of dummy data
gleemail render your-template-name -i 2 > my-email.html
# Render the text version, use -o to specify output instead of stdout
gleemail render your-template-name -t text -o my-email.txt
# Render as a Mailchimp template
gleemail render your-template-name -r mailchimp > my-email.html
```
To view all the available rendering options, use `gleemail help render`.
## Gleemail Markup
For all of these transformer "macro tags", any regular attributes (`id`, `class`, etc) that are placed on the macro element will be transferred to the generated element.
### ``
This gives you a box model for padding around a piece of content using table cells.
```html
Hello World
Hello World
```
### ``
This gives you a vertical stack of elements. Each child of the `` is assumed to be its own row.
```html
Hello
World
!!!
Hello
World
!!!
```
### `` with ``
Using `` with nested `` elements gives you horizontally aligned content.
Attributes placed on the `` elements are transferred to the generated ``s.
```html
Hello
World
!!!
Hello
World
!!!
```
### `gm-centered` Attribute
This attribute can be added to any tag to wrap its contents in a centered table.
This is primarily useful on the `` element.
```html
My body
My body
```
### Creating Custom Transformer Macros
To write your own macros, add a `hooks.js` or `hooks.coffee` file to your project directory.
It should export a function that take a `hooks` object, which has a number of methods on it including `addTransformer()`.
Transformer functions can be synchronous or asynchronous, and this is determined by the presence of a second argument in the function signature.
For example:
```javascript
// This is hooks.js
module.exports = function(hooks) {
// Simple, synchronous macro
// Turns:
// This is green!
// into:
// This is green!
hooks.addTransformer(function($) {
$("gm-green").each(function() {
greenTag = $(this);
span = $("");
span.append(greenTag.contents());
greenTag.after(span);
greenTag.remove();
});
});
// Asynchronous macro, requires passing $ back in the callback
// Turns:
//
// Into:
//
Contents of file...
hooks.addTransformer(function($, cb) {
fileTag = $("gm-file").eq(0); // for simplicity, let's say there's just one
pre = $("");
filePath = fileTag.attr("path");
require("fs").readFile(filePath, function(err, buffer) {
if (err) return cb(err);
pre.html(buffer.toString());
fileTag.after(pre);
fileTag.remove();
cb(null, $);
});
});
});
```
# Development
Please refer to `CONTRIBUTING.md` for contribution guidelines, any help is greatly appreciated!
After cloning the repository, do a setup and run the tests:
```shell
make setup
make test
```
The easiest way to use the `gleemail` command during development is to use the `npm link` command.
This makes your local executable available as if you had installed it globally from npm:
```shell
npm link .
```
To make development easier, you can use these commands to auto-load changes in client and server code:
```shell
# In gleemail dir
make dev
# In project dir
gleemail dev
```