Gerando PDFs A Partir de HTML com Rails

() translation by (you can also view the original English article)

Há inúmeras formas de gerar PDFs no Ruby e no Rails. Como você já conhece HTML e CSS, então usaremos o PDFKit para gerar arquivos PDFs usando HTML das visões e estilos padrões do Rails.

Introdução ao PDFKit

Internamente, o PDFKit usa o wkhtmltopdf (WebKit HTML to PDF), um mecanismo que pega HTML e CSS, renderiza-os usando Webkit e retorna-os como PDFs de alta qualidade.

Para começar, instalemos o wkhtmltopdf. Podemos baixar o binário ou instalá-lo através do Brew no Mac ou do repositório da sua versão Linux.

Também é preciso instalar a gem pdfkit e executar o seguinte código Ruby para gerar um PDF com o texto "Hello Envato!".

require "pdfkit"

kit = PDFKit.new(<<-HTML)
  <p>Hello Envato!</p>
HTML

kit.to_file("hello.pdf")

Criamos um arquivo, chamado hello.pdf, com o texto no topo.

An example of the PDF that was generated

PDFKit também gera PDFs a partir de uma URL. Se quisermos gerar um PDF do Google, podemos executar:

1	require "pdfkit"
2
3	PDFKit.new('https://www.google.com', :page_size => 'A3').to_file('google.pdf')

Como vemos, especificamos page_size—por padrão, A4 é usado. Veja a lista completa de opções.

An example of the Google homepage in PDF format

Estilizando Seu PDF Usando CSS

Mais cedo, mencionamos que geraremos arquivos PDF usando HTML e CSS. Nesse exemplo, adicionei um pouco de CSS para estilizar o HTML de um fatura simples:

require "pdfkit"

kit = PDFKit.new(<<-HTML)
  <style>
    * {
      color: grey;
    }
    h1 {
      text-align: center;
      color: black;
      margin-bottom: 100px;
    }
    .notes {
      margin-top: 100px;
    }

    table {
      width: 100%;
    }
    th {
      text-align: left;
      color: black;
      padding-bottom: 15px;
    }
  </style>

  <h1>Envato Invoice</h1>

  <table>
    <thead>
        <tr>
          <th>Description</th>
          <th>Price</th>
        </tr>
      </thead>
      <tbody>
          <tr>
            <td>Monthly Subscription to Tuts+</td>
            <td>$15</td>
          </tr>
      </tbody>
  </table>

  <div class="notes">
    <p><strong>Notes:</strong> This invoice was paid on the 23rd of March 2016 using your credit card ending on 1234.</p>
  </div>
HTML

kit.to_file("envato_invoice.pdf")

Geraremos o arquivo envato_invoice.pdf se executarmos o script. A foto mostra o resultado do exemplo:

Como vemos, o PDFKit é bem fácil de usar, se já conhecemos HTML e CSS. Podemos customizar ou estilizar o documento o quanto quisermos.

Usando PDFKit A Partir de uma Aplicação Rails

Agora, vejamos como usar o PDFKit em uma aplicação Rails, para gerarmos arquivos PDF dinamicamente, usando dados de nossos modelos. Nessa seção, construiremos uma aplicação Rails simples para gerar a "Fatura Envato", dinamicamente. Criemos uma nova aplicação rails e adicionemos três modelos:

$ rails new envato_invoices
$ cd envato_invoices

$ rails generate model invoice date:date client notes
$ rails generate model line_item description price:float invoice:references

$ rake db:migrate

Agora, adicionemos alguns exemplos na base de dados. Adicione o código abaixo no arquivo db/seeds.rb.

line_items = LineItem.create([
    { description: 'Tuts+ Subscription April 2016', price: 15.0 }, 
    { description: 'Ruby eBook', price: 9.90} ])
Invoice.create(
    client: 'Pedro Alonso', 
    total: 24.90, 
    line_items: line_items, 
    date: Date.new(2016, 4, 1))

Execute rake db:seed em seu terminal para adicionar uma fatura exemplo à base de dados.

Também queremos uma lista de faturas e o detalhamento ddas mesmas, então, usando geradores Rails, execute rails generate controller Invoices index show para criar o controlador e as visões.

app/controllers/invoices_controller.rb

class InvoicesController < ApplicationController
  def index
    @invoices = Invoice.all
  end

  def show
    @invoice = Invoice.find(params[:id])
  end
end

app/views/invoices/index.html.erb

<h1>Invoices</h1>
<ul>
  <% @invoices.each do |invoice| %>
  <li>
    <%= link_to "#{invoice.id} - #{invoice.client} - #{invoice.date.strftime("%B %d, %Y")} ", invoice_path(invoice) %>
  </li>
  <% end %>
