README.md 7.78 KB
Newer Older
julien's avatar
julien committed
1
<img style="display: block; margin: 5em 0 auto;" src="https://www.pagedmedia.org/wp-content/uploads/2018/11/pagedjs.png" alt="Paged.js logo - pagination in the browser"/>
2

Fred Chasen's avatar
Fred Chasen committed
3
Paged.js - Paged Media Tools
Fred Chasen's avatar
Fred Chasen committed
4 5
===========

Fred Chasen's avatar
Fred Chasen committed
6 7
Paged.js is an open-source library to display paginated content in the browser and to generate print books using web technology.

Thomas Parisot's avatar
Thomas Parisot committed
8
It contains a set of handlers for CSS transformations and fragmented layout which polyfill the [CSS Paged Media][] and [CSS Generated Content][] CSS modules, along with hooks to create new handlers for custom properties.
Fred Chasen's avatar
Fred Chasen committed
9 10 11 12

The currently supported properties can be found on [the wiki](https://gitlab.pagedmedia.org/tools/pagedjs/wikis/Support-of-specifications).

A quick overview to getting started with Paged Media CSS and Paged.js is available on [pagedmedia.org](https://www.pagedmedia.org/paged-js/).
13

Thomas Parisot's avatar
Thomas Parisot committed
14
## Install
Fred Chasen's avatar
Fred Chasen committed
15

Thomas Parisot's avatar
Thomas Parisot committed
16 17
Paged.js is available via a CDN like [jsDelivr][] or [unpkg][] for a quick use.
See below for how to use it.
Fred Chasen's avatar
Fred Chasen committed
18

Thomas Parisot's avatar
Thomas Parisot committed
19 20 21 22
You can also integrate Paged.js with your toolchain [via NPM][npm].

```bash
$ npm install pagedjs
Fred Chasen's avatar
Fred Chasen committed
23 24
```

Thomas Parisot's avatar
Thomas Parisot committed
25

Fred Chasen's avatar
Fred Chasen committed
26
## Polyfill
Fred Chasen's avatar
Fred Chasen committed
27

Thomas Parisot's avatar
Thomas Parisot committed
28 29
The polyfill is the easiest way to replace all `@page` css. It renders the html page according to the [CSS Paged Media][] spec.
The polyfill runs automatically as soon as the DOM is ready.
Fred Chasen's avatar
Fred Chasen committed
30 31

```html
Fred Chasen's avatar
Fred Chasen committed
32
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
Fred Chasen's avatar
Fred Chasen committed
33 34
```

Thomas Parisot's avatar
Thomas Parisot committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
See it in action with the [Aurorae book](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).

Use the `auto` configuration property of the `PagedConfig` object to render only when `PagedPolyfill.preview()` is called.

```html
<script>
	// disable the polyfill before loading its script
	window.PagedConfig = {
		auto: false
	};
</script>
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script>
	// do something else
	// ...

	// then runs the pollyfill manually
	PagedPolyfill.preview();
</script>
```
Fred Chasen's avatar
Fred Chasen committed
55

Thomas Parisot's avatar
Thomas Parisot committed
56
Alternativelly, delay the rendering until the `before` configuration property of the `PagedConfig` object is resolved.
Fred Chasen's avatar
Fred Chasen committed
57 58 59 60 61

```html
<script>
	window.PagedConfig = {
		before: () => {
Thomas Parisot's avatar
Thomas Parisot committed
62 63 64 65 66 67
			return new Promise(resolve) {
				// do something before the rendering
				// ...

				// then runs the polyfill
				resolve();
Fred Chasen's avatar
Fred Chasen committed
68
			}
Thomas Parisot's avatar
Thomas Parisot committed
69
		}
Fred Chasen's avatar
Fred Chasen committed
70 71
	};
</script>
Thomas Parisot's avatar
Thomas Parisot committed
72
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
Fred Chasen's avatar
Fred Chasen committed
73 74
```

Thomas Parisot's avatar
Thomas Parisot committed
75
### ECMAScript Module
Fred Chasen's avatar
Fred Chasen committed
76 77 78 79 80 81

```html
<script>
	window.PagedConfig = {
		auto: false
	};
Thomas Parisot's avatar
Thomas Parisot committed
82 83 84
</script>
<script>
	import PagedPolyfill from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';
Fred Chasen's avatar
Fred Chasen committed
85

Thomas Parisot's avatar
Thomas Parisot committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
	// ...

	PagedPolyfill.preview();
</script>
```

## Previewer

```js
import { Previewer } from 'pagedjs';

let paged = new Previewer();
let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
	console.log("Rendered", flow.total, "pages.");
});
```

### ECMAScript Module

```html
<script type="module">
	import { Previewer } from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';

	let paged = new Previewer();
	// ...
Fred Chasen's avatar
Fred Chasen committed
111 112 113
</script>
```

Fred Chasen's avatar
Fred Chasen committed
114 115 116
## Chunker
Chunks up a document into paged media flows and applies print classes.

Fred Chasen's avatar
Fred Chasen committed
117
Examples:
Fred Chasen's avatar
Fred Chasen committed
118

Fred Chasen's avatar
Fred Chasen committed
119 120
* Process the [first 50 pages of Moby Dick](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/index.html).
* Upload and [chunk an Epub using Epub.js](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/epub.html).
Fred Chasen's avatar
Fred Chasen committed
121

Fred Chasen's avatar
Fred Chasen committed
122
## Polisher
Fred Chasen's avatar
Fred Chasen committed
123 124
Converts `@page` css to classes, and applies counters and content.

Fred Chasen's avatar
Fred Chasen committed
125 126 127
Examples:

* Test [styles for print](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polisher.html).
Fred Chasen's avatar
Fred Chasen committed
128 129 130

### CLI

Thomas Parisot's avatar
Thomas Parisot committed
131
[`pagedjs-cli`](https://gitlab.pagedmedia.org/polyfills/pagedjs-cli) is a command line interface to render out PDFs of HTML files. It uses [Puppeteer][] under the hood.
Fred Chasen's avatar
Fred Chasen committed
132

133 134 135 136 137 138 139
## Modules

Modules are groups of handlers for that apply the layout and styles of a CSS module, such as Generated Content.

New handlers can be registered from `import { registerHandlers } from 'pagedjs'` or by calling `Paged.registerHandlers` on an html page.

```html
Thomas Parisot's avatar
Thomas Parisot committed
140 141 142 143
<script type="module">
	import {Handler, registerHandlers} from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';

	class MyHandler extends Handler {
144 145 146 147 148 149 150 151
		constructor(chunker, polisher, caller) {
			super(chunker, polisher, caller);
		}

		afterPageLayout(pageFragment, page) {
			console.log(pageFragment);
		}
	}
Thomas Parisot's avatar
Thomas Parisot committed
152 153

	registerHandlers(MyHandler);
154 155 156 157 158 159 160
</script>
```

Handlers have methods that correspond to the hooks for the parsing, layout and rendering of the Chunker and Polisher. Returning an promise or `async` function from a method in a handler will complete that task before continuing with the other registered methods for that hook.

```js
// Chunker
Fred Chasen's avatar
Fred Chasen committed
161
beforeParsed(content)
162 163 164 165 166 167
afterParsed(parsed)
beforePageLayout(page)
afterPageLayout(pageElement, page, breakToken)
afterRendered(pages)

// Polisher
Fred Chasen's avatar
Fred Chasen committed
168
beforeTreeParse(text, sheet)
169 170
beforeTreeWalk(ast)
afterTreeWalk(ast, sheet)
171 172 173 174 175
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode)
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)
176 177 178 179 180 181

// Layout
layoutNode(node)
renderNode(node, sourceNode)
onOverflow(overflow, rendered, bounds)
onBreakToken(breakToken, overflow, rendered)
182 183
```

Thomas Parisot's avatar
Thomas Parisot committed
184 185
## Local Development

Fred Chasen's avatar
Fred Chasen committed
186 187 188 189 190
Install dependencies
```sh
$ npm install
```

191
Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
Thomas Parisot's avatar
Thomas Parisot committed
192

Fred Chasen's avatar
Fred Chasen committed
193 194 195
```sh
$ npm start
```
Fred Chasen's avatar
Fred Chasen committed
196

Fred Chasen's avatar
Fred Chasen committed
197
## Deployment
Fred Chasen's avatar
Fred Chasen committed
198
Build the `dist` output
Fred Chasen's avatar
Fred Chasen committed
199
```sh
Fred Chasen's avatar
Fred Chasen committed
200
$ npm run prepare
Fred Chasen's avatar
Fred Chasen committed
201
```
Fred Chasen's avatar
Fred Chasen committed
202

203 204
## Testing

Fred Chasen's avatar
Fred Chasen committed
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
Testing for Paged.js uses [Jest](https://facebook.github.io/jest/en/) but is split into Tests and Specs.

### Tests

Unit tests for Chunker and Polisher methods are run in node using JSDOM.

```bash
npm run tests
```

### Specs

Specs run a html file in Chrome (using puppeteer) to test against CSS specifications.

They can also output a pdf and compare pages (one at a time) in that PDF with samples PDFs (saved as images).

221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
The PDF comparison tests depend on the `ghostscript` and the `ghostscript4js` package.

To run them you'll need to install a local version of Ghostscript for you system according to https://www.npmjs.com/package/ghostscript4js#prerequisites

For Mac you can install it with

```bash
brew install ghostscript
```

For Debian you can install it with

```bash
sudo apt-get install ghostscript
sudo apt-get install libgs-dev
```

Then you can install the node library

```bash
npm install ghostscript4js --no-save
```

Fred Chasen's avatar
Fred Chasen committed
244
To test the pdf output of specs, you'll need to build the library locally.
245 246

```bash
Fred Chasen's avatar
Fred Chasen committed
247
npm run build
248 249 250 251 252
```

Then run the jest tests in puppeteer.

```bash
Fred Chasen's avatar
Fred Chasen committed
253
npm run specs
254 255 256 257 258
```

To debug the results of a test in a browser you can add `NODE_ENV=debug`

```bash
Fred Chasen's avatar
Fred Chasen committed
259
NODE_ENV=debug npm run specs
260 261 262 263 264
```

To update the stored pdf images you can run

```bash
Fred Chasen's avatar
Fred Chasen committed
265
npm run specs -- --updateSnapshot
266
```
Fred Chasen's avatar
Fred Chasen committed
267 268 269

### Docker

Thomas Parisot's avatar
Thomas Parisot committed
270
A [`pagedmedia/pagedjs` docker image][docker-image] contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests.
Fred Chasen's avatar
Fred Chasen committed
271 272 273 274

To build the image run

```bash
Thomas Parisot's avatar
Thomas Parisot committed
275
docker build -t pagedmedia/pagedjs .
Fred Chasen's avatar
Fred Chasen committed
276 277 278 279 280 281 282 283 284
```

By default the container will run the development server with `npm start`

```bash
docker run -it -p 9090:9090 pagedmedia/pagedjs
```

The tests and specs can be run within the container by passing a `seccomp` file for Chrome and running `npm test`
Fred Chasen's avatar
Fred Chasen committed
285

Fred Chasen's avatar
Fred Chasen committed
286 287 288
```bash
docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test
```
289

290
## Contributors
291 292 293 294 295 296

### Core team
The core team behind paged.js includes [Adam Hyde](https://adamhyde.net), [Julie Blanc](http://julie-blanc.fr/), [Fred Chasen](http://fchasen.com/) & Julien Taquet.

## Licence

297
MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)
Thomas Parisot's avatar
Thomas Parisot committed
298 299 300 301 302 303 304 305 306 307


[CSS Paged Media]: https://www.w3.org/TR/css-page-3/
[CSS Generated Content]: https://www.w3.org/TR/css-gcpm-3/
[Puppeteer]: https://pptr.dev/

[docker-image]: https://hub.docker.com/r/pagedmedia/pagedjs
[jsDelivr]: https://www.jsdelivr.com/package/npm/pagedjs
[unpkg]: https://unpkg.com/pagedjs
[via NPM]: https://npmjs.com/pagedjs