README.md 4.17 KB
Newer Older
Fred Chasen's avatar
Fred Chasen committed
1
Paged.js - Paged Media Tools
Fred Chasen's avatar
Fred Chasen committed
2 3
===========

Fred Chasen's avatar
Fred Chasen committed
4 5 6 7 8 9
## NPM Module
```sh
$ npm install pagedjs
```

```js
10
import { Previewer } from 'pagedjs';
Fred Chasen's avatar
Fred Chasen committed
11

12 13
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
14 15 16 17
	console.log("Rendered", flow.total, "pages.");
})
```

Fred Chasen's avatar
Fred Chasen committed
18
## Polyfill
Fred Chasen's avatar
Fred Chasen committed
19

Fred Chasen's avatar
Fred Chasen committed
20
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
21 22 23 24 25

```html
<script src="https://s3.amazonaws.com/pagedmedia/pagedjs/dist/paged.polyfill.js"></script>
```

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

## Chunker
Chunks up a document into paged media flows and applies print classes.

Fred Chasen's avatar
Fred Chasen committed
31
Examples:
Fred Chasen's avatar
Fred Chasen committed
32

Fred Chasen's avatar
Fred Chasen committed
33 34
* 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
35

Fred Chasen's avatar
Fred Chasen committed
36
## Polisher
Fred Chasen's avatar
Fred Chasen committed
37 38
Converts `@page` css to classes, and applies counters and content.

Fred Chasen's avatar
Fred Chasen committed
39 40 41
Examples:

* Test [styles for print](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polisher.html).
Fred Chasen's avatar
Fred Chasen committed
42 43 44 45

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

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
## 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
<script src="https://s3.amazonaws.com/pagedmedia/pagedjs/dist/paged.polyfill.js"></script>
<script>
	class myHandler() extends Paged.Handler {
		constructor(chunker, polisher, caller) {
			super(chunker, polisher, caller);
		}

		afterPageLayout(pageFragment, page) {
			console.log(pageFragment);
		}
	}
	Paged.registerHandlers(myHandler);
</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
afterParsed(parsed)
beforePageLayout(page)
afterPageLayout(pageElement, page, breakToken)
afterRendered(pages)

// Polisher
onUrl(urlNode)
onAtPage(atPageNode)
onRule(ruleNode)
onDeclaration(declarationNode, ruleNode)
onContent(contentNode, declarationNode, ruleNode)
```

Fred Chasen's avatar
Fred Chasen committed
86 87 88 89 90 91 92
## Setup
Install dependencies
```sh
$ npm install
```

## Development
93
Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
Fred Chasen's avatar
Fred Chasen committed
94 95 96
```sh
$ npm start
```
Fred Chasen's avatar
Fred Chasen committed
97

Fred Chasen's avatar
Fred Chasen committed
98
## Deployment
Fred Chasen's avatar
Fred Chasen committed
99
Build the `dist` output
Fred Chasen's avatar
Fred Chasen committed
100
```sh
Fred Chasen's avatar
Fred Chasen committed
101
$ npm run prepare
Fred Chasen's avatar
Fred Chasen committed
102
```
Fred Chasen's avatar
Fred Chasen committed
103

104 105
## Testing

Fred Chasen's avatar
Fred Chasen committed
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
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.
123 124 125

```bash
brew install ghostscript
Fred Chasen's avatar
Fred Chasen committed
126
npm install ghostscript4js --no-save
127 128 129 130 131
```

Then run the jest tests in puppeteer.

```bash
Fred Chasen's avatar
Fred Chasen committed
132
npm run specs
133 134 135 136 137
```

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

```bash
Fred Chasen's avatar
Fred Chasen committed
138
NODE_ENV=debug npm run specs
139 140 141 142 143
```

To update the stored pdf images you can run

```bash
Fred Chasen's avatar
Fred Chasen committed
144
npm run specs -- --updateSnapshot
145
```
Fred Chasen's avatar
Fred Chasen committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

### 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`
 
```bash
docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test
```