@spec capture_screenshot(source(), [capture_screenshot_option() | export_option()]) ::
  export_return()

Captures a screenshot.

This call blocks until the screenshot has been created.

print-and-return-base64-encoded-png

Print and return Base64-encoded PNG

{:ok, blob} = ChromicPDF.capture_screenshot({:url, "file:///example.html"})

custom-options-for-page-capturescreenshot

Custom options for Page.captureScreenshot

Custom options for the Page.captureScreenshot call can be specified by passing a map to the :capture_screenshot option.

ChromicPDF.capture_screenshot(
  {:url, "file:///example.html"},
  capture_screenshot: %{
    format: "jpeg"
  }
)

For navigational options (source, cookies, evaluating scripts) see print_to_pdf/2.

You may also use ChromicPDF.Template as an input source for capture_screenshot/2, yet keep in mind that many of the page-related styles do not take effect for screenshots.

full-page-screenshots

Full page screenshots

You can pass the :full_page option to make ChromicPDF increase the viewport dimensions to fit the entire content. This option only works with Chrome version 91 or greater.

ChromicPDF.capture_screenshot(
  {:url, "file:///very-long-content.html"},
  full_page: true
)

@spec child_spec([global_option()]) :: Supervisor.child_spec()

Returns a specification to start this module as part of a supervision tree.

@spec convert_to_pdfa(path(), [pdfa_option()]) :: export_return()

Converts a PDF to PDF/A (either PDF/A-2b or PDF/A-3b).

convert-an-input-pdf-and-return-a-base64-encoded-blob

Convert an input PDF and return a Base64-encoded blob

{:ok, blob} = ChromicPDF.convert_to_pdfa("some_pdf_file.pdf")

convert-and-write-to-file

Convert and write to file

ChromicPDF.convert_to_pdfa("some_pdf_file.pdf", output: "output.pdf")

pdf-a-versions-levels

PDF/A versions & levels

Ghostscript supports both PDF/A-2 and PDF/A-3 versions, both in their b (basic) level. By default, ChromicPDF generates version PDF/A-3b files. Set the pdfa_version option for version 2.

ChromicPDF.convert_to_pdfa("some_pdf_file.pdf", pdfa_version: "2")

Generated files pass the verapdf validation. When you verify this, please pass the corresponding profile arguments (-f 2b or -f 3b).

specifying-pdf-metadata

Specifying PDF metadata

The converter is able to transfer PDF metadata (the Info dictionary) from the original PDF file to the output file. However, files printed by Chrome do not contain any metadata information (except "Creator" being "Chrome").

The :info option of the PDF/A converter allows to specify metadata for the output file directly.

ChromicPDF.convert_to_pdfa("some_pdf_file.pdf", info: %{creator: "ChromicPDF"})

The converter understands the following keys, all of which accept String values:

• :title
• :author
• :subject
• :keywords
• :creator
• :creation_date
• :mod_date

By specification, date values in :creation_date and :mod_date do not need to follow a specific syntax. However, Ghostscript inserts date strings like "D:20200208153049+00'00'" and Info extractor tools might rely on this or another specific format. The converter will automatically format given DateTime values like this.

Both :creation_date and :mod_date are filled with the current date automatically (by Ghostscript), if the original file did not contain any.

adding-more-postscript-to-the-conversion

Adding more PostScript to the conversion

The pdfa_def_ext option can be used to feed more PostScript code into the final conversion step.

ChromicPDF.convert_to_pdfa(
  "some_pdf_file.pdf",
  pdfa_def_ext: "[/Title (OverriddenTitle) /DOCINFO pdfmark",
)

If your extra Postscript requires read permissions for additional files, pass the :permit_read option.

ChromicPDF.convert_to_pdfa(
  "some_pdf_file.pdf",
  pdfa_def_ext: "custom-postscript",
  permit_read: "/some/path",
  permit_read: "/some/other/path"
)

embedded-color-scheme

Embedded color scheme

Since it is required to embed a color scheme into PDF/A files, ChromicPDF ships with a copy of the royalty-free eciRGB_V2 scheme by the European Color Initiative. If you need to to use a different color scheme, please open an issue.

accessibility

Accessibility

