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

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

Specs

blob() :: binary()

Specs

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

Specs

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

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

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

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.

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"