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. 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. The currently supported properties can be found on [the pagedjs website](https://pagedjs.org/documentation/cheatsheet/). A quick overview to getting started with Paged Media CSS and Paged.js is available on [pagedjs.org/documentation](https://pagedjs.org/documentation/). ## NPM Module ```sh $ npm install pagedjs ``` ```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."); }) ``` ## Polyfill Add the the `paged.polyfill.js` script to replace all `@page` css and render the html page with the Paged Media styles applied: ```html ``` Try the [polyfill with Aurorae](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html). 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 ``` Otherwise you can disable `auto` running the previewer and call `window.PagedPolyfill.preview();` whenever you want to start. ```html ``` ## Chunker Chunks up a document into paged media flows and applies print classes. Examples: * 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). ## Polisher Converts `@page` css to classes, and applies counters and content. Examples: * Test [styles for print](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polisher.html). ### CLI 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). ## 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 ``` Handlers have methods that correspond to the hooks for the parsing, layout and rendering of the Chunker and Polisher. Returning a 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 // Previewer beforePreview(content, renderTo) afterPreview(pages) // Chunker beforeParsed(content) filter(content) afterParsed(parsed) beforePageLayout(page) onPageLayout(pageWrapper, breakToken, layout); afterPageLayout(pageElement, page, breakToken) finalizePage(pageElement, page, breakToken) afterRendered(pages) // Polisher beforeTreeParse(text, sheet) beforeTreeWalk(ast) afterTreeWalk(ast, sheet) onUrl(urlNode) onAtPage(atPageNode) onRule(ruleNode) onDeclaration(declarationNode, ruleNode) onContent(contentNode, declarationNode, ruleNode) // Layout layoutNode(node) renderNode(node, sourceNode, layout) onOverflow(overflow, rendered, bounds) onBreakToken(breakToken, overflow, rendered) afterOverflowRemoved(removed, rendered) beforeRenderResult(breakToken, pageWrapper) ``` ## Setup Install dependencies ```sh $ npm install ``` ## Development Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/) ```sh $ npm start ``` ## Deployment Build the `dist` output ```sh $ npm run build ``` Compile the `lib` output ```sh $ npm run compile ``` Generate legacy builds with polyfills included ```sh $ npm run legacy ``` ## Testing 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 test ``` ### 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). The PDF comparison tests depend on the `ghostscript` and the `ghostscript4js` package. It is recomend to run these in the Docker container below via: ```bash npm run docker-specs ``` However if you'd like to run the specs outside of Docker, you'll need to install a local version of Ghostscript for your system according to https://www.npmjs.com/package/ghostscript4js#prerequisites For Mac you can install it with ```bash brew install ghostscript ``` For Debian you can install it with ```bash sudo apt-get install ghostscript sudo apt-get install libgs-dev ``` Now you can install the `ghostscript4js` library. For Linux you can optionally pass the location ghostscript was installed to in `GS4JS_HOME`. ```bash GS4JS_HOME="/usr/lib/$(gcc -dumpmachine)" npm install ghostscript4js ``` To test the pdf output of specs, you'll need to build the library locally. ```bash npm run build ``` Then run the jest tests in puppeteer. ```bash npm run specs ``` To debug the results of a test in a browser you can add `NODE_ENV=debug` ```bash NODE_ENV=debug npm run specs ``` To update the stored pdf images you can run ```bash npm run specs -- --updateSnapshot ``` ### 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 && npm run specs ``` ## Contributors ### 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 MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)

Paket	Downloads	Stars	Größe	Issues	Veröffentlichung	Lizenz

pagedjs	20,925	-	5.92 MB	-	vor 2 Jahren	MIT