Installation

The ruby client is distributed via a minimum dependency ruby gem. This guide expects that you know how to install and work with gems.

Add it to your gem file.

Gemfile
gem 'breezy_pdf'

As a HTTP Middleware

BreezyPDF includes a Rack middleware which will automatically intercept HTTP GET requests to a resource, render the HTML at that given URL, and redirect the client to the URL which will eventually return the generated PDF.

Ruby on Rails

application.rb
config.middleware.use BreezyPDF::Middleware

Rack

app.rb
use BreezyPDF::Middleware

Configuration

BreezyPDF has some extensive configuration options. This configuration should be done when your project is initialized.

Specifying your secret API key is the only required configuration.

Ruby on Rails

config/initializers/breezy_pdf.rb
BreezyPDF.setup do |config|
    config.secret_api_key = "YOUR_SECRET_API_KEY"
    # ...
end

Other

app.rb
BreezyPDF.setup do |config|
    config.secret_api_key = "YOUR_SECRET_API_KEY"
    # ...
end

Render your first PDF as an HTTP request

The default configuration options are optimized for rendering PDF's in your local development enviornment. You may or may not want to modify these settings for your production environment.

• config.middleware_path_matchers = [/\.pdf/]

• config.treat_urls_as_private = true

• config.upload_assets = true

• config.asset_selectors = %w(img script link[rel="stylesheet"])

• config.asset_cache = BreezyPDF::Cache::Null.new

Let's assume you have an HTML report that lives at the path /reports/quarterly. BreezPDF will automatically intercept and convert the report to a PDF by adding a .pdf extension to the URL. Let's add a button in your HTML.

<a href="/reports/quarterly.pdf">Download PDF</a>

Clicking the link will redirect you to the PDF version of your Quarterly Report!

Configure how your page is rendered

BreezyPDF provides extensive control over how you might want your page to render. This can be done via meta tags anywhere within the HTML document. See the Metadata section for options.

Add a Loading/Progress/Busy Animation

Generation of your PDF may take a few seconds, so leaving your user hanging without any UI indication might not be the best.

<a href="/reports/quarterly.pdf" class="pdf-link">Download as PDF</a>
​
<script type="text/javascript">
  $('.pdf-link').on('click', function(clickEv) {
    var startTime     = new Date();
    var targetEl      = $(clickEv.target);
    var modalEl       = $('#pdf-loading'); // An existing bootstrap modal in this example
    var ajaxRequest   = new XMLHttpRequest();
​
    clickEv.preventDefault();
​
    ajaxRequest.addEventListener('load', function(ev) {
      modalEl.modal('hide');
​
      window.location = ev.currentTarget.responseURL;
    })
​
    modalEl.modal('show');
​
    ajaxRequest.open('GET', targetEl.attr('href'));
    ajaxRequest.send();
  })
</script>

Pragmatic Usage

BreezyPDF facilitates generating PDF's outside of a HTTP request.

def invoice_mailer(user, invoice)
  asset_host = Rails.env.production? ? Rails.application.config.action_controller.asset_host : "http://localhost:3000"
​
  metadata = { width: 8.5, width: 11 }
​
  html = ActionController::Renderer.render(template "invoices/show", assigns: { invoice: invoice }, locals: { current_user: user })
  pdf = BreezyPDF::HTML2PDF.new(asset_host, html, metadata)
​
  attachments["invoice-#{invoice.id}.pdf"] = pdf.to_file.read
  @pdf_url = pdf.to_url
end