Part01_Getting-Started-with-paged.md 9.62 KB
Newer Older
Julie Blanc's avatar
Julie Blanc committed
1 2 3 4 5 6 7
# Getting Started with Paged.js



## A quick presentation of paged.js


8 9 10 11 12 13 14 15 16 17 18 19

Paged.js is a free and open-source library to paginate content in the browser to create PDF outputs from any HTML content based on the W3C specifications.

With Paged.js you can do automated typesetting adaptable to any workflows. It will fragment your content, read and apply your print declarations and present a paginated rendering of the HTML document. 



### Visual preview and command line version

With paginated content in the browser, Paged.js makes it possible to have a visual preview of the printed rendering directly in web browsers with a graphical interface. This allows designers to access development tools to make changes on the fly and control the rendering of the composition (easy debugging). It's also possible to insert Paged.js into other tools and to propose to users to configure their graphical rendering by adding functionalities.

Paged.js can easily be inserted into automated workflows thanks to the command line interface version (using an headless browser) that can generate a PDF from scriptable and automated commands. 
Julie Blanc's avatar
Julie Blanc committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36



### W3C specifications

Paged.js is based on the CSS standards written by the World Wide Web Consortium (W3C). It acts like a sort of polyfill(*) to supports some CSS print modules in recent browser: it can parse CSS stylesheets, polyfill the print declarations (by updating them with supported styles or replacing them with JavaScript implementations) and present a paginated rendering of the HTML document using the fragmentation provided by CSS columns. 

(*) A [polyfill](https://en.wikipedia.org/wiki/Polyfill_(programming)) is code that implements a feature on web browsers that do not support the feature. 

W3C CSS modules implemented by paged.js : 

- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)  
- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css-gcpm-3/)  
- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/) 



37 38 39 40




Julie Blanc's avatar
Julie Blanc committed
41 42 43 44 45 46 47 48 49 50 51 52 53
### A community

The code of paged.js is open-source with a MIT license and the development is community-driven. Everyone is invited to join us!

You can find the source code of paged.js on the repo of our self-healing gitlab: https://gitlab.pagedmedia.org/tools/pagedjs

