README.md 7.2 KB
Newer Older
julientaq's avatar
julientaq 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
8
9
Paged.js is an open-source library to display paginated content in the browser and to generate print books using web technology.

It contains a set of handlers for CSS transformations and fragmented layout which polyfill the [Paged Media](https://www.w3.org/TR/css-page-3/) and [Generated Content](https://www.w3.org/TR/css-gcpm-3/) CSS modules, along with hooks to create new handlers for custom properties.

julientaq's avatar
julientaq committed
10
The currently supported properties can be found on [the pagedjs website](https://pagedjs.org/documentation/cheatsheet/).
Fred Chasen's avatar
Fred Chasen committed
11

julientaq's avatar
julientaq committed
12
A quick overview to getting started with Paged Media CSS and Paged.js is available on [pagedjs.org/documentation](https://pagedjs.org/documentation/).
13

Fred Chasen's avatar
Fred Chasen committed
14
15
16
17
18
19
## NPM Module
```sh
$ npm install pagedjs
```

```js
Fred Chasen's avatar
Fred Chasen committed
20
import { Previewer } from 'pagedjs';
Fred Chasen's avatar
Fred Chasen committed
21

Fred Chasen's avatar
Fred Chasen committed
22
23
let paged = new Previewer();
let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
Fred Chasen's avatar
Fred Chasen committed
24
25
26
27
	console.log("Rendered", flow.total, "pages.");
})
```

Fred Chasen's avatar
Fred Chasen committed
28
## Polyfill
Fred Chasen's avatar
Fred Chasen committed
29

Fred Chasen's avatar
Fred Chasen committed
30
Add the the `paged.polyfill.js` script to replace all `@page` css and render the html page with the Paged Media styles applied:
Fred Chasen's avatar
Fred Chasen committed
31
32

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

Fred Chasen's avatar
Fred Chasen committed
36
Try the [polyfill with Aurorae](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).
Fred Chasen's avatar
Fred Chasen committed
37

Fred Chasen's avatar
Fred Chasen committed
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
By default the polyfill will run automatically as soon as the DOM is ready.
However, you can add an async `before` function or return a Promise to delay the polyfill starting.

```html
<script>
	window.PagedConfig = {
		before: () => {
			return new Promise(resolve, reject) {
				setTimeout(() => { resolve() }, 1000);
			}
		},
		after: (flow) => { console.log("after", flow) },
	};
</script>
```

Otherwise you can disable `auto` running the previewer and call `window.PagedPolyfill.preview();`
whenever you want to start.

```html
<script>
	window.PagedConfig = {
60
		auto: false,
Fred Chasen's avatar
Fred Chasen committed
61
62
63
64
65
66
67
68
69
		after: (flow) => { console.log("after", flow) },
	};

	setTimeout(() => {
		window.PagedPolyfill.preview();
	}, 1000);
</script>
```

Fred Chasen's avatar
Fred Chasen committed
70
71
72
## Chunker
Chunks up a document into paged media flows and applies print classes.

Fred Chasen's avatar
Fred Chasen committed
73
Examples:
Fred Chasen's avatar
Fred Chasen committed
74

Fred Chasen's avatar
Fred Chasen committed
75
76
* 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
77

Fred Chasen's avatar
Fred Chasen committed
78
## Polisher
Fred Chasen's avatar
Fred Chasen committed
79
80
Converts `@page` css to classes, and applies counters and content.

Fred Chasen's avatar
Fred Chasen committed
81
82
83
Examples:

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

### CLI

Erik Schilling's avatar
Erik Schilling committed
87
Command line interface to render out PDFs of HTML files using Puppeteer: [https://gitlab.pagedmedia.org/tools/pagedjs-cli](https://gitlab.pagedmedia.org/tools/pagedjs-cli).
Fred Chasen's avatar
Fred Chasen committed
88

Fred Chasen's avatar
Fred Chasen committed
89
90
91
92
93
94
95
## 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
Fred Chasen's avatar
Fred Chasen committed
96
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
Fred Chasen's avatar
Fred Chasen committed
97
<script>
Fred Chasen's avatar
Fred Chasen committed
98
	class MyHandler extends Paged.Handler {
Fred Chasen's avatar
Fred Chasen committed
99
100
101
102
103
104
105
106
		constructor(chunker, polisher, caller) {
			super(chunker, polisher, caller);
		}

		afterPageLayout(pageFragment, page) {
			console.log(pageFragment);
		}
	}
Fred Chasen's avatar
Fred Chasen committed
107
	Paged.registerHandlers(MyHandler);
Fred Chasen's avatar
Fred Chasen committed
108
109
110
111
112
113
</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
114
115
116
117
// Previewer
beforePreview(content, renderTo)
afterPreview(pages)

Fred Chasen's avatar
Fred Chasen committed
118
// Chunker
Fred Chasen's avatar
Fred Chasen committed
119
beforeParsed(content)
Fred Chasen's avatar
Fred Chasen committed
120
filter(content)
Fred Chasen's avatar
Fred Chasen committed
121
122
123
124
125
126
afterParsed(parsed)
beforePageLayout(page)
afterPageLayout(pageElement, page, breakToken)
afterRendered(pages)

// Polisher
Fred Chasen's avatar
Fred Chasen committed
127
beforeTreeParse(text, sheet)
Fred Chasen's avatar
Fred Chasen committed
128
129
beforeTreeWalk(ast)
afterTreeWalk(ast, sheet)
Fred Chasen's avatar
Fred Chasen committed
130
131
132
133
134
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode)
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)
135
136
137

// Layout
layoutNode(node)
Fred Chasen's avatar
Fred Chasen committed
138
renderNode(node, sourceNode, layout)
139
140
onOverflow(overflow, rendered, bounds)
onBreakToken(breakToken, overflow, rendered)
Fred Chasen's avatar
Fred Chasen committed
141
afterOverflowRemoved(removed, rendered)
Fred Chasen's avatar
Fred Chasen committed
142
143
```

Fred Chasen's avatar
Fred Chasen committed
144
145
146
147
148
149
150
## Setup
Install dependencies
```sh
$ npm install
```

## Development
151
Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
Fred Chasen's avatar
Fred Chasen committed
152
153
154
```sh
$ npm start
```
Fred Chasen's avatar
Fred Chasen committed
155

Fred Chasen's avatar
Fred Chasen committed
156
## Deployment
Fred Chasen's avatar
Fred Chasen committed
157
Build the `dist` output
Fred Chasen's avatar
Fred Chasen committed
158
```sh
Fred Chasen's avatar
Fred Chasen committed
159
160
161
162
163
164
165
166
167
168
169
$ npm run build
```

Compile the `lib` output
```sh
$ npm run compile
```

Generate legacy builds with polyfills included
```sh
$ npm run legacy
Fred Chasen's avatar
Fred Chasen committed
170
```
Fred Chasen's avatar
Fred Chasen committed
171

Fred Chasen's avatar
Fred Chasen committed
172
173
## Testing

Fred Chasen's avatar
Fred Chasen committed
174
175
176
177
178
179
180
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
Fred Chasen's avatar
Fred Chasen committed
181
npm test
Fred Chasen's avatar
Fred Chasen committed
182
183
184
185
186
187
188
189
```

### 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).

190
191
The PDF comparison tests depend on the `ghostscript` and the `ghostscript4js` package.

192
193
194
195
196
197
198
It is recomend to run these in the Docker container below via:

```bash
npm run docker-specs
```

However if you'd like to run the specs outside of Docker, you'll need to install a local version of Ghostscript for your system according to https://www.npmjs.com/package/ghostscript4js#prerequisites
199
200
201
202
203
204
205
206
207
208
209
210
211
212

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
```

Fred Chasen's avatar
Fred Chasen committed
213
214
215
216
217
218
Now you can install the `ghostscript4js` library. For Linux you can optionally pass the location ghostscript was installed to in `GS4JS_HOME`.

```bash
GS4JS_HOME="/usr/lib/$(gcc -dumpmachine)" npm install ghostscript4js
```

Fred Chasen's avatar
Fred Chasen committed
219
To test the pdf output of specs, you'll need to build the library locally.
220
221

```bash
Fred Chasen's avatar
Fred Chasen committed
222
npm run build
223
224
225
226
227
```

Then run the jest tests in puppeteer.

```bash
Fred Chasen's avatar
Fred Chasen committed
228
npm run specs
229
230
231
232
233
```

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

```bash
Fred Chasen's avatar
Fred Chasen committed
234
NODE_ENV=debug npm run specs
235
236
237
238
239
```

To update the stored pdf images you can run

```bash
Fred Chasen's avatar
Fred Chasen committed
240
npm run specs -- --updateSnapshot
241
```
Fred Chasen's avatar
Fred Chasen committed
242
243
244
245
246
247
248
249

### Docker

A `pagedmedia/pagedjs` docker image contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests.

To build the image run

```bash
Fred Chasen's avatar
Fred Chasen committed
250
docker build -t pagedmedia/pagedjs .
Fred Chasen's avatar
Fred Chasen committed
251
252
253
254
255
256
257
258
259
```

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
260

Fred Chasen's avatar
Fred Chasen committed
261
```bash
262
docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test && npm run specs
Fred Chasen's avatar
Fred Chasen committed
263
```
264

Fred Chasen's avatar
Fred Chasen committed
265
## Contributors
266
267
268
269
270
271

### 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

Fred Chasen's avatar
Fred Chasen committed
272
MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)