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