ChromicPDF.Template (ChromicPDF v1.1.1) View Source

Helper functions for page styling.

For a start, see source_and_options/1.

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

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.

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

blob()

Specs

blob() :: binary()

content_option()

Specs

content_option() :: {:content, blob()} | {:header, blob()} | {:footer, blob()}

paper_size()

Specs

paper_size() :: :a4 | :us_letter | {float(), float()}

style_option()

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()}

Link to this section Functions

html_concat(styles, content)

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"))

source_and_options(opts)

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

header
footer
all options from styles/1

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 ⚠

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.

styles(opts \\ [])

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

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"