View Source ChromicPDF.Template (ChromicPDF v1.6.0)
Helper functions for page styling.
For a start, see source_and_options/1
.
motivation
Motivation
This module contains helper functions that make it easier to to build HTML templates (body,
header, and footer) that fully cover a given page. Like an adapter, it tries to harmonize
Chrome's printToPDF
options and related CSS layout styles (@page
and friends) with a custom
set of page sizing options. Using this module is entirely optional, but perhaps can help to
avoid some common pitfalls arising from the slightly unintuitive and sometimes conflicting
behaviour of printToPDF
options and @page
CSS styles in Chrome.
page-dimensions
Page dimensions
One particularly cumbersome detail is that Chrome in headless mode does not correctly interpret
the @page
CSS rule to configure the page dimensions. Resulting PDF files will always be in
US-letter format unless configured differently with the paperWidth
and paperHeight
options.
Experience has shown, that results will be best if the @page
rule aligns with the values
passed to printToPDF/2
, which is why this module exists to make basic page sizing easier.
To rotate a page into landscape, use the landscape
option.
Link to this section Summary
Functions
Concatenes two HTML strings or iolists into one.
Returns source and options for a PDF to be printed, a given set of template options. The return
value can be passed to ChromicPDF.print_to_pdf/2
.
Renders page styles for given options.
Link to this section Types
Link to this section Functions
Concatenes two HTML strings or iolists into one.
From {:safe, iolist}
tuples, the :safe
is dropped. This is useful to prepare data coming
from a Phoenix-compiled .eex
template.
content = html_concat(@styles, render("content.html"))
@spec source_and_options([content_option() | style_option()]) :: ChromicPDF.source_and_options()
Returns source and options for a PDF to be printed, a given set of template options. The return
value can be passed to ChromicPDF.print_to_pdf/2
.
options
Options
header
footer
- all options from
styles/1
example
Example
This example has the dimension of a ISO A4 page.
ChromicPDF.Template.source_and_options(
content: "<p>Hello</p>",
header: "<p>header</p>",
footer: "<p>footer</p>",
size: :a4,
header_height: "45mm",
header_font_size: "20pt",
footer_height: "40mm"
)
Content, header, and footer templates should be unwrapped HTML markup (i.e. no <html>
around
the content), prefixed with any <style>
tags that your page needs.
<style>
h1 { font-size: 22pt; }
</style>
<h1>Hello</h1>
markup-is-injected-into-the-dom
⚠ Markup is injected into the DOM ⚠
Please be aware that the options returned by this function cause ChromicPDF to inject the
markup directly into the DOM using the remote debugging API. This comes with some pitfalls
which are explained in ChromicPDF.print_to_pdf/2
. Most notably, no relative URLs may be
used within the given HTML.
@spec styles([style_option()]) :: blob()
Renders page styles for given options.
These base styles will configure page dimensions and header and footer heights. They also remove any browser padding and margins from these elements, and set the font-size.
Additionally, they set the zoom level of header and footer templates to 0.75 which seems to make them align with the content viewport scaling better.
options
Options
size
page size, either a standard name (:a4
,:us_letter
) or a{<width>, <height>}
tuple in inches, default::us_letter
header_height
default: zeroheader_font_size
default: 10ptheader_zoom
default: 0.75footer_height
default: zerofooter_font_size
default: 10ptfooter_zoom
default: 0.75webkit_color_print_adjust
default: "exact"landscape
default: false
landscape
Landscape
As it turns out, Chrome does not recognize the landscape
option in its printToPDF
command
when explicit page dimensions are given. Hence, we provide a landscape
option here that
swaps the page dimensions (e.g. it turns 11.7x8.3" A4 into 8.3"x11.7").