Chrome-pdf recipe is using headless chrome to print html content into pdf files.
The settings reflects the headless chrome API where you can also find detail information.
These basic settings are typically stored with the template, but you can also send them through API calls inside the template.chrome property.
The options can be also dynamically set from within the page javascript using:
<script>
...
window.JSREPORT_CHROME_PDF_OPTIONS = {
landscape: true
}
</script>
Use chrome-pdf node in the standard config file.
"extensions": {
"chrome-pdf": {
"timeout": 30000,
"launchOptions": {...}
}
}
to find more information about what is available in launchOptions configuration object you can check the docs here.
you can also use top level chrome property in configuration, the difference is that this configuration will be shared with any other extension that uses chrome and the configuration snippet above is specifically for options in chrome-pdf extension.
"chrome": {
"timeout": 30000
}
The fonts can be easily embedded into PDF reports using the assets extension. You can find the tutorial on how to do it here.
CSS contains styles like page-break-before that you can use to specify html page breaks. This can be used as well with chrome-pdf in order to specify page breaks inside pdf files.
<h1>Hello from Page 1</h1>
<div style='page-break-before: always;'></div>
<h1>Hello from Page 2</h1>
You can also use css property page-break-inside to for example avoid breaking an element to multiple pages.
You may need to postpone pdf printing until some javascript async tasks are processed. If this is your case set the chrome.waitForJS=true in the API or Wait for printing trigger in the studio menu. Then the printing won't start until you set window.JSREPORT_READY_TO_START=true inside your template's javascript.
...
<script>
// do some calculations or something async
setTimeout(function() {
window.JSREPORT_READY_TO_START = true; //this will start the pdf printing
}, 500);
...
</script>
The header and footer are evaluated as if they were a full jsreport template. This means you can add, for example, a child template reference into a header and it will be extracted. You can also use main template helpers or data in the header/footer. Remember that in order to show the header/footer you need to activate the displayHeaderFooter option first and add some top, bottom margin to the template in order to give the page some space to show the header/footer.
Inside the header/footer template you can use some special css classes to make chrome inject some content for you. the special css classes supported by chrome are the following:
date -> injects formatted print datetitle -> injects the content of the document titleurl -> injects the document locationpageNumber -> injects current page numbertotalPages -> insject the total pagesThere are some issues with native header/footer you should be aware of:
-webkit-print-color-adjust: exact as workaroundIn the most of the cases it is better to use pdf-utils instead which is less limiting and without these issues.
Example showing how to use the special css classes and the workaround for the scaling issues.
<!--header template content-->
<html>
<head>
<style>
/* defining explicit font-size solves the scaling issue */
html, body {
font-size: 12px;
}
</style>
</head>
<body>
<!--
defining some elements with the special css classes makes chrome
inject content in runtime
-->
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</body>
</html>
The pdf-utils extension provides advanced and more rich features to merge dynamic content into the chrome pdf output, like rich header/footer, print page numbers, watermarks, merge pages with different orientation, etc. make sure to check the docs for some examples.
Chrome by default uses print CSS media query when printing pdf. This impacts CSS frameworks like Bootstrap which usually produces different results for print media type. The pdf in this case applies different styles then html. You can adapt/unite this by changing media type settings from print to screen in the template's chrome settings.
The recipe by default starts extra new chrome process every time you render a template. This behavior can be changed and recipe configured to reuse several chrome instances to improve rendering performance.
{
"extensions": {
"chrome-pdf": {
"strategy": "chrome-pool",
"numberOfWorkers": 3
}
}
self closing divs (<div />) are heavily slowing down chrome pdf rendering, don't use them
<div style='height:500'>
<img src='foo' />
</div>
--no-sandbox argument. This can be achieved using the following config. See also puppeteer troubleshooting.
"extensions": {
"chrome-pdf": {
"launchOptions": {
"args": ["--no-sandbox"]
}
}
}