Please note that running a PDF file through Ghostscript removes all structural annotations ("Tags") and hence disables accessibility features of assistive technologies. See On Accessibility / PDF/UA section for details.

@spec get_dynamic_name() :: atom()

Retrieves the currently set name (set using put_dynamic_name/1) or the default name.

@spec print_to_pdf(source() | [source()], [pdf_option() | export_option()]) ::
  export_return()

Prints a PDF.

This call blocks until the PDF has been created.

output-options

Output options

print-and-return-base64-encoded-pdf

Print and return Base64-encoded PDF

{:ok, blob} = ChromicPDF.print_to_pdf({:url, "file:///example.html"})

# Can be displayed in iframes
"data:application/pdf;base64,\#{blob}"

print-to-file

Print to file

:ok = ChromicPDF.print_to_pdf({:url, "file:///example.html"}, output: "output.pdf")

print-to-temporary-file

Print to temporary file

{:ok, :some_result} =
  ChromicPDF.print_to_pdf({:url, "file:///example.html"}, output: fn path ->
    send_download(path)
    :some_result
  end)

The temporary file passed to the callback will be deleted when the callback returns.

input-options

Input options

You can choose between multiple methods of supplying Chrome with the HTML source to print:

• Printing from a URL
• Internal endpoint with request forwarding
• Injecting the HTML markup directly into the DOM through the remote debugging API

print-from-url

Print from URL

Passing in a URL is the simplest way of printing a PDF. A target in Chrome is told to navigate to the given URL. When navigation is finished, the PDF is printed.

ChromicPDF.print_to_pdf({:url, "file:///example.html"})

ChromicPDF.print_to_pdf({:url, "http://example.net"})

ChromicPDF.print_to_pdf({:url, "https://example.net"})

Printing from URL has the benefit of being the tried-and-true solution, as Chrome's content loading works just as you would expect, including its assets cache.

Cookies

If your URL requires authentication, you can pass in a session cookie. The cookie is automatically cleared after the PDF has been printed.

cookie = %{
  name: "foo",
  value: "bar",
  domain: "localhost"
}

ChromicPDF.print_to_pdf({:url, "http:///example.net"}, set_cookie: cookie)

See Network.setCookie for options. name and value keys are required.

internal-endpoint-with-request-forwarding

Internal endpoint with request forwarding

Serving HTML templates from an internal endpoint allows you to leverage your existing HTTP server and HTML rendering infrastructure. Usually, you will want to render a HTML template from data you have in hand when calling print_to_pdf/2. ChromicPDF.Plug allows you to pass a callback function from the caller to the process serving Chrome's HTTP request.

ChromicPDF.print_to_pdf(
  {:plug,
    url: "http://localhost:4000/makepdf",
    forward:
      fn conn ->
        # this is executed in the context of the incoming Chrome request
      end
  }
)

You can also pass a MFA to the :forward option.

print-from-in-memory-html

Print from in-memory HTML

Alternatively, print_to_pdf/2 allows to pass an in-memory HTML blob to Chrome in a {:html, blob()} tuple. The HTML is sent to the target using the Page.setDocumentContent function.

ChromicPDF.print_to_pdf(
  {:html, "<h1>Hello World!</h1>"}
)

This method is useful for setups where Chrome has no network access to the application that hosts ChromicPDF, or you prefer not to have an HTTP server in your application.

Caveats

However, in-memory HTML printing comes with a few caveats.

References to external files in HTML source

Since the document content is replaced without navigating to a URL, Chrome has no way of telling which host it should contact to resolve relative URLs contained in the source.

If your HTML contains markup like

<!-- BAD: relative link to stylesheet in <head> element -->
<head>
  <link rel="stylesheet" href="selfhtml.css">
</head>

<!-- BAD: relative link to image -->
<img src="some_logo.png">

... you will need to replace these lines with either absolute URLs or inline data. Of course, absolute URLs can use the file:// scheme to point to files on the local filesystem, assuming Chrome has access to them. For the purpose of displaying small inline images (e.g. logos), data URLs are a good way of embedding them without the need for an absolute URL.

<!-- GOOD: inline styles -->
<style>
  /* ... */
</style>

<!-- GOOD: data URLs -->
<img src="data:image/png;base64,R0lGODdhEA...">