</ul>

Precisamos modificar as rotas do Rails para direcionar para InvoicesController por padrão, então, editemos config/routes.rb:

Rails.application.routes.draw do
  root to: 'invoices#index'

  resources :invoices, only: [:index, :show]
end

Inicie um servidor com rails server e navegue até localhost:3000 para ver a lista de faturas.

app/views/invoices/show.html.erb

<div class="invoice">
  <h1>Envato Invoice</h1>

  <h3>To: <%= @invoice.client %></h3>
  <h3>Date: <%= @invoice.date.strftime("%B %d, %Y") %></h3>

  <table>
    <thead>
        <tr>
          <th>Description</th>
          <th>Price</th>
        </tr>
      </thead>
      <tbody>
        <% @invoice.line_items.each do |line_item| %>
          <tr>
            <td><%= line_item.description %></td>
            <td><%= number_to_currency(line_item.price) %></td>
          </tr>
        <% end %>
        <tr class="total">
          <td style="text-align: right">Total: </td>
          <td><%= number_to_currency(@invoice.total) %></span></td>
        </tr>
      </tbody>
  </table>

  <% if @invoice.notes %>
  <div class="notes">
    <p><strong>Notes:</strong> <%= @invoice.notes %></p>
  </div>
  <% end %>
</div>

O CSS para a página de detalhes dessa fatura pode ser movido para app/assets/stylesheets/application.scss.

.invoice {
  width: 700px;
  max-width: 700px;
  border: 1px solid grey;
  margin: 50px;
  padding: 50px;

  h1 {
    text-align: center;
    margin-bottom: 100px;
  }
  .notes {
    margin-top: 100px;
  }

  table {
    width: 90%;
    text-align: left;
  }
  th {
    padding-bottom: 15px;
  }

  .total td {
    font-size: 20px;
    font-weight: bold;
    padding-top: 25px;
  }
}

Então, ao clicarmos em uma fatura na listagem principal, veremos seu detalhamento:

Agora, estamos prontos para adicionar a funcionalidade de visualizar ou baixar faturas como PDF, à nossa aplicação Rails.

Classe InvoicePdf para Lidar com Renderização de PDF

Para renderizar as faturas como PDF, precisamos adicionar 3 gems ao Gemfile: PDFKit, render_anywhere e wkhtmltopdf-binary. Por padrão, Rails renderiza visões apenas em controladores, mas usando render_anywhere, podemos renderizá-las em modelos do domínio ou em serviços em segundo plano.

1	gem 'pdfkit'
2	gem 'render_anywhere'
3	gem 'wkhtmltopdf-binary'

Para não poluir nosso controlador com muita lógica, criaremos uma nova classe InvoicePdf dentro de app/models para envolver a lógica de geração do PDF.

require "render_anywhere"

class InvoicePdf
  include RenderAnywhere

  def initialize(invoice)
    @invoice = invoice
  end

  def to_pdf
    kit = PDFKit.new(as_html, page_size: 'A4')
    kit.to_file("#{Rails.root}/public/invoice.pdf")
  end

  def filename
    "Invoice #{invoice.id}.pdf"
  end

  private

    attr_reader :invoice

    def as_html
      render template: "invoices/pdf", layout: "invoice_pdf", locals: { invoice: invoice }
    end
end

Essa classe receberá a fatura a ser renderizada por parâmetro, em seu construtor. O método privado as_html lê as visões invoices/pdf e layout_pdf, que serão usadas para gerar o HTML necessário para a renderização do PDF. Por último, o método to_pdf usa o PDFKit para salvar o PDF no diretório public do Rails.

Provavelmente, você gerará um nome dinâmico para o PDF para que não seja sobrescrito por acidente em sua aplicação real. Talvez até queira salvar o arquivo na AWS S3 ou em um diretório privado, mas essas ações estão além desse tutorial.

/app/views/invoices/pdf.html.erb

<div class="invoice">
  <h1>Envato Invoice</h1>

  <h3>To: <%= invoice.client %></h3>
  <h3>Date: <%= invoice.date.strftime("%B %d, %Y") %></h3>

  <table>
    <thead>
        <tr>
          <th>Description</th>
          <th>Price</th>
        </tr>
      </thead>
      <tbody>
        <% invoice.line_items.each do |line_item| %>
          <tr>
            <td><%= line_item.description %></td>
            <td><%= number_to_currency(line_item.price) %></td>
          </tr>
        <% end %>
        <tr class="total">
          <td style="text-align: right">Total: </td>
          <td><%= number_to_currency(invoice.total) %></span></td>
        </tr>
      </tbody>
  </table>

  <% if invoice.notes %>
  <div class="notes">
    <p><strong>Notes:</strong> <%= invoice.notes %></p>
  </div>
  <% end %>
