ChromicPDF v0.5.0 ChromicPDF.Template View Source

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.

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, which is why these helpers exist to make basic page styling a bit easier.

For a start, see source_and_options/1.

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 type

content_option()

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

paper_size()

View Source
paper_size() :: :a4 | :us_letter | {float(), float()}
Link to this type

style_option()

View Source
style_option() ::
  {:size, paper_size()}
  | {:header_height, binary()}
  | {:header_font_size, binary()}
  | {:footer_height, binary()}
  | {:footer_font_size, binary()}

Link to this section Functions

Link to this function

html_concat(styles, content)

View Source
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
source_and_options([content_option() | style_option()]) ::
  ChromicPDF.Processor.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>
Link to this function

styles(opts \\ [])

View Source
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"