<!-- GOOD: absolute URLs -->
<img src="http://localhost/path/to/image.png">
<img src="file:///path/to/image.png">

Content from Phoenix templates

If your content is generated by a Phoenix template (and hence comes in the form of {:safe, iodata()} or %Phoenix.LiveView.Rendered{}), you will need to pass it to Phoenix.HTML.safe_to_string/1 first.

content = SomeView.render("body.html") |> Phoenix.HTML.safe_to_string()
ChromicPDF.print_to_pdf({:html, content})

concatenating-multiple-sources

Concatenating multiple sources

Pass a list of sources as first argument to instruct ChromicPDF to create a PDF file for each source and concatenate these using Ghostscript. This is particularly useful when some sections of your final document require a different page layout than others. You may use ChromicPDF.Template or tuple sources.

[
  ChromicPDF.Template.source_and_options(
    content: "<h1>First part with header</h1>",
    header_height: "20mm",
    header: "<p>Some header text</p>"
  ),
  {:html, "second part without header"}
]
|> ChromicPDF.print_to_pdf()

You can pass additional options to print_to_pdf/2 as usual, e.g. :output to control the return value handling.

Individual sources are processed sequentially and eventually concatenated, so expect runtime to increase linearly with the number of sources. The session timeout is applied per source. Each source emits the normal :print_to_pdf telemetry events. The final concatenation emits :join_pdfs events.

Please note that running PDF files through Ghostscript removes all structural annotations ("Tags") and hence disables accessibility features of assistive technologies. See On Accessibility / PDF/UA section for details.

custom-options-for-page-printtopdf

Custom options for Page.printToPDF

You can provide custom options for the Page.printToPDF call by passing a map to the :print_to_pdf option.

ChromicPDF.print_to_pdf(
  {:url, "file:///example.html"},
  print_to_pdf: %{
    # Margins are in given inches
    marginTop: 0.393701,
    marginLeft: 0.787402,
    marginRight: 0.787402,
    marginBottom: 1.1811,

    # Print header and footer (on each page).
    # This will print the default templates if none are given.
    displayHeaderFooter: true,

    # Even on empty string.
    # To disable header or footer, pass an empty element.
    headerTemplate: "<span></span>",

    # Example footer template.
    # They are completely unstyled by default and have a font-size of zero,
    # so don't despair if they don't show up at first.
    # There's a lot of documentation online about how to style them properly,
    # this is just a basic example. Also, take a look at the documentation for the
    # ChromicPDF.Template module.
    # The <span> classes shown below are interpolated by Chrome.
    footerTemplate: """
    <style>
      p {
        color: #333;
        font-size: 10pt;
        text-align: right;
        margin: 0 0.787402in;
        width: 100%;
        z-index: 1000;
      }
    </style>
    <p>
    Page <span class="pageNumber"></span> of <span class="totalPages"></span>
    </p>
    """
  }
)

Please note the camel-case. For a full list of options, please see the Chrome documentation at:

https://chromedevtools.github.io/devtools-protocol/tot/Page#method-printToPDF

page-size-and-margins

Page size and margins

Chrome will use the provided pagerWidth and paperHeight dimensions as the PDF paper format. Please be aware that the @page section in the body CSS is not correctly interpreted, see ChromicPDF.Template for a discussion.

header-and-footer

Header and footer

Chrome's support for native header and footer sections is a little bit finicky. Still, to the best of my knowledge, Chrome is currently the only well-functioning solution for HTML-to-PDF conversion if you need headers or footers that are repeated on multiple pages even in the presence of body elements stretching across a page break.

In order to make header and footer visible in the first place, you will need to be aware of a couple of caveats:

