Skip to content

Commit fbff09d

Browse files
eKoopmanseKoopmans
committed
Merge branch 'release/v0.8.0'
2 parents ed00bd4 + e742939 commit fbff09d

20 files changed

+9885
-607
lines changed

‎.babelrc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"presets": [
3+
[
4+
"env",
5+
{
6+
"modules": false
7+
}
8+
]
9+
],
10+
"plugins": [
11+
"external-helpers"
12+
]
13+
}

‎.gitignore

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
1-
# https://git-scm.com/docs/gitignore
2-
# https://help.github.com/articles/ignoring-files
3-
# Example .gitignore files: https://github.com/github/gitignore
4-
/bower_components/
5-
/node_modules/
6-
7-
# Personal ignores
8-
/~archive/
9-
/~devel/
1+
node_modules/
2+
.archive/
3+
.devel/

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License
2+
3+
Copyright (c) 2017 Erik Koopmans
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,27 @@
22

33
html2pdf converts any webpage or element into a printable PDF entirely client-side using [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF).
44

5-
## Install
5+
## Getting started
66

7-
1. Copy `html2pdf.js` to your project directory.
8-
2. Fetch the dependencies `html2canvas` and `jsPDF`, which can be found in the `vendor` folder.
9-
3. Include the files in your HTML document (**order is important**, otherwise `jsPDF` will override `html2canvas` with its own internal implementation):
7+
There are two ways to install html2pdf:
108

11-
```html
12-
<script src="jspdf.min.js"></script>
13-
<script src="html2canvas.min.js"></script>
14-
<script src="html2pdf.js"></script>
15-
```
16-
17-
**Note:** For best results, use the custom build of `html2canvas` found in the `vendor` folder, which contains added features and hotfixes.
9+
1. **NPM:** Use `npm install --save html2pdf` to add html2pdf and its dependencies to your project.
10+
2. **HTML:** Download `dist/html2pdf.bundle.min.js` to your project folder and include it in your HTML with: `<script src="html2pdf.bundle.min.js"></script>`.
1811

19-
## Usage
20-
21-
### Basic usage
22-
23-
Including html2pdf exposes the `html2pdf` function. Calling it will create a PDF and prompt the user to save the file:
12+
Once installed, html2pdf is ready to use. This command will generate a PDF of `#element-to-print` and prompt the user to save the result:
2413

2514
```js
2615
var element = document.getElementById('element-to-print');
2716
html2pdf(element);
2817
```
2918

30-
The PDF can be configured using an optional `opt` parameter:
19+
*Note: html2pdf **will not run in Node.js**, it must be run in a browser.*
20+
21+
*[Click here](#dependencies) for more information about using the unbundled version `dist/html2canvas.min.js`.*
22+
23+
## Options
24+
25+
html2pdf can be configured using an optional `opt` parameter:
3126

3227
```js
3328
var element = document.getElementById('element-to-print');
@@ -42,18 +37,16 @@ html2pdf(element, {
4237

4338
The `opt` parameter has the following optional fields:
4439

45-
|Name |Type |Default |Description |
46-
|------------|----------------|------------------------------|---------------------------------------------------------------------------------------------|
47-
|margin |number or array |0 |PDF margin. Array can be either [vMargin, hMargin] or [top, left, bottom, right]. |
48-
|filename |string |'file.pdf' |The default filename of the exported PDF. |
49-
|image |object |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below. |
50-
|enableLinks |boolean |true |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
40+
|Name |Type |Default |Description |
41+
|------------|----------------|------------------------------|------------------------------------------------------------------------------------------------------------|
42+
|margin |number or array |0 |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
43+
|filename |string |'file.pdf' |The default filename of the exported PDF. |
44+
|image |object |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below. |
45+
|enableLinks |boolean |true |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
5146
|html2canvas |object |{ } |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/documentation.html#available-options) for usage).|
5247
|jsPDF |object |{ } |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
5348

54-
### Extra features
55-
56-
#### Page-breaks
49+
### Page-breaks
5750

5851
You may add `html2pdf`-specific page-breaks to your document by adding the CSS class `html2pdf__page-break` to any element (normally an empty `div`). For React elements, use `className=html2pdf__page-break`. During PDF creation, these elements will be given a height calculated to fill the remainder of the PDF page that they are on. Example usage:
5952

@@ -65,7 +58,7 @@ You may add `html2pdf`-specific page-breaks to your document by adding the CSS c
6558
</div>
6659
```
6760

68-
#### Image type and quality
61+
### Image type and quality
6962

7063
You may customize the image type and quality exported from the canvas by setting the `image` option. This must be an object with the following fields:
7164

@@ -78,9 +71,17 @@ These options are limited to the available settings for [HTMLCanvasElement.toDat
7871

7972
## Dependencies
8073

81-
html2pdf depends on the external packages [`html2canvas`](https://github.com/niklasvh/html2canvas) and [`jsPDF`](https://github.com/MrRio/jsPDF).
74+
html2pdf depends on the external packages [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF). These dependencies are automatically loaded when using NPM or the bundled package.
75+
76+
If using the unbundled `dist/html2pdf.min.js` (or its un-minified version), you must also include each dependency. Order is important, otherwise html2canvas will be overridden by jsPDF's own internal implementation:
77+
78+
```html
79+
<script src="jspdf.min.js"></script>
80+
<script src="html2canvas.min.js"></script>
81+
<script src="html2pdf.min.js"></script>
82+
```
8283

83-
For best results, use [this custom build](https://github.com/eKoopmans/html2canvas/tree/develop) of `html2canvas`, which includes bugfixes and adds support for box-shadows and custom resolutions (via the `dpi`/`scale` options).
84+
html2pdf currently uses [this fork](https://github.com/eKoopmans/html2canvas/tree/develop) of html2canvas to resolve a few bugs and add support for box-shadows and custom resolutions (via the `dpi`/`scale` options).
8485

8586
## Contributing
8687

@@ -90,7 +91,7 @@ When submitting an issue, please provide reproducible code that highlights the i
9091

9192
### Pull requests
9293

93-
Right now, html2pdf is a single source file located in `/src/`. If you want to create a new feature or bugfix, feel free to fork and submit a pull request!
94+
If you want to create a new feature or bugfix, please feel free to fork and submit a pull request! Use the [`develop`](/eKoopmans/html2pdf/tree/develop) branch, which features the latest development, and make changes to `/src/` rather than directly to `/dist/`. You can test your changes by rebuilding with `npm run build`.
9495

9596
## Credits
9697

0 commit comments

Comments
 (0)