README.md 6.79 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 8 9 10 11 12
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.

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

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

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

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 60 61 62 63 64 65 66 67 68 69
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 = {
		auto: false
		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

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>
97
<script>
Fred Chasen's avatar
Fred Chasen committed
98
	class MyHandler extends Paged.Handler {
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);
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)

118
// Chunker
Fred Chasen's avatar
Fred Chasen committed
119
beforeParsed(content)
120
filter(content)
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)
128 129
beforeTreeWalk(ast)
afterTreeWalk(ast, sheet)
130 131 132 133 134
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode)
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)
135 136 137

// Layout
layoutNode(node)
138
renderNode(node, sourceNode, layout)
139 140
onOverflow(overflow, rendered, bounds)
onBreakToken(breakToken, overflow, rendered)
141 142
```

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

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

Fred Chasen's avatar
Fred Chasen committed
155
## Deployment
Fred Chasen's avatar
Fred Chasen committed
156
Build the `dist` output
Fred Chasen's avatar
Fred Chasen committed
157
```sh
Fred Chasen's avatar
Fred Chasen committed
158 159 160 161 162 163 164 165 166 167 168
$ 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
169
```
Fred Chasen's avatar
Fred Chasen committed
170

171 172
## Testing

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

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

189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
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
```

Fred Chasen's avatar
Fred Chasen committed
206
To test the pdf output of specs, you'll need to build the library locally.
207 208

```bash
Fred Chasen's avatar
Fred Chasen committed
209
npm run build
210 211 212 213 214
```

Then run the jest tests in puppeteer.

```bash
Fred Chasen's avatar
Fred Chasen committed
215
npm run specs
216 217 218 219 220
```

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

```bash
Fred Chasen's avatar
Fred Chasen committed
221
NODE_ENV=debug npm run specs
222 223 224 225 226
```

To update the stored pdf images you can run

```bash
Fred Chasen's avatar
Fred Chasen committed
227
npm run specs -- --updateSnapshot
228
```
Fred Chasen's avatar
Fred Chasen committed
229 230 231 232 233 234 235 236

### 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
237
docker build -t pagedmedia/pagedjs .
Fred Chasen's avatar
Fred Chasen committed
238 239 240 241 242 243 244 245 246
```

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
247

Fred Chasen's avatar
Fred Chasen committed
248 249 250
```bash
docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test
```
251

252
## Contributors
253 254 255 256 257 258

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

259
MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)