• You can not use any external (http:// or https://) resources in the header or footer, not even per absolute URL. You need to inline all your CSS and convert your images to data-URLs.

• Javascript is not interpreted either.

• HTML for header and footer is interpreted in a new page context which means no body styles will be applied. In fact, even default browser styles are not present, so all content will have a default font-size of zero, and so on.

• You need to make space for the header and footer templates first, by adding page margins. Margins can either be given using the marginTop and marginBottom options or with CSS styles. If you use the options, the height of header and footer elements will inherit these values. If you use CSS styles, make sure to set the height of the elements in CSS as well.

• Header and footer have a default padding to the page ends of 0.4 centimeters. To remove this, add the following to header/footer template styles (source).

  #header, #footer { padding: 0 !important; }

• Header and footer have a default zoom level of 1/0.75 so everything appears to be smaller than in the body when the same styles are applied.

• If header or footer are not displayed even though they should, make sure your HTML is valid. Tuning the margins for an hour looking for mistakes there, only to discover that you are missing a closing </style> tag, can be quite painful.

• Background colors are not applied unless you include -webkit-print-color-adjust: exact in your stylesheet.

See print_header_footer_template.html from the Chromium sources to see how these values are interpreted.

dynamic-content

Dynamic Content

Evaluate script before printing

In case your print source is generated by client-side scripts, for instance to render graphics or load additional resources, you can trigger these by evaluating a JavaScript expression before the PDF is printed.

evaluate = %{
  expression: """
  document.querySelector('body').innerHTML = 'hello world';
  """
}

ChromicPDF.print_to_pdf({:url, "http://example.net"}, evaluate: evaluate)

If your script returns a Promise, Chrome will wait for it to be resolved.

Wait for attribute on element

Some JavaScript libraries signal their successful initialization to the user by setting an attribute on a DOM element. The wait_for option allows you to wait for this attribute to be set before printing. It evaluates a script that repeatedly queries the element given by the query selector and tests whether it has the given attribute.

wait_for = %{
  selector: "#my-element",
  attribute: "ready-to-print"
}

ChromicPDF.print_to_pdf({:url, "http:///example.net"}, wait_for: wait_for)

@spec print_to_pdfa(source() | [source()], [
  pdf_option() | pdfa_option() | export_option()
]) ::
  export_return()

Prints a PDF and converts it to PDF/A in a single call.

See print_to_pdf/2 and convert_to_pdfa/2 for options.

example

Example

ChromicPDF.print_to_pdfa({:url, "https://example.net"})

@spec put_dynamic_name(atom()) :: atom()

Activate a particular ChromicPDF instance, which was started with the name option. After calling this function, all calls in the current process will use this instance of ChromicPDF.

You can use this function if you need to run ChromicPDF as part of a supervision tree with a particular name, for example:

defmodule MySupervisor do
  use Supervisor

  @impl true
  def init(opts) do
    children = [
      # other apps...
      {ChromicPDF, name: MyName}
    ]

    Supervisor.init(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

Returns the previously set name or the default name.

@spec start_link([global_option()]) :: Supervisor.on_start()

Starts ChromicPDF.

on-demand-mode

"On Demand" mode

If the given config includes the on_demand: true flag, this will not spawn a Chrome instance but instead hold the configuration in an Agent until a PDF print job is triggered. The print job will launch a temporary browser process and perform a graceful shutdown at the end.

Please note that the browser process is spawned from your client process and that these processes are linked. If your client process is trapping EXIT signals, you will receive a message when the browser is terminated.

@spec warm_up([local_chrome_option()]) :: {:ok, binary()}

Runs a one-off Chrome process to allow Chrome to initialize its caches.

On some infrastructure (notably, Github Actions), Chrome occasionally takes a long nap between process launch and first replying to DevTools commands. If meanwhile you happen to print a PDF (so, before any sessions have been spawned by the session pool), the session checkout will fail with a timeout error:

Caught EXIT signal from NimblePool.checkout!/4

      ** (EXIT) time out

This function mitigates the issue by launching a Chrome process via a shell command, bypassing ChromicPDF's internals.

usage

Usage

# in your test_helper.exs
{:ok, _} = ChromicPDF.warm_up()
...
ExUnit.start()

options

Options

This function accepts all options of print_to_pdf/2 related to external Chrome process.

If you pass discard_stderr: false, Chrome's standard error is returned.

{:ok, stderr} = ChromicPDF.warm_up(discard_stderr: false)
IO.inspect(stderr, label: "chrome stderr")

mix-task

Mix Task

Alternatively, you can choose to run a mix task as part of your CI script, see Mix.Tasks.ChromicPdf.WarmUp. The task currently does not accept any options.

...
$ mix chromic_pdf.warm_up
$ mix test