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 |
|
3 | Paged.js - Paged Media Tools
|
4 | ===========
|
5 |
|
6 |
|
7 |
|
8 | ## NPM Module
|
9 | ```sh
|
10 | $ npm install pagedjs
|
11 | ```
|
12 |
|
13 | ```js
|
14 | import { Previewer } from 'pagedjs';
|
15 |
|
16 | let paged = new Previewer();
|
17 | let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
|
18 | console.log("Rendered", flow.total, "pages.");
|
19 | })
|
20 | ```
|
21 |
|
22 | ## Polyfill
|
23 |
|
24 | Add the the `paged.polyfill.js` script to replace all `@page` css and render the html page with the Paged Media styles applied:
|
25 |
|
26 | ```html
|
27 | <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
|
28 | ```
|
29 |
|
30 | Try the [polyfill with Aurorae](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).
|
31 |
|
32 | By default the polyfill will run automatically as soon as the DOM is ready.
|
33 | However, you can add an async `before` function or return a Promise to delay the polyfill starting.
|
34 |
|
35 | ```html
|
36 | <script>
|
37 | window.PagedConfig = {
|
38 | before: () => {
|
39 | return new Promise(resolve, reject) {
|
40 | setTimeout(() => { resolve() }, 1000);
|
41 | }
|
42 | },
|
43 | after: (flow) => { console.log("after", flow) },
|
44 | };
|
45 | </script>
|
46 | ```
|
47 |
|
48 | Otherwise you can disable `auto` running the previewer and call `window.PagedPolyfill.preview();`
|
49 | whenever you want to start.
|
50 |
|
51 | ```html
|
52 | <script>
|
53 | window.PagedConfig = {
|
54 | auto: false
|
55 | after: (flow) => { console.log("after", flow) },
|
56 | };
|
57 |
|
58 | setTimeout(() => {
|
59 | window.PagedPolyfill.preview();
|
60 | }, 1000);
|
61 | </script>
|
62 | ```
|
63 |
|
64 | ## Chunker
|
65 | Chunks up a document into paged media flows and applies print classes.
|
66 |
|
67 | Examples:
|
68 |
|
69 | * Process the [first 50 pages of Moby Dick](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/index.html).
|
70 | * Upload and [chunk an Epub using Epub.js](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/epub.html).
|
71 |
|
72 | ## Polisher
|
73 | Converts `@page` css to classes, and applies counters and content.
|
74 |
|
75 | Examples:
|
76 |
|
77 | * Test [styles for print](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polisher.html).
|
78 |
|
79 | ### CLI
|
80 |
|
81 | 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).
|
82 |
|
83 | ## Modules
|
84 |
|
85 | Modules are groups of handlers for that apply the layout and styles of a CSS module, such as Generated Content.
|
86 |
|
87 | New handlers can be registered from `import { registerHandlers } from 'pagedjs'` or by calling `Paged.registerHandlers` on an html page.
|
88 |
|
89 | ```html
|
90 | <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
|
91 | <script>
|
92 | class MyHandler extends Paged.Handler {
|
93 | constructor(chunker, polisher, caller) {
|
94 | super(chunker, polisher, caller);
|
95 | }
|
96 |
|
97 | afterPageLayout(pageFragment, page) {
|
98 | console.log(pageFragment);
|
99 | }
|
100 | }
|
101 | Paged.registerHandlers(MyHandler);
|
102 | </script>
|
103 | ```
|
104 |
|
105 | 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.
|
106 |
|
107 | ```js
|
108 | // Chunker
|
109 | beforeParsed(content)
|
110 | afterParsed(parsed)
|
111 | beforePageLayout(page)
|
112 | afterPageLayout(pageElement, page, breakToken)
|
113 | afterRendered(pages)
|
114 |
|
115 | // Polisher
|
116 | beforeTreeParse(text, sheet)
|
117 | beforeTreeWalk(ast)
|
118 | afterTreeWalk(ast, sheet)
|
119 | onUrl(urlNode)
|
120 | onAtPage(atPageNode)
|
121 | onRule(ruleNode)
|
122 | onDeclaration(declarationNode, ruleNode)
|
123 | onContent(contentNode, declarationNode, ruleNode)
|
124 | ```
|
125 |
|
126 | ## Setup
|
127 | Install dependencies
|
128 | ```sh
|
129 | $ npm install
|
130 | ```
|
131 |
|
132 | ## Development
|
133 | Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
|
134 | ```sh
|
135 | $ npm start
|
136 | ```
|
137 |
|
138 | ## Deployment
|
139 | Build the `dist` output
|
140 | ```sh
|
141 | $ npm run prepare
|
142 | ```
|
143 |
|
144 | ## Testing
|
145 |
|
146 | Testing for Paged.js uses [Jest](https://facebook.github.io/jest/en/) but is split into Tests and Specs.
|
147 |
|
148 | ### Tests
|
149 |
|
150 | Unit tests for Chunker and Polisher methods are run in node using JSDOM.
|
151 |
|
152 | ```bash
|
153 | npm run tests
|
154 | ```
|
155 |
|
156 | ### Specs
|
157 |
|
158 | Specs run a html file in Chrome (using puppeteer) to test against CSS specifications.
|
159 |
|
160 | They can also output a pdf and compare pages (one at a time) in that PDF with samples PDFs (saved as images).
|
161 |
|
162 | To test the pdf output of specs, you'll need to build the library locally.
|
163 |
|
164 | ```bash
|
165 | npm run build
|
166 | ```
|
167 |
|
168 | Then run the jest tests in puppeteer.
|
169 |
|
170 | ```bash
|
171 | npm run specs
|
172 | ```
|
173 |
|
174 | To debug the results of a test in a browser you can add `NODE_ENV=debug`
|
175 |
|
176 | ```bash
|
177 | NODE_ENV=debug npm run specs
|
178 | ```
|
179 |
|
180 | To update the stored pdf images you can run
|
181 |
|
182 | ```bash
|
183 | npm run specs -- --updateSnapshot
|
184 | ```
|
185 |
|
186 | ### Docker
|
187 |
|
188 | A `pagedmedia/pagedjs` docker image contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests.
|
189 |
|
190 | To build the image run
|
191 |
|
192 | ```bash
|
193 | docker build -t pagedmedia/pagedjs .
|
194 | ```
|
195 |
|
196 | By default the container will run the development server with `npm start`
|
197 |
|
198 | ```bash
|
199 | docker run -it -p 9090:9090 pagedmedia/pagedjs
|
200 | ```
|
201 |
|
202 | The tests and specs can be run within the container by passing a `seccomp` file for Chrome and running `npm test`
|
203 |
|
204 | ```bash
|
205 | docker run -it --security-opt 'seccomp=seccomp.json' pagedmedia/pagedjs npm test
|
206 | ```
|
207 |
|
208 | ## Contributors
|
209 |
|
210 | ### Core team
|
211 | 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.
|
212 |
|
213 | ## Licence
|
214 |
|
215 | MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)
|