We have several tools to help designers and discuss the addition of new features. You can add issues to the repo to suggest new features or simply report problems. But the easiest way to talk to us (if you're not using gitlab) it's to join us on our self-hosted chat: https://mattermost.pagedmedia.org/






54
## Running paged.js
Julie Blanc's avatar
Julie Blanc committed
55 56 57 58 59 60 61 62

How to start with paged.js?  The first thing is to make the script work on your document. For that, you need a few things:

* your usual html and css files,
* the paged.js script,
* a (local) server,
* a web browser.

63
https://www.startpage.com/fr/
Julie Blanc's avatar
Julie Blanc committed
64

65
### Access to paged.polyfill.js script
Julie Blanc's avatar
Julie Blanc committed
66 67 68 69 70 71 72 73 74

**Option 1: CDN version**

You can use the hosted version of the script, just copy this in the `head` of your document:

```HTML
<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
```

75
If you want to specify the release number of the script you are using, the different releases of the script will be available here: https://gitlab.pagedmedia.org/tools/pagedjs/releases. By default, the link bellow go to the latest release.
Julie Blanc's avatar
Julie Blanc committed
76 77 78 79 80 81 82

To use the script locally, without an internet connection, just copy the script into a file and change the link to your script, something like:

```HTML
<script src="js/paged.polyfill.js"></script>
```

83
The script will start automatically when you go to your document from the browser. It will apply to all your content and fragment it into different pages. If you need to run other scripts before paged.js starts, if you want to integrate it into a tool or simply if you want delay its launch, we will see that in another part.
84

Julie Blanc's avatar
Julie Blanc committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106


**Option 2: Developpement version**

To get setup with the developement version, clone the repository and run the project using npm (you need to have git and npm installed):

```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs.git
$ cd pagedjs
$ npm install
$ npm start
```

Link the script with your document:

<script src="http://localhost:9090/dist/paged.polyfill.js"></script>
All you need to know about setup, development and testing with the local dev-server is available in the README.md of the repo. 



### Use a local server

107
Paged.js need to access your files via a local server to read the css properties you write. There is a lot of way to create and lunch a local server.  If you're not familiar to Linux, the easiest way is to use ready-to-use local web development solution like [WAMP](http://www.wampserver.com/) (for window) or [WAMP](https://www.mamp.info/en/) (for Mac).
Julie Blanc's avatar
Julie Blanc committed
108 109 110 111 112 113

You can find all the documentation on their respective websites, globally:

1. download the package and follow the step of your usual system installation manager.
2. add the folder of your project in the folder automatically create by the application, typically in `c:\wamp\www` for WAMP or in `/Applications/MAMP/htdocs/`
3. Start the local server
114 115 116 117 118
4. In your favorite browser, go to the local address provided by your application (like`http://localhost:8888` for example)



Note: With some browsers and some OS, you may not need a local server for paged.js to work. To find out, simply open your HTML page (linked to the polyfill).  If the paginated content appears, you don't need a local server.
Julie Blanc's avatar
Julie Blanc committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136



### Which browser to use?

 We really want paged.js to work with all the browsers around, but we can't manage right now. There are several reasons for this which are explained below. To be quick:  **Paged.js only works in Chromium and derivative (Chrome, Brave, etc.) and in recent versions, after mid-2017**.



#### Support of @page { size } 

Paged.js act like a sort of polyfill but there is one thing we can't manage and we need to print: it's the support by the browser of the `@page { size }` property. This property will allow you to create the PDF at the right size when it is generated. It's only supported in some browsers (see the list below):

- Chromium
- Google Chrome
- Brave
- Opera

137
We know that many of you are attached to Mozzila Firefox (and so are we), it is still possible to use it but you will have to manually change the PDF size when you generate it (in the custom sizes). De careful to calculate bleeds and crop marks if you add it.
Julie Blanc's avatar
Julie Blanc committed
138 139 140 141 142



#### Support of CSS grid

143
You must also use a recent version of these browsers because we use some CSS grid module properties for the construction of the pages. CSS grid is supported in most browsers since mid-2017. You can see here if your browser supports CSS grid:  https://caniuse.com/#feat=css-grid 
Julie Blanc's avatar
Julie Blanc committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183



#### Different rendering between browsers

The result will not always be the same from one browser to another because they don't use the same browser engine. For example, line-height is not managed in the same way on Firefox and Chrome. The result will also not be the same depending on the OS you are using. For example, hyphenation is managed in Chrome only on Apple OSX. 

 We recommend staying on the same browser and OS for the design and generation of the PDF to avoid unpleasant surprises.



## Generating a PDF



Paged.js is a viewer for your content paged in the browser. The PDF generation can be done by two way:

* using the print features of your browser,

* using the [pagedjs-cli](https://gitlab.pagedmedia.org/tools/pagedjs-cli) tool based on paged.js and [Puppeteer](https://github.com/GoogleChrome/puppeteer).



### Option 1: with a browser

1. Simply click on the “Print” button of your browser.

2. Change the *Destination* to "Save as a PDF file”.

3. In the avanced settings:
   * Set *Margins* to “none”,
   * Remove the option “Headers and footers”,
   * Select the option “Background graphics”.

The way paged.js work, it doesn't use the print engine from the browser to define the margins, the breaks or the headers and footers. This is why you need to remove this option. Printing without the library give a different output.



### Option 2: with pagedjs-cli

184 185
The command line version of paged.js uses a headless browser to generate a PDF (chromium). So you can use paged.js in fully automated workflows. With the command line version, you don't need to call the paged.js script in your document, it will be done automatically.

Julie Blanc's avatar
Julie Blanc committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
First, download and install pagedjs-cli with your terminal (you need to have git and npm installed):

```
$ git clone https://gitlab.pagedmedia.org/tools/pagedjs-cli.git
$ cd pagedjs-cli
$ npm install -g pagedjs-cli
```

Then, in a new window terminal, go to the folder where the code of your document is located (use the `cd` command) and generate your PDF with the following command: 

```
$ pagedjs-cli index.html -o result.pdf
```

Some options to generate the PDF: 

```-h, --help                  output usage information
-V, --version               output the version number
-i, --inputs [inputs]       Inputs
-o, --output [output]       Output
-d, --debug                 Show Electron Window to Debug
-l, --landscape             Landscape printing
-s, --page-size [size]      Print to Page Size [size]
-w, --width [size]          Print to Page Width [width]
-h --height [size]          Print to Page Height [weight]
-m, --page-margin [margin]  Print with margin [margin]
-n, --hyphenate [lang]      Hyphenate with language [language], defaults to "en-us"
-hi, --hypher_ignore [str]  Ignore passed element selectors, such as ".class_to_ignore, h1"
-ho, --hypher_only [str]    Only hyphenate passed elements selector, such as ".hyphenate, aside"
-e, --encoding [type]       Set the encoding of the input html, defaults to "utf-8"
-t, --timeout [ms]          Set a max timeout of [ms]
```

219 220