README.md 5.41 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
===========

6 7


Fred Chasen's avatar
Fred Chasen committed
8 9 10 11 12 13
## NPM Module
```sh
$ npm install pagedjs
```

```js
14
import { Previewer } from 'pagedjs';
Fred Chasen's avatar
Fred Chasen committed
15

16 17
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
18 19 20 21
	console.log("Rendered", flow.total, "pages.");
})
```

Fred Chasen's avatar
Fred Chasen committed
22
## Polyfill
Fred Chasen's avatar
Fred Chasen committed
23

Fred Chasen's avatar
Fred Chasen committed
24
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
25 26

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

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

Fred Chasen's avatar
Fred Chasen committed
32 33 34 35 36 37 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
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
64 65 66
## Chunker
Chunks up a document into paged media flows and applies print classes.

Fred Chasen's avatar
Fred Chasen committed
67
Examples:
Fred Chasen's avatar
Fred Chasen committed
68

Fred Chasen's avatar
Fred Chasen committed
69 70
* 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
71

Fred Chasen's avatar
Fred Chasen committed
72
## Polisher
Fred Chasen's avatar
Fred Chasen committed
73 74
Converts `@page` css to classes, and applies counters and content.

Fred Chasen's avatar
Fred Chasen committed
75 76 77
Examples:

* Test [styles for print](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polisher.html).
Fred Chasen's avatar
Fred Chasen committed
78 79 80 81

### CLI

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

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

		afterPageLayout(pageFragment, page) {
			console.log(pageFragment);
		}
	}
Fred Chasen's avatar
Fred Chasen committed
101
	Paged.registerHandlers(MyHandler);
102 103 104 105 106 107 108
</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
109
beforeParsed(content)
110 111 112 113 114 115
afterParsed(parsed)
beforePageLayout(page)
afterPageLayout(pageElement, page, breakToken)
afterRendered(pages)

// Polisher
Fred Chasen's avatar
Fred Chasen committed
116
beforeTreeParse(text, sheet)
117 118
beforeTreeWalk(ast)
afterTreeWalk(ast, sheet)
119 120 121 122 123 124 125
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode)
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)
```

Fred Chasen's avatar
Fred Chasen committed
126 127 128 129 130 131 132
## Setup
Install dependencies
```sh
$ npm install
```

## Development
133
Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
Fred Chasen's avatar
Fred Chasen committed
134 135 136
```sh
$ npm start
```
Fred Chasen's avatar
Fred Chasen committed
137

Fred Chasen's avatar
Fred Chasen committed
138
## Deployment
Fred Chasen's avatar
Fred Chasen committed
139
Build the `dist` output
Fred Chasen's avatar
Fred Chasen committed
140
```sh
Fred Chasen's avatar
Fred Chasen committed
141
$ npm run prepare
Fred Chasen's avatar
Fred Chasen committed
142
```
Fred Chasen's avatar
Fred Chasen committed
143

144 145
## Testing

Fred Chasen's avatar
Fred Chasen committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
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).

To test the pdf output of specs, you'll need to install ghostscript locally.
163 164 165

```bash
brew install ghostscript
Fred Chasen's avatar
Fred Chasen committed
166
npm install ghostscript4js --no-save
167 168 169 170 171
```

Then run the jest tests in puppeteer.

```bash
Fred Chasen's avatar
Fred Chasen committed
172
npm run specs
173 174 175 176 177
```

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

```bash
Fred Chasen's avatar
Fred Chasen committed
178
NODE_ENV=debug npm run specs
179 180 181 182 183
```

To update the stored pdf images you can run

```bash
Fred Chasen's avatar
Fred Chasen committed
184
npm run specs -- --updateSnapshot
185
```
Fred Chasen's avatar
Fred Chasen committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

### 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
docker build -t pagedmedia/pagedjs .  
```

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
204

Fred Chasen's avatar
Fred Chasen committed
205 206 207
```bash
docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test
```
208

209
## Contributors
210 211 212 213 214 215

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

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