ChromicPDF v1.3.0

View Source ChromicPDF.Template (ChromicPDF v1.3.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

Types

blob()
content_option()
paper_size()
style_option()

Functions

html_concat(styles, content)

Concatenes two HTML strings or iolists into one.

source_and_options(opts)

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.

styles(opts \\ [])

Renders page styles for given options.

Link to this section Types

Link to this type

blob()

View Source

Specs

blob() :: binary()
Link to this type

content_option()

View Source

Specs

content_option() :: {:content, blob()} | {:header, blob()} | {:footer, blob()}
Link to this type

paper_size()

View Source

Specs

paper_size() ::
  {float(), float()}
  | :a0
  | :a1
  | :a2
  | :a3
  | :a4
  | :a5
  | :a6
  | :a7
  | :a8
  | :a9
  | :a10
  | :us_letter
  | :legal
  | :tabloid
Link to this type

style_option()

View Source

Specs

style_option() ::
  {:size, paper_size()}
  | {:header_height, binary()}
  | {:header_font_size, binary()}
  | {:header_zoom, binary()}
  | {:footer_height, binary()}
  | {:footer_font_size, binary()}
  | {:footer_zoom, binary()}
  | {:webkit_print_color_adjust, binary()}
  | {:landscape, boolean()}

Link to this section Functions

Link to this function

html_concat(styles, content)

View Source

Specs

html_concat({:safe, iolist()} | iodata(), {:safe, iolist()} | iodata()) ::
  iolist()

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"))
Link to this function

source_and_options(opts)

View Source

Specs

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

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.

Link to this function

styles(opts \\ [])

View Source

Specs

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: zero
  • header_font_size default: 10pt
  • header_zoom default: 0.75
  • footer_height default: zero
  • footer_font_size default: 10pt
  • footer_zoom default: 0.75
  • webkit_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").