update docs, revert signature on inlineContent

Automattic · Feb 12, 2015 · e0382f5 · e0382f5
1 parent d4b602c
commit e0382f5
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -2,62 +2,33 @@
 [![Dependency Status](https://david-dm.org/Automattic/juice.png)](https://david-dm.org/Automattic/juice)
 # Juice ![](http://i.imgur.com/jN8Ht.gif)
 
-Given HTML, juice will inline your CSS properties into the `style`
-attribute.
+Given HTML, juice will inline your CSS properties into the `style` attribute.
 
 ## How to use
 
-```js
-var juice = require('juice');
-juice("/path/to/file.html", function(err, html) {
-  console.log(html);
-});
-```
+Juice has a number of functions based on whether you want to process a file, HTML string, or a cheerio document, and whether you want juice to automatically get remote stylesheets, scripts and image dataURIs to inline.
 
-`/path/to/file.html`:
-```html
-<html>
-<head>
-  <style>
-    p { color: red; }
-  </style>
-  <link rel="stylesheet" href="style.css">
-</head>
-<body>
-  <p>Test</p>
-</body>
-</html>
-```
+To inline HTML without getting remote resources, using default options:
 
-`style.css`
-```css
-p {
-  text-decoration: underline;
-}
+```js
+var juice = require('juice');
+var result = juice("<style>div{color:red;}</style><div/>");
 ```
 
-Output:
+result will be:
 ```html
-<html>
-<head>
-</head>
-<body>
-  <p style="color: red; text-decoration: underline;">Test</p>
-</body>
-</html>
+<div style="color: red;"></div>
 ```
 
 ## What is this useful for ?
 
-- HTML emails. For a comprehensive list of supported selectors see
-[here](http://www.campaignmonitor.com/css/)
+- HTML emails. For a comprehensive list of supported selectors see [here](http://www.campaignmonitor.com/css/)
 - Embedding HTML in 3rd-party websites.
 
 ## Projects using juice
 
 * [node-email-templates][1] - Node.js module for rendering beautiful emails with [ejs][2] templates and email-friendly inline CSS using [juice][3].
-* [swig-email-templates][4] - Uses [swig][5], which gives you [template inheritance][6], and
-  can generate a [dummy context][7] from a template.
+* [swig-email-templates][4] - Uses [swig][5], which gives you [template inheritance][6], and can generate a [dummy context][7] from a template.
 
 [1]: https://github.com/niftylettuce/node-email-templates
 [2]: https://github.com/visionmedia/ejs
@@ -69,72 +40,85 @@ Output:
 
 ## Documentation
 
-### juice(filePath, [options], callback)
-
- * `filePath` - html file
- * `options` - (optional) object containing these properties:
-   - `extraCss` - extra css to apply to the file. Defaults to `""`.
-   - `applyStyleTags` - whether to inline styles in `<style></style>`
-     Defaults to `true`.
-   - `applyLinkTags` - whether to resolve `<link rel="stylesheet">` tags
-     and inline the resulting styles. Defaults to `true`.
-   - `removeStyleTags` - whether to remove the original `<style></style>`
-     tags after (possibly) inlining the css from them. Defaults to `true`.
-   - `preserveMediaQueries` - preserves all media queries (and contained styles) 
-     within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. 
-     Other styles are removed. Defaults to `false`.
-   - `applyWidthAttributes` - whether to use any CSS pixel widths to create
-     `width` attributes on elements set in `juice.widthElements`
-   - `removeLinkTags` - whether to remove the original `<link rel="stylesheet">`
-     tags after (possibly) inlining the css from them. Defaults to `true`.
-   - `url` - how to resolve hrefs. Defaults to using `filePath`. If you want
-     to override, be sure your `url` has the protocol at the beginning, e.g.
-     `http://` or `file://`.
+### Options
+
+All juice methods take an options object that can contain any of these properties, though not every method uses all of these:
+
+ * `extraCss` - extra css to apply to the file. Defaults to `""`.
+ * `applyStyleTags` - whether to inline styles in `<style></style>` Defaults to `true`.
+ * `removeStyleTags` - whether to remove the original `<style></style>` tags after (possibly) inlining the css from them. Defaults to `true`.
+ * `preserveMediaQueries` - preserves all media queries (and contained styles) within `<style></style>` tags as a refinement when `removeStyleTags` is `true`. Other styles are removed. Defaults to `false`.
+ * `applyWidthAttributes` - whether to use any CSS pixel widths to create `width` attributes on elements set in `juice.widthElements`. Defaults to `false`.
+ * `webResources` - An options object that will be passed through to web-resource-inliner for juice functions that will get remote resources (`juiceResources` and `juiceFile`). Defaults to `{}`.
+
+### Methods
+
+#### juice(html [, options])
+
+Returns string containing inlined HTML. Does not fetch remote resources.
+
+ * `html` - html string, accepts complete documents as well as fragments
+ * `options` - optional, see Options above
+
+#### juice.juiceResources(html, options, callback)
+
+Callback returns string containing inlined HTML. Fetches remote resources.
+
+ * `html` - html string
+ * `options` - see Options above
  * `callback(err, html)`
-   - `err` - `Error` object or `null`.
-   - `html` - contains the html from `filePath`, with potentially `<style>` and
-     `<link rel="stylesheet">` tags removed, and css inlined.
+   - `err` - `Error` object or `null`
+   - `html` - inlined HTML
 
-### juice.juiceContent(html, options, callback)
+#### juice.juiceFile(filePath, options, callback)
 
- * `html` - raw html content
- * `options` - same options as calling `juice`, except now `url` is required.
- * `callback(err, html)` - same as calling `juice`
+Callback returns string containing inlined HTML. Fetches remote resources.
 
-### juice.juiceDocument(document, options, callback)
+ * `filePath` - path to the html file to be juiced
+ * `options` - see Options above
+ * `callback(err, html)`
+   - `err` - `Error` object or `null`
+   - `html` - inlined HTML
+
+#### juice.juiceDocument($ [, options])
 
-Operates on a jsdom instance. Be sure to use the same jsdom version that juice
-uses. Also be sure to clean up after you are done. You may have to
-call `document.parentWindow.close()` to free up memory.
+Returns string containing inlined HTML. Does not fetch remote resources.
 
- * `document` - a jsdom instance
- * `options` - see `juice.juiceContent`
- * `callback(err)`
+ * `$` - a cheerio instance, be sure to use the same cheerio version that juice uses
+ * `options` - optional, see Options above`
 
-### juice.inlineContent(html, css)
+#### juice.inlineContent(html, css [, options])
 
 This takes html and css and returns new html with the provided css inlined.
 It does not look at `<style>` or `<link rel="stylesheet">` elements at all.
 
-### juice.inlineDocument(document, css, options)
+ * `html` - html string
+ * `css` - css string
+ * `options` - optional, see Options above
+
+#### juice.inlineDocument($, css [, options])
+
+Given a cheerio instance and css, this modifies the cheerio instance so that the provided css is inlined. It does not look at `<style>` or `<link rel="stylesheet">` elements at all.
+
+ * `$` - a cheerio instance, be sure to use the same cheerio version that juice uses
+ * `css` - css string
+ * `options` - optional, see Options above
 
-Given a jsdom instance and css, this modifies the jsdom instance so that the
-provided css is inlined. It does not look at `<style>` or
-`<link rel="stylesheet">` elements at all.
+### Global settings
 
-### juice.ignoredPseudos
+#### juice.ignoredPseudos
 
 Array of ignored pseudo-selectors such as 'hover' and 'active'.
 
-### juice.widthElements
+#### juice.widthElements
 
 Array of HTML elements that can receive `width` attributes.
 
 ## Credits
 
 (The MIT License)
 
-Copyright (c) 2011 Guillermo Rauch &lt;guillermo@learnboost.com&gt;
+Copyright (c) 2015 Guillermo Rauch &lt;guillermo@learnboost.com&gt;
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -157,7 +141,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ### 3rd-party
 
-- Uses the excellent [JSDom](http://github.com/tmpvar/jsdom) for the underlying DOM
+- Uses [cheerio](https://github.com/cheeriojs/cheerio) for the underlying DOM
 representation.
 - Uses [cssom](https://github.com/NV/CSSOM) to parse out CSS selectors and
 [Slick](http://github.com/subtleGradient/slick) to tokenize them.

diff --git a/lib/juice.js b/lib/juice.js
@@ -55,7 +55,7 @@ juice.ignoredPseudos = ['hover', 'active', 'focus', 'visited', 'link'];
 juice.widthElements = ['TABLE', 'TD', 'IMG'];
 
 juice.juiceDocument = juiceDocument;
-juice.juiceContent = juiceContent;
+juice.juiceResources = juiceResources;
 juice.juiceFile = juiceFile;
 juice.inlineDocument = inlineDocument;
 juice.inlineContent = inlineContent;
@@ -172,7 +172,7 @@ function juiceDocument($, options) {
   return $;
 }
 
-function juiceContent(html, options, callback) {
+function juiceResources(html, options, callback) {
   options = getDefaultOptions(options);
 
   var onInline = function(err, html) {
@@ -193,8 +193,6 @@ function getDefaultOptions(options) {
     extraCss: "",
     applyStyleTags: true,
     removeStyleTags: true,
-    applyLinkTags: true,
-    removeLinkTags: true,
     preserveMediaQueries: false,
     applyWidthAttributes: false,
   }, options);
@@ -213,21 +211,14 @@ function juiceFile(filePath, options, callback) {
       var rel = path.dirname(path.relative(process.cwd(),filePath));
       options.webResources.relativeTo = rel;
     };
-    juiceContent(content, options, callback);
+    juiceResources(content, options, callback);
   });
 }
 
-function inlineContent(html, css, options, callback) {
-  var onInline = function(err, html){
-    if(err){
-      return callback(err);
-    }
+function inlineContent(html, css, options) {
     var $ = utils.cheerio(html);
-    inlineDocument($, css, {});
-    callback(null, $.html());
-  }
-
-  utils.inlineExternal(html, options.webResources, onInline);
+    inlineDocument($, css, options);
+    return $.html();
 }
 
 function getStylesData($, options) {

diff --git a/test/run.js b/test/run.js
@@ -57,10 +57,10 @@ function test (testName, options) {
     };
 
     if(config === null) {
-      juice.inlineContent(html, css, options, onJuiced);
+      onJuiced(null, juice.inlineContent(html, css, options));
     }
     else {
-      juice.juiceContent(html, config, onJuiced);
+      juice.juiceResources(html, config, onJuiced);
     }
   };
 }