KevinMidboe/inline-html
1
0
Fork 0
mirror of https://github.com/KevinMidboe/inline-html.git synced 2025-10-29 17:40:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Change api to separate html file and string processing.

Browse Source
This commit is contained in:
Alexandre Gigliotti
2015-10-13 13:59:25 -07:00
parent 2c981a6038
commit bd793daae4
9 changed files with 407 additions and 381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
README.md
View File

@@ -8,39 +8,24 @@ Inline local assets referenced in an HTML document.
[![David](https://img.shields.io/david/panosoft/inline-html.svg)](https://david-dm.org/panosoft/inline-html)
[![npm downloads](https://img.shields.io/npm/dm/inline-html.svg)](https://www.npmjs.com/package/inline-html)
## Installation
This library parses HTML, embeds the contents of local assets that are referenced within that HTML, and returns a new inlined HTML string.
```sh
npm install inline-html
```
The following HTML elements and CSS data types are inlined:
- Images - The source path is replaced with a datauri.
- Linked LESS stylesheets - The LESS is compiled and the result is inlined within a `<style>` element. Note that `@imports` are processed as well.
- CSS url data types - The reference path is replaced with a datauri. These can be used in linked stylesheets, style elements, and element style attributes.
## Usage
Reads an HTML file, embeds the contents of local assets that are referenced within that file, and returns the inlined `html` string.
The following elements and data types are inlined:
- LESS stylesheets - The LESS is compiled and the result is inlined within a `<style>` element.
- CSS url data types - The reference path is replaced with a datauri. These can be used in linked stylesheets, style elements, and element style attributes.
- Images - The source path is replaced with a datauri.
Assuming we have the following files:
- `index.html`
```html
<link rel="stylesheet/less" href="main.less"/>
<style>
div { background-image: url('path/to/file'); }
</style>
<div style="background-image: url('path/to/file');"></div>
<img src="path/to/file"/>
```
Assuming ...
- `main.less`
```css
@import (inline) 'main.css';
@import (less) 'main.css';
div { background-image: url('path/to/file'); }
```
@@ -50,57 +35,110 @@ Assuming we have the following files:
@font-face { src: url('path/to/file'); }
```
We can use `inline-html`:
Then ...
```js
var inlineHtml = require('inline-html');
var co = require('co');
var inline = require('inline-html');
inlineHtml('index.html').then(function (html) {
// ...
});
```
To create the following `html` string:
```html
co(function * () {
var html = `
<link rel="stylesheet/less" href="main.less"/>
<style> div { background-image: url('path/to/file'); } </style>
<div style="background-image: url('path/to/file');"></div>
<img src="path/to/file"/>
`;
html = yield inline.html(html);
console.log(html);
/**
<style>
@font-face { src: url('data:...'); }
div { background-image: url('data:...'); }
</style>
<style>
div { background-image: url('data:...'); }
</style>
<style> div { background-image: url('data:...'); } </style>
<div style="background-image: url('data:...');"></div>
<img src="data:..."/>
*/
});
```
## Installation
```sh
npm install inline-html
```
## API
- [`inlineHtml`](#inlineHtml)
- [`inline.html`](#html)
- [`inline.file`](#file)
- [`Results`](#results)
---
<a name="inlineHtml"/>
### inlineHtml ( html [, options] )
<a name="html"/>
### inline.html ( html [, options] )
Reads an HTML file and embeds referenced local assets into the HTML.
Parses an HTML string and embeds referenced local assets into the HTML.
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#Results) depending on the value of `options.verbose`.
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#results) depending on the value of `options.verbose`.
__Arguments__
- `html` - An HTML string or a filename of an HTML file to inline. Relative file paths are resolved relative to `options.filename` if a string or the filename's directory if a filename.
- `html` - An HTML string to inline.
- `options`
- `filename` - The filename used to resolve relative paths when `html` is a string. If `html` is a string and this option is not provided, relative paths will be resolved relative to the process's current working directory.
- `filename` - The filename used to resolve relative paths. If this option is not provided, relative paths will be resolved relative to the process's current working directory.
- `less` - An object containing LESS options to pass to the less compiler. Defaults to `{}`.
- `verbose` - A boolean that determines the promises fulfillment value. Supported values are:
- `true`: An instance of [`Results`](#Results).
- `false`: An `html` string. (_default_)
- `true`: An instance of [`Results`](#results).
- `false`: An `html` string. (_Default_)
<a name="Results"/>
__Results__
__Example__
The `Promise` returned by this function is optionally fulfilled with a `results` object that has the following properties:
```js
co(function * () {
var html = yield inline.html(`<img src="test.png">`);
console.log(html); // <img src="data:...">
});
```
---
<a name="file"/>
### inline.file ( filename [, options] )
Reads an HTML file and embeds referenced local assets into the HTML.
Returns a `Promise` that is fulfilled with an `html` string or an instance of [`Results`](#results) depending on the value of `options.verbose`.
__Arguments__
- `html` - A filename of an HTML file to inline. Relative file paths are resolved relative to the filename's directory.
- `options`
- `less` - An object containing LESS options to pass to the less compiler. Defaults to `{}`.
- `verbose` - A boolean that determines the promises fulfillment value. Supported values are:
- `true`: An instance of [`Results`](#results).
- `false`: An `html` string. (_Default_)
__Example__
```js
co(function * () {
html = yield inline.file(`index.html`);
console.log(html); // <img src="data:...">
});
```
---
<a name="results"/>
### Results
The `Promise` returned by these functions is optionally fulfilled with a `results` object that has the following properties:
- `html` - The inlined html
- `files` - An array of filenames for the local assets that were inlined.

25
lib/index.js
View File

@@ -6,30 +6,22 @@ var inlineLess = require('./inline-less');
var R = require('ramda');
var Ru = require('@panosoft/ramda-utils');
var inlineHtml = {};
/**
* Embed referenced local assets within and HTML file.
*
* @param {String} html
* Filename or html string.
* @param {Object} options
*
* @return {Promise}
*/
var inlineHtml = co.wrap(function * (html, options) {
inlineHtml.html = co.wrap(function * (html, options) {
options = Ru.defaults({
filename: null,
less: {},
verbose: false
}, options || {});
var filename;
try {
filename = html;
html = yield fs.readFile(filename, 'utf8');
}
catch (error) {
if (error.code === 'ENOENT') filename = options.filename;
else throw error;
}
var filename = options.filename;
// Embed assets
var files = [filename];
@@ -53,11 +45,14 @@ var inlineHtml = co.wrap(function * (html, options) {
}
files = R.uniq(files);
var result = {
html,
files
};
var result = { html, files };
return (options.verbose ? result : result.html);
});
inlineHtml.file = co.wrap(function * (filename, options) {
var html = yield fs.readFile(filename, 'utf8');
options = R.merge(options || {}, {filename});
return yield inlineHtml.html(html, options);
});
module.exports = inlineHtml;

7
test/fixtures/errors/lessImport/index.html vendored
View File

@@ -1,7 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet/less" href="main.less" />
</head>
<body></body>
</html>

9
test/fixtures/errors/lessSyntax/index.html vendored
View File

@@ -1,9 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet/less" href="main.less" />
</head>
<body>
</body>
</html>

9
test/fixtures/errors/lessUrl/index.html vendored
View File

@@ -1,9 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet/less" href="main.less" />
</head>
<body>
</body>
</html>

0
test/fixtures/errors/lessImport/main.less → test/fixtures/invalidImport.less vendored
View File

0
test/fixtures/errors/lessSyntax/main.less → test/fixtures/invalidSyntax.less vendored
View File

0
test/fixtures/errors/lessUrl/main.less → test/fixtures/invalidUrl.less vendored
View File

172
test/index.js
View File

@@ -7,78 +7,88 @@ var fs = require('fs');
var inline = require('../lib');
var path = require('path');
describe('inlineHtml', function () {
describe('inline-html', () => {
it('html: filename', function () {
describe('file()', () => {
it('exists', () => expect(inline).to.have.property('file').that.is.a('function'));
it('accept html filename', () => {
var filename = path.resolve(__dirname, './fixtures/file.txt');
var content = fs.readFileSync(filename, 'utf8');
return expect(inline(filename)).to.eventually.equal(content);
return expect(inline.file(filename)).to.eventually.equal(content);
});
it('html: string', function () {
it('options.filename: ignored for css url path resolution', () => {
var filename = path.resolve(__dirname, 'fixtures/css-url.html'); // file contains url path relative to itself
var options = { filename: __filename }; // sets filename relative to this test file
return expect(inline.file(filename, options)).to.eventually.match(/"data:.*,.*"/);
});
it('options.filename: ignored for img src path resolution', () => {
var filename = path.resolve(__dirname, 'fixtures/img.html'); // file contains src relative to itself
var options = { filename: __filename }; // sets filename relative to this test file
return expect(inline.file(filename, options)).to.eventually.match(/"data:.*,.*"/);
});
it('throw error when file not found', () => expect(inline.file('missing.html')).to.eventually.be.rejected);
});
describe('html()', () => {
it('exists', () => expect(inline).to.have.property('html').that.is.a('function'));
it('accept html string', () => {
var html = 'HTML';
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('inline link less', function () {
it('inline link less', () => {
var filename = path.resolve(__dirname, 'fixtures/basic.less');
var html = `<link rel="stylesheet/less" href="${filename}"/>`;
return expect(inline(html)).to.eventually.match(/<style>[^]*<\/style>/);
return expect(inline.html(html)).to.eventually.match(/<style>[^]*<\/style>/);
});
it('inline link less imports', function () {
it('inline link less imports', () => {
var filename = path.resolve(__dirname, 'fixtures/import.less');
var html = `<link rel="stylesheet/less" href="${filename}"/>`;
return expect(inline(html)).to.eventually.match(/<style>[^]*<\/style>/)
return expect(inline.html(html)).to.eventually.match(/<style>[^]*<\/style>/)
.and.not.match(/@import/);
});
it('inline css url path in style element', function () {
it('inline css url path in style element', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<style>div {background-image: url("${filename}");}</style>`;
return expect(inline(html)).to.eventually.match(/data:.*,.*/);
return expect(inline.html(html)).to.eventually.match(/data:.*,.*/);
});
it('inline css url path in element style attribute', function () {
it('inline css url path in element style attribute', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<div style="background-image: url('${filename}');"></div>`;
return expect(inline(html)).to.eventually.match(/data:.*,.*/);
return expect(inline.html(html)).to.eventually.match(/data:.*,.*/);
});
it('inline img src', function () {
it('inline img src', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<img src="${filename}"/>`;
return expect(inline(html)).to.eventually.match(/data:.*,.*/);
return expect(inline.html(html)).to.eventually.match(/data:.*,.*/);
});
it('options.verbose: return results object if true', function () {
it('options.verbose: return results object if true', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<img src="${filename}"/>`;
var options = { verbose: true };
return expect(inline(html, options)).to.eventually.be.an('object')
return expect(inline.html(html, options)).to.eventually.be.an('object')
.that.contains.keys(['html', 'files']);
});
it('options.verbose: return html if false', function () {
it('options.verbose: return html if false', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<img src="${filename}"/>`;
var options = { verbose: false };
return expect(inline(html, options)).to.eventually.be.a('string');
return expect(inline.html(html, options)).to.eventually.be.a('string');
});
it('options.verbose: default false', function () {
it('options.verbose: default false', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<img src="${filename}"/>`;
return expect(inline(html)).to.eventually.be.a('string');
return expect(inline.html(html)).to.eventually.be.a('string');
});
it('options.filename: ignored for css url path resolution if html filename', function () {
var html = path.resolve(__dirname, 'fixtures/css-url.html'); // file contains url path relative to itself
var options = { filename: __filename }; // sets filename relative to this test file
return expect(inline(html, options)).to.eventually.match(/"data:.*,.*"/);
});
it('options.filename: ignored for img src path resolution if html filename', function () {
var html = path.resolve(__dirname, 'fixtures/img.html'); // file contains src relative to itself
var options = { filename: __filename }; // sets filename relative to this test file
return expect(inline(html, options)).to.eventually.match(/"data:.*,.*"/);
});
it('options.filename: set basepath for css url path resolution if html string', function () {
it('options.filename: set basepath for css url path resolution', () => {
var filename = path.resolve(__dirname, 'fixtures/fake.html');
var dirname = path.dirname(filename);
@@ -87,9 +97,9 @@ describe('inlineHtml', function () {
var html = (path) => `<style>div { background-image: url('${path}'); }</style>`;
var options = { filename: filename };
return expect(inline(html(url), options)).to.eventually.equal(html(uri));
return expect(inline.html(html(url), options)).to.eventually.equal(html(uri));
});
it('options.filename: set basepath for img src path resolution if html string', function () {
it('options.filename: set basepath for img src path resolution', () => {
var filename = path.resolve(__dirname, 'fixtures/fake.html');
var dirname = path.dirname(filename);
@@ -98,81 +108,81 @@ describe('inlineHtml', function () {
var html = (path) => `<img src="${path}"/>`;
var options = { filename: filename };
return expect(inline(html(url), options)).to.eventually.equal(html(uri));
return expect(inline.html(html(url), options)).to.eventually.equal(html(uri));
});
it('options.filename: default to cwd for css url path resolution if html string', function () {
it('options.filename: default to cwd for css url path resolution', () => {
var url = 'test/fixtures/file.txt'; // Note: this is relative to cwd
var uri = datauri(url);
var html = (path) => `<style>div { background-image: url('${path}'); }</style>`;
return expect(inline(html(url))).to.eventually.equal(html(uri));
return expect(inline.html(html(url))).to.eventually.equal(html(uri));
});
it('options.filename: default to cwd for img src path resolution if html string', function () {
it('options.filename: default to cwd for img src path resolution', () => {
var url = 'test/fixtures/file.txt'; // Note: path relative to cwd
var uri = datauri(url);
var html = (path) => `<img src="${path}"/>`;
return expect(inline(html(url))).to.eventually.equal(html(uri));
return expect(inline.html(html(url))).to.eventually.equal(html(uri));
});
it('options.filename: included in results.files for img src if html string and options.verbose true', function () {
it('options.filename: included in results.files for img src if options.verbose true', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<img src="${filename}"/>`;
var options = { verbose: true };
return expect(inline(html, options)).to.eventually.have.property('files')
return expect(inline.html(html, options)).to.eventually.have.property('files')
.that.is.an('array')
.that.contains(filename);
});
it('options.filename: included in results.files for css url path if html string and options.verbose true', function () {
it('options.filename: included in results.files for css url path if options.verbose true', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var html = `<style>div { background-image: url('${filename}'); }</style>`;
var options = { verbose: true };
return expect(inline(html, options)).to.eventually.have.property('files')
return expect(inline.html(html, options)).to.eventually.have.property('files')
.that.is.an('array')
.that.contains(filename);
});
it('preserve self closing tags', function () {
it('preserve self closing tags', () => {
var html = '<br/>';
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('preserve partials', function () {
it('preserve partials', () => {
var html = '{{> partial}}';
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('preserve helpers', function () {
it('preserve helpers', () => {
var html = '{{helper}}';
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('ignore css url remote paths', function () {
it('ignore css url remote paths', () => {
var html = `<style> div { background-image: url('http://test.com/file.txt?query=string#hash'); }</style>`;
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('ignore img src remote paths', function () {
it('ignore img src remote paths', () => {
var html = `<img src="http://test.com/file.txt?query=string#hash"/>`;
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('ignore css url template expression paths', function () {
it('ignore css url template expression paths', () => {
var html = `<style> div { background-image: url({{path}}); }</style>`;
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('ignore img src template expression paths', function () {
it('ignore img src template expression paths', () => {
var html = `<img src="{{path}}"/>`;
return expect(inline(html)).to.eventually.equal(html);
return expect(inline.html(html)).to.eventually.equal(html);
});
it('ignore query strings and hashes on local paths', function () {
it('ignore query strings and hashes on local paths', () => {
var filename = path.resolve(__dirname, 'fixtures/file.txt');
var url = `${filename}?query=string#hash`;
var uri = datauri(filename);
var html = (source) => `<style> div { background-image: url('${source}'); }</style>`;
return expect(inline(html(url))).to.eventually.equal(html(uri));
return expect(inline.html(html(url))).to.eventually.equal(html(uri));
});
it('handle assets with a space in their filename', function () {
it('handle assets with a space in their filename', () => {
var filename = path.resolve(__dirname, 'fixtures/file space.txt');
var uri = datauri(filename);
var html = (source) => `<style> div { background-image: url('${source}'); }</style>`;
return expect(inline(html(filename))).to.eventually.equal(html(uri));
return expect(inline.html(html(filename))).to.eventually.equal(html(uri));
});
// Error handling
@@ -184,7 +194,7 @@ describe('inlineHtml', function () {
var html = `<img src="${source}" >`;
var resolvedSource = path.resolve(path.dirname(filename), source);
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -199,7 +209,7 @@ describe('inlineHtml', function () {
var filename = path.resolve(__dirname, 'index.html');
var html = `<div style="background url()"></div>`;
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -215,7 +225,7 @@ describe('inlineHtml', function () {
var resolvedUrl = path.resolve(path.dirname(filename), url);
var html = `<div style="background-image: url('${url}')"></div>`;
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -229,7 +239,7 @@ describe('inlineHtml', function () {
var filename = path.resolve(__dirname, 'index.html');
var html = `<style>div {</style>`;
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -245,7 +255,7 @@ describe('inlineHtml', function () {
var resolvedUrl = path.resolve(path.dirname(filename), url);
var html = `<style>div { background-image: url('${url}'); }</style>`;
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -262,7 +272,7 @@ describe('inlineHtml', function () {
var resolvedHref = path.resolve(path.dirname(filename), href);
var html = `<link rel="stylesheet/less" href="${href}">`;
try {
yield inline(html, {filename});
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -273,10 +283,12 @@ describe('inlineHtml', function () {
});
it('throw error when less import invalid', () => {
return co(function * () {
var filename = path.resolve(__dirname, 'fixtures/errors/lessImport/index.html');
var lessFilename = path.resolve(path.dirname(filename), 'main.less');
var filename = path.resolve(__dirname, 'fixtures/index.html');
var lessBasename = 'invalidImport.less';
var lessFilename = path.resolve(path.dirname(filename), lessBasename);
var html = `<link rel="stylesheet/less" href="${lessBasename}">`;
try {
yield inline(filename);
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -287,10 +299,12 @@ describe('inlineHtml', function () {
});
it('throw error when less syntax invalid', () => {
return co(function * () {
var filename = path.resolve(__dirname, 'fixtures/errors/lessSyntax/index.html');
var lessFilename = path.resolve(path.dirname(filename), 'main.less');
var filename = path.resolve(__dirname, 'fixtures/index.html');
var lessBasename = 'invalidSyntax.less';
var lessFilename = path.resolve(path.dirname(filename), lessBasename);
var html = `<link rel="stylesheet/less" href="${lessBasename}">`;
try {
yield inline(filename);
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -301,11 +315,13 @@ describe('inlineHtml', function () {
});
it('throw error when less url invalid', () => {
return co(function * () {
var filename = path.resolve(__dirname, 'fixtures/errors/lessUrl/index.html');
var lessFilename = path.resolve(path.dirname(filename), 'main.less');
var filename = path.resolve(__dirname, 'fixtures/index.html');
var lessBasename = 'invalidUrl.less';
var lessFilename = path.resolve(path.dirname(filename), lessBasename);
var badUrl = path.resolve(path.dirname(filename), 'missing.png');
var html = `<link rel="stylesheet/less" href="${lessBasename}">`;
try {
yield inline(filename);
yield inline.html(html, {filename});
throw new Error('No error thrown');
}
catch (error) {
@@ -317,3 +333,5 @@ describe('inlineHtml', function () {
});
});
});
});