Commit ec8ad483 authored by Thomas Parisot's avatar Thomas Parisot

Refine documentation

parent 7e48d3e5
Pipeline #235 failed with stage
in 7 seconds
...@@ -5,65 +5,93 @@ Paged.js - Paged Media Tools ...@@ -5,65 +5,93 @@ Paged.js - Paged Media Tools
Paged.js is an open-source library to display paginated content in the browser and to generate print books using web technology. 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. It contains a set of handlers for CSS transformations and fragmented layout which polyfill the [CSS Paged Media][] and [CSS Generated Content][] 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). 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/). A quick overview to getting started with Paged Media CSS and Paged.js is available on [pagedmedia.org](https://www.pagedmedia.org/paged-js/).
## NPM Module ## Install
```sh
$ npm install pagedjs
```
```js Paged.js is available via a CDN like [jsDelivr][] or [unpkg][] for a quick use.
import { Previewer } from 'pagedjs'; See below for how to use it.
let paged = new Previewer(); You can also integrate Paged.js with your toolchain [via NPM][npm].
let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
console.log("Rendered", flow.total, "pages."); ```bash
}) $ npm install pagedjs
``` ```
## Polyfill ## Polyfill
Add the the `paged.polyfill.js` script to replace all `@page` css and render the html page with the Paged Media styles applied: The polyfill is the easiest way to replace all `@page` css. It renders the html page according to the [CSS Paged Media][] spec.
The polyfill runs automatically as soon as the DOM is ready.
```html ```html
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script> <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
``` ```
Try the [polyfill with Aurorae](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html). See it in action with the [Aurorae book](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).
By default the polyfill will run automatically as soon as the DOM is ready. Use the `auto` configuration property of the `PagedConfig` object to render only when `PagedPolyfill.preview()` is called.
However, you can add an async `before` function or return a Promise to delay the polyfill starting.
```html ```html
<script> <script>
// disable the polyfill before loading its script
window.PagedConfig = { window.PagedConfig = {
before: () => { auto: false
return new Promise(resolve, reject) {
setTimeout(() => { resolve() }, 1000);
}
},
after: (flow) => { console.log("after", flow) },
}; };
</script> </script>
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script>
// do something else
// ...
// then runs the pollyfill manually
PagedPolyfill.preview();
</script>
``` ```
Otherwise you can disable `auto` running the previewer and call `window.PagedPolyfill.preview();` Alternativelly, delay the rendering until the `before` configuration property of the `PagedConfig` object is resolved.
whenever you want to start.
```html ```html
<script> <script>
window.PagedConfig = { window.PagedConfig = {
auto: false before: () => {
after: (flow) => { console.log("after", flow) }, return new Promise(resolve) {
// do something before the rendering
// ...
// then runs the polyfill
resolve();
}
}
}; };
</script>
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
```
## Previewer
```js
import { Previewer } from 'pagedjs';
let paged = new Previewer();
let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
console.log("Rendered", flow.total, "pages.");
});
```
setTimeout(() => { ### ECMAScript Module
window.PagedPolyfill.preview();
}, 1000); ```html
<script type="module">
import { Previewer } from 'https://unpkg.com/pagedjs/dist/paged.esm.js';
let paged = new Previewer();
// ...
</script> </script>
``` ```
...@@ -84,7 +112,7 @@ Examples: ...@@ -84,7 +112,7 @@ Examples:
### CLI ### 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). [`pagedjs-cli`](https://gitlab.pagedmedia.org/polyfills/pagedjs-cli) is a command line interface to render out PDFs of HTML files. It uses [Puppeteer][] under the hood.
## Modules ## Modules
...@@ -93,9 +121,10 @@ Modules are groups of handlers for that apply the layout and styles of a CSS mod ...@@ -93,9 +121,10 @@ Modules are groups of handlers for that apply the layout and styles of a CSS mod
New handlers can be registered from `import { registerHandlers } from 'pagedjs'` or by calling `Paged.registerHandlers` on an html page. New handlers can be registered from `import { registerHandlers } from 'pagedjs'` or by calling `Paged.registerHandlers` on an html page.
```html ```html
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script> <script type="module">
<script> import {Handler, registerHandlers} from 'https://unpkg.com/pagedjs/dist/paged.esm.js';
class MyHandler extends Paged.Handler {
class MyHandler extends Handler {
constructor(chunker, polisher, caller) { constructor(chunker, polisher, caller) {
super(chunker, polisher, caller); super(chunker, polisher, caller);
} }
...@@ -104,7 +133,8 @@ New handlers can be registered from `import { registerHandlers } from 'pagedjs'` ...@@ -104,7 +133,8 @@ New handlers can be registered from `import { registerHandlers } from 'pagedjs'`
console.log(pageFragment); console.log(pageFragment);
} }
} }
Paged.registerHandlers(MyHandler);
registerHandlers(MyHandler);
</script> </script>
``` ```
...@@ -135,14 +165,15 @@ onOverflow(overflow, rendered, bounds) ...@@ -135,14 +165,15 @@ onOverflow(overflow, rendered, bounds)
onBreakToken(breakToken, overflow, rendered) onBreakToken(breakToken, overflow, rendered)
``` ```
## Setup ## Local Development
Install dependencies Install dependencies
```sh ```sh
$ npm install $ npm install
``` ```
## Development
Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/) Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
```sh ```sh
$ npm start $ npm start
``` ```
...@@ -220,12 +251,12 @@ npm run specs -- --updateSnapshot ...@@ -220,12 +251,12 @@ npm run specs -- --updateSnapshot
### Docker ### Docker
A `pagedmedia/pagedjs` docker image contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests. A [`pagedmedia/pagedjs` docker image][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 To build the image run
```bash ```bash
docker build -t pagedmedia/pagedjs . docker build -t pagedmedia/pagedjs .
``` ```
By default the container will run the development server with `npm start` By default the container will run the development server with `npm start`
...@@ -248,3 +279,13 @@ The core team behind paged.js includes [Adam Hyde](https://adamhyde.net), [Julie ...@@ -248,3 +279,13 @@ The core team behind paged.js includes [Adam Hyde](https://adamhyde.net), [Julie
## Licence ## Licence
MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md) MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)
[CSS Paged Media]: https://www.w3.org/TR/css-page-3/
[CSS Generated Content]: https://www.w3.org/TR/css-gcpm-3/
[Puppeteer]: https://pptr.dev/
[docker-image]: https://hub.docker.com/r/pagedmedia/pagedjs
[jsDelivr]: https://www.jsdelivr.com/package/npm/pagedjs
[unpkg]: https://unpkg.com/pagedjs
[via NPM]: https://npmjs.com/pagedjs
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment