ChromicPDF Documentation

ChromicPDF is a supervision tree rather than a standalone application. To use it, you must add it to your runtime dependencies and include it in your application's supervision tree.

1. Add dependency

Add {:chromic_pdf, "~> 1.17"} to your mix.exs file.

2. Start in supervision tree

Add ChromicPDF to your list of children in your application's start/2 function.

# mix.exs
def deps do
  [ {
    :chromic_pdf,
    "~> 1.17"
  }
]
end

# lib/my_app/application.ex
def MyApp.Application do
  def start(_type, _args) do
    children = [
      # other apps...
      ChromicPDF
    ]

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

To run ChromicPDF, you must have the following installed on your system:

• Chromium or Chrome: Required for the core HTML-to-PDF rendering.
• Ghostscript (Optional): Required if you want to use PDF/A support or concatenate multiple sources.

The ProtocolOptions module allows you to replace a standard wait_for option with an automated evaluate script. If you provide a wait_for option with a selector and an attribute, the library will automatically inject a JavaScript loop that waits until the specified element possesses that attribute before proceeding.

Example wait_for structure:

%{selector: ".my-element", attribute: "data-ready"}

If you need to separate PDF worker pools or provide a custom API for your PDF module, you can use ChromicPDF.Supervisor. You do this by defining a module that uses ChromicPDF.Supervisor and adding it to your application's supervision tree.

To use it, define a module in your application and include it in your start/2 function.

defmodule MyApp.MyPDFGenerator do
  use ChromicPDF.Supervisor
end

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      MyApp.MyPDFGenerator
    ]

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

The ChromicPDF.Plug module implements a request forwarding mechanism. It allows an internal endpoint (serving incoming requests from Chrome) to forward the request back to the original caller process that initiated the PDF generation.

To use it, you must register the plug in your router and call ChromicPDF.print_to_pdf/2 using the {:plug, ...} tuple format.

### 1. Register the plug in your router
forward "/makepdf", ChromicPDF.Plug

### 2. Call print_to_pdf from the caller side
ChromicPDF.print_to_pdf({
  {:plug,
    url: "http://localhost:4000/makepdf",
    forward: {MyTemplate, :render, [%{hello: :world}]
  }
})

### 3. Implement your template
defmodule MyTemplate do
  def render(conn, assigns) do
    # Either send response via conn (and return conn)
    # Or return content to be sent by the plug
  end
end

The ChromicPDF.Template module provides tools to control PDF page dimensions (e.g., A4). You can use ChromicPDF.Template.source_and_options/1 to prepare a source and options map, which is then passed to ChromicPDF.print_to_pdf/2.

[content: "<p>Hello Template</p>", size: :a4]
|> ChromicPDF.Template.source_and_options()
|> ChromicPDF.print_to_pdf()

The main API allows you to render HTML from URLs or local files into PDF format.

Print a URL to a file

Use ChromicPDF.print_to_pdf/2 with a {:url, url} tuple and an output: option specifying the destination path.

Print to PDF/A with a callback

Use ChromicPDF.print_to_pdfa/2 to generate PDF/A compliant files. This function accepts a callback function that receives the path to the generated temporary PDF file, which is useful for uploading to S3 or sending via email.

# Prints a local HTML file to PDF.
ChromicPDF.print_to_pdf({:url, "https://example.net"}, output: "example.pdf")

# Print to PDF/A using a callback for the generated file path
ChromicPDF.print_to_pdfa({:url, "file:///example.html"}, output: fn pdf ->
  # Send pdf via mail, upload to S3, ...
end)

If Ghostscript is installed, you can pass a list of sources to ChromicPDF.print_to_pdf/2. The library will automatically concatenate them into a single PDF file.

ChromicPDF.print_to_pdf([{:html, "page 1"}, {:html, "page 2"}], output: "joined.pdf")

Captures a screenshot of a page. This call blocks until the screenshot is created.

Options

• capture_screenshot: %{format: "jpeg"}: Specify image format (e.g., png, jpeg).
• full_page: true: Increases the viewport to fit the entire content (requires Chrome 91+).

Output

Returns {:ok, blob} where blob is the Base64-encoded image.

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