Skip to content
This repository was archived by the owner on Jan 22, 2021. It is now read-only.

Commit 95d6f79

Browse files
author
Satya van Heummen
committed
Merge remote-tracking branch 'lookback/master'
2 parents 3909b1e + d6f4d95 commit 95d6f79

File tree

9 files changed

+87
-59
lines changed

9 files changed

+87
-59
lines changed

Diff for: ‎.versions

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ iron:[email protected]
2727
iron:[email protected]
2828
[email protected]
2929
[email protected]
30-
lookback:emails@0.5.1
30+
lookback:emails@0.6.1
3131
[email protected]
3232
meteorhacks:[email protected]
3333
[email protected]

Diff for: ‎README.md

+33-22
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ Usually, building HTML emails yourself is tedious. On top of that, add the need
1313
2. [Template paths on deployed instances](#template-paths-on-deployed-instances)
1414
3. [Template helpers](#template-helpers)
1515
4. [Layouts](#layouts)
16-
5. [Previewing and sending](#previewing-and-sending)
17-
6. [Paths](#paths)
18-
7. [Sample file structure](#sample-file-structure)
19-
8. [Logging](#logging)
20-
9. [Plain-text](#plain-text)
16+
5. [Plain text version](#plain-text)
17+
6. [Previewing and sending](#previewing-and-sending)
18+
7. [Paths](#paths)
19+
8. [Sample file structure](#sample-file-structure)
20+
9. [Logging](#logging)
2121
6. [Version history](#version-history)
2222
7. [Contributing](#contributing)
2323

@@ -28,7 +28,7 @@ Usually, building HTML emails yourself is tedious. On top of that, add the need
2828
- **SCSS support** using `node-sass` (opt-in).
2929
- **Preview and debug** emails in development mode in your browser when developing.
3030
- **Layouts** for re-using markup.
31-
- **Auto Plain-text** automatically creates a plain text version from your html template for lower Spam score.
31+
- **Auto Plain-text** automatically creates a plain text version from your HTML template for lower spam score.
3232

3333
Help is appreciated in order to hammer out potential issues and bugs.
3434

@@ -82,6 +82,8 @@ Please inspect the provided sample code for details.
8282
silent: false, // If set to `true`, any `Logger.info` calls won't be shown in the console to reduce clutter.
8383
addRoutes: process.env.NODE_ENV === 'development' // Add routes for previewing and sending emails. Defaults to `true` in development.
8484
language: 'html' // The template language to use. Defaults to 'html', but can be anything Meteor SSR supports (like Jade, for instance).
85+
plainText: true // Send plain text version of HTML email as well.
86+
plainTextOpts: {} // Options for `html-to-text` module. See all here: https://www.npmjs.com/package/html-to-text
8587
}
8688
```
8789

@@ -93,8 +95,6 @@ Please inspect the provided sample code for details.
9395
templates: {}, // Required. A key-value hash where the keys are the template names. See more below.
9496
helpers: {}, // Global helpers available for all templates.
9597
layout: false // Global layout template.
96-
settings:
97-
plainText: true // Optional, defaults to true
9898
}
9999
```
100100

@@ -339,6 +339,23 @@ It's you to render the raw CSS in your layout:
339339
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
340340
```
341341

342+
### Plain text version
343+
344+
By default, plain text versions are automatically created from your html template and included in the final email. It's strongly advises to leave this option on, as it greatly reduces your emails' spam score and the chance that your emails will end up in spam folder of users. However, if you want to override this behaviour simply at this to `Mailer.config()`:
345+
346+
```coffeescript
347+
Mailer.config(
348+
# ...
349+
plainText: false,
350+
plainTextOpts: {
351+
// Your options to send to the module, defaults to {}
352+
ignoreImage: true
353+
}
354+
)
355+
```
356+
357+
Consult the `html-to-text` [documentation](https://www.npmjs.com/package/html-to-text) for available options. See in the example app in this repo for how to disable images in plain text version, for instance.
358+
342359
### Previewing and Sending
343360

344361
`lookback:emails` makes it easier to preview email designs in your browser. And you can even interface with you database collections in order to fill them emails with *real data*.
@@ -349,11 +366,12 @@ Noticed the `route` property on the template? It uses Iron Router's server side
349366

350367
The `route` property expects a `path` property (feel free to use any of Iron Router's fanciness in here) and an optional `data` function providing the data context (an object). The function has access to the same scope as Iron Router's `action` hook, which means you can get a hold of parameters and the whole shebang.
351368

352-
**Two routes** will be added:
369+
**Three routes** will be added:
353370

354371
```
355-
/emails/preview/<routeName>
356-
/emails/send/<routeName>
372+
/emails/preview/<routeName> # Preview as HTML
373+
/emails/text/<routeName> # Preview as plain text
374+
/emails/send/<routeName> # Send the email to an address
357375
```
358376
The `/emails` root prefix is configurable in `config` in the `routePrefix` key.
359377

@@ -367,6 +385,7 @@ So for a template named `newsletterEmail`, the route names will be
367385

368386
```
369387
previewNewsletterEmail
388+
textNewsletterEmail
370389
sendNewsletterEmail
371390
```
372391

@@ -443,19 +462,11 @@ and that will be used. The logger **must** support these methods:
443462

444463
Why not try [`meteor-logger`](https://github.com/lookback/meteor-logger)? :)
445464

446-
### Plain-text
447-
By default, plain-text versions are automatically created from your html template and included in the final email. It's strongly advises to leave this option on, as it greatly reduces your emails' Spam score and the chance that your emails will end up in Spam folder of users. However, if you want to override this behaviour simply at this to `Mailer.init()`:
448-
449-
```coffeescript
450-
Mailer.init(
451-
settings:
452-
plainText: false
453-
)
454-
```
455-
456465
## Version history
457466

458-
- `0.6.0` - Automatically create and include plain-text email version from your HTML templates
467+
- `0.6.2` - Support passing options to `html-to-text` module in `Mailer.config()`.
468+
- `0.6.1`- Fix critical runtime crash when sending emails.
469+
- `0.6.0` - Automatically create and include plain text email version from your HTML templates, using [`html-to-text`](http://npmjs.com/package/html-to-text).
459470
- `0.5.1` - Remove need for setting the `BUNDLE_PATH` environment variable ([#39](https://github.com/lookback/meteor-emails/pull/39)).
460471
- `0.5.0` - Remove `node-sass` as hard dependency. SCSS support is now opt-in, by adding `chrisbutler:node-sass` to your app ([#35](https://github.com/lookback/meteor-emails/pull/35)).
461472
- `0.4.6` - Fix paths on Windows in development mode.

Diff for: ‎emails.coffee

+33-29
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,6 @@
77

88
TAG = 'mailer'
99

10-
# used to make plain-text version from html version
11-
htmlToText = Npm.require 'html-to-text'
12-
1310
# ## Setup
1411

1512
# Main exported symbol with some initial settings:
@@ -31,7 +28,7 @@ Mailer =
3128
addRoutes: process.env.NODE_ENV is 'development'
3229
language: 'html'
3330
plainText: true
34-
31+
plainTextOpts: {}
3532
juiceOpts:
3633
preserveMediaQueries: true
3734
removeStyleTags: true
@@ -205,6 +202,10 @@ MailerClass = (options) ->
205202

206203
return rendered
207204

205+
# Short hand function for converting HTML to plain text with some options.
206+
toText = (html) ->
207+
Utils.toText(html, settings.plainTextOpts)
208+
208209
# ## Send
209210
#
210211
# The main sending-email function. Takes a set of usual email options,
@@ -233,10 +234,7 @@ MailerClass = (options) ->
233234

234235
# create plain-text version from html
235236
if settings.plainText
236-
try
237-
opts.text = htmlToText.fromString opts.html
238-
catch ex
239-
Utils.Logger.error "Could not make plain-text version from html: " + ex.message
237+
opts.text = toText(opts.html)
240238

241239
catch ex
242240
Utils.Logger.error 'Could not render email before sending: ' + ex.message, TAG
@@ -260,30 +258,35 @@ MailerClass = (options) ->
260258
# This function adds the `preview` route from a `template` object.
261259
# It will apply the returned data from a `data` function on the
262260
# provided `route` prop from the template.
263-
previewAction = (template) ->
264-
try
265-
data = template.route.data and template.route.data.apply(this, arguments)
266-
catch ex
267-
msg = 'Exception in '+template.name+' data function: '+ex.message
268-
Utils.Logger.error msg, TAG
269-
@response.writeHead 500
270-
return @response.end msg
261+
previewAction = (opts) ->
262+
check opts,
263+
type: Match.OneOf('html', 'text')
271264

272-
# Compile, since we wanna refresh markup and CSS inlining.
273-
compile template
265+
return (template) ->
266+
try
267+
data = template.route.data and template.route.data.apply(this, arguments)
268+
catch ex
269+
msg = 'Exception in '+template.name+' data function: '+ex.message
270+
Utils.Logger.error msg, TAG
271+
@response.writeHead 500
272+
return @response.end msg
274273

275-
Utils.Logger.info "Rendering #{template.name} ...", TAG
274+
# Compile, since we wanna refresh markup and CSS inlining.
275+
compile template
276276

277-
try
278-
html = render template.name, data
279-
Utils.Logger.info "Rendering successful!", TAG
280-
catch ex
281-
msg = 'Could not preview email: ' + ex.message
282-
Utils.Logger.error msg, TAG
283-
html = msg
277+
Utils.Logger.info "Rendering #{template.name} as #{opts.type} ...", TAG
278+
279+
try
280+
html = render template.name, data
281+
content = if opts.type is 'html' then html else toText(html)
282+
Utils.Logger.info "Rendering successful!", TAG
283+
catch ex
284+
msg = 'Could not preview email: ' + ex.message
285+
Utils.Logger.error msg, TAG
286+
content = msg
284287

285-
@response.writeHead 200, 'Content-Type': 'text/html'
286-
@response.end(html, 'utf8')
288+
@response.writeHead 200, 'Content-Type': if opts.type is 'html' then 'text/html' else 'text/plain'
289+
@response.end(content, 'utf8')
287290

288291
# This function adds the `send` route, for easy sending emails from
289292
# the browser.
@@ -330,7 +333,8 @@ MailerClass = (options) ->
330333
check template.route.path, String
331334

332335
types =
333-
preview: previewAction
336+
preview: previewAction(type: 'html')
337+
text: previewAction(type: 'text')
334338
send: sendAction
335339

336340
_.each types, (action, type) ->

Diff for: ‎example/.meteor/versions

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ iron:[email protected]
4040
[email protected]
4141
[email protected]
4242
[email protected]
43-
lookback:emails@0.5.1
43+
lookback:emails@0.6.2
4444
[email protected]
4545
[email protected]
4646
meteorhacks:[email protected]

Diff for: ‎example/private/sample-email/template.html

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
<h2>Hi {{capitalizedName}}!</h2>
22

33
<p>
4-
This is some email content.
4+
This is some email content. With an image:
55
</p>
66

7+
<img width="500" src="https://lookback-public.s3.amazonaws.com/resources/opengraph.png">
8+
79
<p>
810
The members of the Beatles are {{enumerate names limit=3}}.
911
</p>

Diff for: ‎example/server/server.js

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
Mailer.config({
22
from: 'John Doe <[email protected]>',
33
replyTo: 'John Doe <[email protected]>',
4-
addRoutes: true
4+
addRoutes: true,
5+
plainTextOpts: {
6+
ignoreImage: true
7+
}
58
});
69

710
Meteor.startup(function() {

Diff for: ‎package.js

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@ var where = 'server';
33
Package.describe({
44
name: 'lookback:emails',
55
summary: 'Send HTML emails with server side Blaze templates. Preview and debug in the browser.',
6-
version: '0.6.0',
6+
version: '0.6.2',
77
git: 'https://github.com/lookback/meteor-emails.git'
88
});
99

1010
Npm.depends({
11-
"html-to-text": "1.3.0"
11+
'html-to-text': '1.3.0'
1212
});
1313

1414
Package.onUse(function(api) {

Diff for: ‎update-docs.sh

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
#!/usr/bin/env bash
22

33
git stash && \
4-
git checkout gh-pages && \
5-
git rebase master && \
4+
git checkout -b gh-pages && \
65
rm -rf docs && \
76
rm -rf example && \
87
docco emails.coffee utils.coffee && \
98
git add . && \
109
git commit -a -m 'Generate documentation' && \
1110
git push -f origin gh-pages && \
1211
git checkout master && \
12+
git branch -D gh-pages && \
1313
git stash pop && \
1414
echo "Done: Generated documentation"

Diff for: ‎utils.coffee

+8
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
fs = Npm.require 'fs'
44
path = Npm.require 'path'
5+
htmlToText = Npm.require 'html-to-text'
56

67
TAG = 'mailer-utils'
78

@@ -38,6 +39,13 @@ ROOT ||= developmentPrivateDir()
3839

3940
Utils =
4041

42+
# Takes an HTML string and outputs a text version of it. Catches and logs errors.
43+
toText: (html, opts = {}) ->
44+
try
45+
return htmlToText.fromString(html, opts)
46+
catch ex
47+
Utils.Logger.error "Could not make plain-text version from html: " + ex.message
48+
4149
capitalizeFirstChar: (string) ->
4250
string.charAt(0).toUpperCase() + string.slice(1)
4351

0 commit comments

Comments
 (0)