</div>

/app/views/layouts/invoice_pdf.erb

<!DOCTYPE html>
<html>
<head>
  <title>Envato Invoices</title>
  <style>
    <%= Rails.application.assets.find_asset('application.scss').to_s %>
  </style>
</head>
<body>
  <%= yield %>
</body>
</html>

Algo a se notar nesse arquivo de layout é que renderizamos os estilos dentro dele. WkHtmlToPdf funciona melhor se fizermos desse jeito.

DownloadsController para Renderizar o PDF da Fatura

Agora, precisamos de uma rota e um controlador que chame a classe InvoicePdf para enviar o arquivo PDF para o navegador. Então, edite o arquivo config/routes.rb, assim:

Rails.application.routes.draw do
  root to: "invoices#index"

  resources :invoices, only: [:index, :show] do
    resource :download, only: [:show]
  end
end

Se usarmos rake routes, veremos a lista de rotas disponíveis na aplicação:

          Prefix Verb URI Pattern                              Controller#Action
            root GET  /                                        invoices#index
invoice_download GET  /invoices/:invoice_id/download(.:format) downloads#show
        invoices GET  /invoices(.:format)                      invoices#index
         invoice GET  /invoices/:id(.:format)                  invoices#show

Crie app/controllers/downloads_controller.rb:

class DownloadsController < ApplicationController

  def show
    respond_to do |format|
      format.pdf { send_invoice_pdf }
    end
  end

  private

  def invoice_pdf
    invoice = Invoice.find(params[:invoice_id])
    InvoicePdf.new(invoice)
  end

  def send_invoice_pdf
    send_file invoice_pdf.to_pdf,
      filename: invoice_pdf.filename,
      type: "application/pdf",
      disposition: "inline"
  end
end

Como podemos ver, quando a requisição buscar um arquivo PDF, o send_invoice_pdf a processará. O método invoice_pdf encontrará a fatura usando o ID e criará uma instância de InvoicePdf. Então, send_invoice_pdf chamará o método to_pdf, enviando o arquivo gerado para o navegador.

Outra coisa a se notar é que estamos passando disposition: "inline" para send_file. Esse parâmetro envia o arquivo para o navegador, que o mostrará na tela. Se quiser forçar o download do arquivo, você precisa passar disposition: "attachment".

Adicione um botão de download para a fatura na visão app/views/invoices/show.html.erb:

1	<%= link_to "Download PDF",
2	invoice_download_path(@invoice, format: "pdf"),
3	target: "_blank",
4	class: "download" %>

Execute a aplicação, navegue pelos detalhes da fatura, clique em download e veja uma nova abar mostrando a fatura em PDF.

Renderizando PDF como HTML Durante Desenvolvimento

Ao criar o código HTML para seu PDF, é preciso gerar um novo PDF toda vez que quiser testar uma mudança. Algumas vezes, isso pode ser lento. Por isso, pode ser bem útil poder visualizar o HTML gerado que será convertido em PDF. Apenas precisamos editar o arquivo /app/controllers/downloads_controller.rb:

class DownloadsController < ApplicationController

  def show
    respond_to do |format|
      format.pdf { send_invoice_pdf }

      if Rails.env.development?
        format.html { render_sample_html }
      end
    end
  end

  private

  def invoice
    Invoice.find(params[:invoice_id])
  end

  def invoice_pdf
    InvoicePdf.new(invoice)
  end

  def send_invoice_pdf
    send_file invoice_pdf.to_pdf,
      filename: invoice_pdf.filename,
      type: "application/pdf",
      disposition: "inline"
  end

  def render_sample_html
    render template: "invoices/pdf", layout: "invoice_pdf", locals: { invoice: invoice }
  end
end

Agora, o método show também lida com requisições HTML em modo de desenvolvimento. A rota para a fatura em PDF seria algo assim: http://localhost:3000/invoices/1/download.pdf. Se altararmos para http://localhost:3000/invoices/1/download.html, podemos ver o HTML usado para gerar o PDF da fatura.

Dado o código acima, gerar arquivos PDF usando Ruby on Rails é bem simples e direto, assumindo que seja familiar com a lingugem Ruby e a framework Rails. Talvez, o melhor aspecto desse processo é que não é preciso aprender uma nova linguagem ou coisas específicas sobre geração de PDF.

Espero que esse tutorial tenha sido útli. Por favor, faça quaisquer perguntas, comentários ou feedback na seção de comentário e ficarei feliz em responder!