PDF Generation for your Rubies

This project is a Ruby gem that provides functionality for generating PDF files from HTML using the Chrome browser. It allows you to easily convert HTML content into PDF documents, making it convenient for tasks such as generating reports, invoices, or any other printable documents. The gem provides a simple and intuitive API for converting HTML to PDF, and it leverages the power and flexibility of the Chrome browser's rendering engine to ensure accurate and high-quality PDF output. With this gem, you can easily integrate PDF generation capabilities into your Ruby applications.

At the core, this project leverages the same rendering engine as Grover, but with significantly reduced overhead and dependencies. Instead of relying on the full Grover/Puppeteer/NodeJS stack, this project builds on Ferrum to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficient, thread-safe operations, providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.

This is how easy and powerfull PDF generation should be in Ruby:

require "palapala"
Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')

And this while having the most modern HTML/CSS/JS availlable to you: flex, grid, canvas, you name it.

Installation

To install the gem and add it to your application's Gemfile, execute the following command:

$ bundle add palapala_pdf

If you are not using bundler to manage dependencies, you can install the gem by running:

$ gem install palapala_pdf

Palapala PDF uses Ferrum inside and that one is pretty good at finding your Chrome or Chromium.

If you want the highest throughput, then use an external Chrome/Chromium. Just start it with (9222 is the default port):

chrome --headless --disable-gpu --remote-debugging-port=9222

Then you can run Palapala PDF against that Chrome/Chromium instance (see configuration).

Usage Instructions

To create a PDF from HTML content using the Palapala library, follow these steps:

1. Configuration:

Configure the Palapala library with the necessary options, such as the URL for the Ferrum browser and default settings like scale and format.

In a Rails context, this could be inside an initializer.

Palapala.setup do |config|
    # run against an external chrome/chromium or leave this out to run against a chrome that is started as a child process
    config.ferrum_opts = { url: 'http://localhost:9222' }
    config.defaults = { scale: 1, format: :A4 }
end

1. Create a PDF from HTML:

Create a PDF file from HTML in irb

gem install palapala_pdf

in IRB, load palapala and create a PDF from an HTML snippet:

require "palapala"
Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')

Instantiate a new Palapala::PDF object with your HTML content and generate the PDF binary data.

require "palapala"
binary_data = Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").binary_data

Paged CSS

Paged CSS is a subset of CSS designed for styling printed documents. It extends standard CSS to handle pagination, page sizes, headers, footers, and other aspects of printed content. Paged CSS is commonly used in scenarios where web content needs to be converted to PDFs or other paginated formats.

Headers and Footers

When using Chromium-based rendering engines, headers and footers are not controlled by the Paged CSS standard but are instead managed through specific settings in the rendering engine.

With palapala PDF headers and footers are defined using header_html and footer_html options. These allow you to insert HTML content directly into the header or footer areas.

Palapala::PDF.new(
  "<p>Hello world</>",
  header_html: '<div style="text-align: center;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
  footer_html: '<div style="text-align: center;">Generated with Palapala PDF</div>',
  margin: { top: "2cm", bottom: "2cm"}
).save("test.pdf")

Page size, orientation and margins

With CSS

todo example

As params

todo example

JS based rendering

  <html>
    <script type="text/javascript">
      document.addEventListener("DOMContentLoaded", () => {
        document.body.innerHTML += "<p>Current time from JS: " + new Date().toLocaleString() + "</p>";
      });
    </script>
    <body><p>Default body text.</p></body>
  </html>

Customisation

Ferrum

It is Ruby clean and high-level API to Chrome. All you need is Ruby and Chrome or Chromium. Ferrum connects to the browser by CDP protocol.

Highlighting some key Ferrum options in the context of PDF generation

