ChromicPDF
ChromicPDF
v1.17.0

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

Link to this section Summary

Types

content_option()
header_footer_option()
paper_size()
style_option()

Functions

header_footer_styles(opts \\ [])

Renders header/footer styles for given template options.

html_concat(styles, content)

Concatenes two HTML strings or iolists into one.

options(opts \\ [])

Returns an options list for given template options.

page_styles(opts \\ [])

Renders page styles for given template options.

source_and_options(opts)

Returns source and options for a PDF to be printed, a given set of template options.

styles(opts \\ []) deprecated

Renders page styles & header/footer styles in a single template.

Link to this section Types

Link to this type

content_option()

View Source 
@type content_option() :: {:content, iodata()}
Link to this type

paper_size()

View Source 
@type 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 
@type 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()}
  | {:text_rendering, binary()}
  | {:landscape, boolean()}

Link to this section Functions

Link to this function

html_concat(styles, content)

View Source 
@spec 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

options(opts \\ [])

View Source 
@spec options([header_footer_option() | style_option()]) :: keyword()

Returns an options list for given template options.

Returned options can be passed as second argument to ChromicPDF.print_to_pdf/2.

options

 Options

  • header iodata content of header
  • footer iodata content of footer
  • all options from styles/1

example

 Example

This example has the dimension of a ISO A4 page.

ChromicPDF.Template.options(
  header: "<p>header</p>",
  footer: "<p>footer</p>",
  size: :a4,
  header_height: "45mm",
  header_font_size: "20pt",
  footer_height: "40mm"
)

Header, and footer templates should be unwrapped HTML markup (i.e. no <html> around the content), including any <style> tags that your page needs.

Link to this function

page_styles(opts \\ [])

View Source 
@spec page_styles(keyword()) :: binary()

Renders page styles for given template options.

These base styles will configure page dimensions and apply margins for headers and footers. They also remove any default browser margin from the body, and apply sane defaults for rendering text in print.

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

Link to this function

source_and_options(opts)

View Source 
@spec source_and_options([content_option() | header_footer_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 directly passed to ChromicPDF.print_to_pdf/2.

options

 Options

  • content iodata page content (required)
  • header iodata content of header (default: "")
  • footer iodata content of footer (default: "")
  • all options from styles/1

example

 Example

This example has the dimension of a ISO A4 page.

[
  content: "<p>Hello</p>",
  header: "<p>header</p>",
  footer: "<p>footer</p>",
  size: :a4,
  header_height: "45mm",
  header_font_size: "20pt",
  footer_height: "40mm"
]
|> ChromicPDF.Template.source_and_options()
|> ChromicPDF.print_to_pdf()

Content, header, and footer templates should be unwrapped HTML markup (i.e. no <html> around the content), including 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 "source" 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
This function is deprecated. Use page_styles/1 or header_footer_styles/1 instead. 
@spec styles([style_option()]) :: binary()

Renders page styles & header/footer styles in a single template.

This function is deprecated. Since Chromium v117 the footer and header templates must not contain any margins in a @page directive anymore.

See https://github.com/bitcrowd/chromic_pdf/issues/290 for details.

Please use page_styles/1 or header_footer_styles/1 instead.