• options Hash
  • :headless (String | Boolean) - Set browser as headless or not, true by default. You can set "new" to support new headless mode.
  • :xvfb (Boolean) - Run browser in a virtual framebuffer, false by default.
  • :extensions (Array[String | Hash]) - An array of paths to files or JS source code to be preloaded into the browser e.g.: ["/path/to/script.js", { source: "window.secret = 'top'" }]
  • :logger (Object responding to puts) - When present, debug output is written to this object.
  • :timeout (Numeric) - The number of seconds we'll wait for a response when communicating with browser. Default is 5.
  • :js_errors (Boolean) - When true, JavaScript errors get re-raised in Ruby.
  • :pending_connection_errors (Boolean) - When main frame is still waiting for slow responses while timeout is reached PendingConnectionsError is raised. It's better to figure out why you have slow responses and fix or block them rather than turn this setting off. Default is true.
  • :browser_path (String) - Path to Chrome binary, you can also set ENV variable as BROWSER_PATH=some/path/chrome.
  • :browser_options (Hash) - Additional command line options, see them all e.g. { "ignore-certificate-errors" => nil }
  • :ignore_default_browser_options (Boolean) - Ferrum has a number of default options it passes to the browser, if you set this to true then only options you put in :browser_options will be passed to the browser, except required ones of course.
  • :url (String) - URL for a running instance of Chrome. If this is set, a browser process will not be spawned.
  • :process_timeout (Integer) - How long to wait for the Chrome process to respond on startup.
  • :ws_max_receive_size (Integer) - How big messages to accept from Chrome over the web socket, in bytes. Defaults to 64MB. Incoming messages larger than this will cause a Ferrum::DeadBrowserError.

More details

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/palapala-app/palapala_pdf.

Contributors

• Kenneth Geerts - Your foundational contributions to simplicity are greatly appreciated.
• Eugen Neagoe - Thank you for your valuable input, feedback and opinions.

Sponsor This Project

If you find this project useful and would like to support its development, consider sponsoring or buying a coffee to help keep it going:

• GitHub Sponsors: Sponsor on GitHub
• Buy Me a Coffee: Buy a Coffee

Your support is greatly appreciated and helps maintain the project!

Findings

For Chrome, mode headless=new seems to be slower for pdf rendering cases.

On mac m3 (aug 24), chromium (brew install chromium) is about 3x slower then chrome? Maybe the chromium that get's installed is not ARM optimized?

Primitive benchmark

On a macbook m3, the throughput for 'hello world' PDF generation can reach around 25 docs/second when allowing for some concurrency. As Chrome is actually also very efficient, it scales really well for complex documents also. If you run this in Rails, the concurrency is being taken care of either by the front end thread pool or by the workers and you shouldn't have to think about this. (Using an external Chrome)

benchmarking 20 docs: 1x20, 2x10, 4x5, 5x4, 20x1 (c is concurrency, n is iterations)
Total time c:1, n:20 = 1.2048690000083297 seconds
Total time c:2, n:10 = 0.8969700000016019 seconds
Total time c:4, n:5 = 0.7497870000079274 seconds
Total time c:5, n:4 = 0.72492800001055 seconds
Total time c:20, n:1 = 0.7156629998935387 seconds

Rails

send_data

The send_data method in Rails is used to send binary data as a file download to the user's browser. It allows you to send any type of data, such as PDF files, images, or CSV files, directly to the user without saving the file on the server.

Here's an example of how to use send_data to send a PDF file:

def download_pdf
    pdf_data = Palapala::PDF.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
    send_data pdf_data, filename: "document.pdf", type: "application/pdf"
end

In this example, pdf_data is the binary data of the PDF file. The filename option specifies the name of the file that will be downloaded by the user, and the type option specifies the MIME type of the file.

render_to_string

The render_to_string method in Rails is used to render a view template to a string without sending it as a response to the user's browser. It allows you to generate HTML or other text-based content that can be used in various ways, such as sending it as an email, saving it to a file, or manipulating it further before sending it as a response.

Here's an example of how to use render_to_string to render a view template to a string:

def download_pdf
    html_string = render_to_string(template: "example/template", layout: "print", locals: { } )
    pdf_data = Palapala::PDF.new(html_string).binary_data
    send_data pdf_data, filename: "document.pdf", type: "application/pdf"
end

Docker

In docker as root you must pass the no-sandbox browser option:

Palapala.setup do |config|
  config.ferrum_opts = { 'no-sandbox': nil }
end

(from Ferrum) It has also been reported that the Chrome process repeatedly crashes when running inside a Docker container on an M1 Mac preventing Ferrum from working. Ferrum should work as expected when deployed to a Docker container on a non-M1 Mac.

Heroku

possible buildpacks

https://github.com/heroku/heroku-buildpack-chrome-for-testing

this buildpack install chrome and chromedriver, which is actually not needed, but it's maintained

https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-google-chrome

this buildpack installs chrome, which is all we need, but it's deprecated