Содержание
Эта статья была первоначально написана Эстимо Кириной в блоге разработчиков Honeybadger.
Мы живем в мире документов. Практически в каждом аспекте бизнеса и жизни мы сталкиваемся с документами. Работаете ли вы со счетами и контрактами на своем рабочем месте или наслаждаетесь любимым мистическим триллером - так или иначе, документ имеет отношение к делу. Формат файлов, который лежит в основе большинства этих документов, - универсальный переносной формат, чаще всего называемый PDF.
В контексте приложения на Ruby или Rails PDF-файл может быть создан путем преобразования существующих HTML/CSS-файлов в PDF-документы или с помощью доменно-специфического языка (DSL), специально созданного для генерации PDF. В этой статье мы расскажем, как использовать эти два метода для создания PDF-файлов с помощью трех разных гемов: PDFkit и WickedPDF, которые используют метод преобразования HTML/CSS в PDF, и гема Prawn, который вместо этого использует мощный DSL.
Мы также обсудим, как стилизовать ваши PDF-файлы, чтобы повысить их удобство для пользователя, в том числе как вставлять в них изображения. В завершение мы расскажем, как использовать Action mailer для отправки писем с PDF-вложениями.
Приступим.
Необходимые условия
Чтобы следовать приведенным в этой статье примерам, вам потребуется знать несколько основ:
Ruby 2.0+ установлен Bundler установлен Rails 6.0+ установлен базовый или средний уровень владения Ruby (и Rails)
Краткое введение в формат файлов PDF
PDF означает ”портативный формат документов”, формат файлов, разработанный компанией Adobe в начале 90-х годов, чтобы упростить представление документов, не слишком полагаясь на базовое системное программное обеспечение, аппаратное обеспечение или операционную систему.
Итак, давайте посмотрим, как можно использовать этот популярный формат файлов в контексте приложения на Rails. Для этого мы рассмотрим три популярные программы для создания PDF-файлов.
WickedPDF
Мы начнем с гема WickedPDF, который работает на основе библиотеки командной строки wkhtmltopdf.
Этот гем работает, преобразуя HTML/CSS-документы в их эквиваленты в формате PDF.
Когда использовать WickedPDF
Если вы предпочитаете использовать уже имеющиеся навыки работы с HTML/CSS вместо того, чтобы изучать новый DSL для создания PDF, то гем WickedPDF будет хорошим выбором.
Установка и использование WickedPDF
Добавьте гем (включите гем wkhtmltopdf, так как он поддерживает WickedPDF) в Gemfile вашего приложения, а затем выполните команду
bundle install
:
gem 'wicked_pdf' gem 'wkhtmltopdf-binary'.
После этого запустите генератор, чтобы получить файл инициализатора WickedPDF:
rails generate wicked_pdf
Затем нам нужно сообщить нашему Rails-приложению о расширении PDF-файла, отредактировав файл инициализатора mime_types.rb, находящийся в папке
директории . Совет: если говорить очень простым языком, то тип mime - это идентификатор форматов файлов и того, как эти форматы должны передаваться по Сети.\_ ruby Mime::Type.register “application/pdf”, :pdf`
Таким образом, наше Rails-приложение знает, как реагировать на тип файла PDF.
Наконец, вам нужно отредактировать файл контроллера, чтобы он реагировал на формат PDF (в моем случае я буду работать с действием show контроллера orders, но вы можете использовать это в любом контроллере, который используется в вашем проекте, где требуется генерация PDF-файлов):
class OrdersController < ApplicationController
def show
respond_to do |format|
format.html
format.pdf do
# Важно включить соответствующий шаблон представления, иначе вы получите ошибку отсутствия шаблона.
render pdf: "#{@order.id}", template: 'orders/show.html.erb'
end
end
end
end
Теперь, если вы добавите ”.pdf” к вашему представлению show, вас поприветствует соответствующее PDF-представление. Ура! Пока что наше приложение может генерировать PDF-файлы заказов. Однако что будет, если коллега из отдела логистики попросит переслать эти документы в виде вложений по электронной почте? Как это сделать? ## PDF Email Attachments Via WickedPDF And ActionMailer Расширяя наш пример с приложением для создания заказов, предположим, что коллеге из отдела логистики нужны детали каждого поступившего заказа в виде вложения в электронную почту. Сначала мы создадим соответствующий почтовик:
bash rails generate mailer OrderMailer new_order
Отредактируйте сгенерированный почтовик, чтобы включить в него вложение в виде PDF-файла:
class OrderMailer < ApplicationMailer
def new_order
@order = Order.first
attachments["Order-#{@order.id}.pdf"] = WickedPdf.new.pdf_from_string(
render_to_string(template: 'orders/show.html.erb', pdf: "Order-#{@order.id}")
)
mail to: "to@example.org"
end
end
После этого посетите
Или, если у вас есть существующее приложение Rails, отредактируйте Gemfile следующим образом:
gem 'prawn'.
Затем запустите bundle, чтобы установить его для вашего приложения.
После успешной установки гема, как и в случае с гемом WickedPDF, вам нужно сделать так, чтобы ваше приложение узнало о типе файлов “PDF”, зарегистрировав его как тип mime.
Откройте файл
файл и добавьте следующую строку: ruby Mime::Type.register “application/pdf”, :pdf“.
Теперь, чтобы увидеть гем в действии, перейдите к контроллеру, на который вы хотите ответить PDF (я использую тот же пример, что и в примере кода WickedPDF):
class OrdersController < ApplicationController
def index
@orders = Order.all
end
def show
@order = Order.find(params[:id])
respond_to do |format|
format.html
format.pdf do
pdf = Prawn::Document.new
pdf.text "This is order no: #{@order.id}"
send_data pdf.render, filename: "#{@order.id}.pdf", type: 'application/pdf', disposition: 'inline'
end
end
end
def new
@order = Order.new
end
end
DSL гема Prawn также может быть использован для рисования сложных векторных изображений, а также для вставки изображений в генерируемые PDF-документы (в рамках данной статьи мы покажем только функцию вставки изображений).
Добавление изображений в PDF с помощью Prawn
Надеемся, теперь вы имеете базовое представление о том, как стилизовать PDF-документы в вашем Rails-приложении. Однако что, если вы хотите добавить изображения?
Используя наш очень упрощенный пример с гемом Prawn, приведенный ранее, вы можете сделать это следующим образом (показано только действие show):
def show respond_to do |format|
format.html
format.pdf do
pdf = Prawn::Document.new
pdf.text "This is order no: #{@order.id}"
pdf.image Rails.root.join("public", "images", '1.png').to_s, width: 450
send_data pdf.render, filename: "#{@order.id}.pdf", type: 'application/pdf', disposition: 'inline'
end
end
Очевидно, что этот самоцвет обладает большим потенциалом, чем тот, который мы показали до сих пор. Чтобы узнать больше, зайдите на сайт Prawn.
Гем PDFkit
Как и гем WickedPDF, гем PDFkit использует wkhtmltopdf в бэкенде для преобразования простых HTML и CSS файлов в PDF документы.
Когда использовать PDFkit
Если вам нужно часто конвертировать HTML в PDF, то этот гем будет хорошим выбором.
Использование PDFkit
Добавьте гем:
gem install pdfkit.
Не забудьте установить библиотеку wkhtmltopdf. Для этого просто следуйте инструкциям, найденным здесь.
После этого создайте простой Ruby-файл в вашей любимой папке (мой называется “testing-pdfkit.rb”, но вы можете назвать свой как угодно).
Затем отредактируйте свой файл так, чтобы он выглядел так, как показано ниже:
require "pdfkit"
kit = PDFKit.new(<<-HTML)
<h1>Мой счет-фактура PDFkit</h1>
<table>
<thead>
<tr>
<th>Item</th>
<th>Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>Item #1</td>
<td>$27.00</td>
</tr>
<tr>
<td>Item #2</td>
<td>$100.00</td>
</tr>
</tbody>
</table>
HTML
kit.to_file("pdfkit_invoice.pdf")
Запустите
ruby testing-pdfkit.rb
чтобы сгенерировать PDF-файл в корневой папке вашего скрипта.
В примере, который мы показали, получится очень простой PDF-документ. Однако, применив некоторые базовые стили, мы можем сделать его намного лучше.
Применение базовых стилей к PDF-файлам с помощью PDFkit
Вполне вероятно, что PDF-документы, с которыми вы взаимодействуете в повседневной жизни, какими бы они ни были, например любимая электронная книга или отчет компании, выглядят отполированными и профессиональными.
Далее давайте добавим некоторые стили в наш пример кода с помощью гема PDFkit:
require "pdfkit"
kit = PDFKit.new(<<-HTML)
# CSS стили добавлены...
<style>
table {
background-color: #ff33cc;
}
tbody tr:nth-child(odd) {
background-color: #ff33cc;
}
tbody tr:nth-child(even) {
background-color: #e495e4;
}
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>Мой счет-фактура PDFkit</h1>
<table>
<thead>
<tr>
<th>Item</th>
<th>Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>Item #1</td>
<td>$27.00</td>
</tr>
<tr>
<td>Item #2</td>
<td>$100.00</td>
</tr>
</tbody>
</table>
HTML
kit.to_file("pdfkit_invoice.pdf")
Совет: Использование более продвинутой библиотеки PDF, такой как Prawn gem, даст вам еще больше возможностей для стилизации. Ознакомьтесь с руководством по Prawn, чтобы узнать все возможности этого гема.
Подведение итогов
В этой статьеВ этой статье мы рассказали о том, как создавать PDF-документы с помощью трех драгоценных камней. Мы также рассмотрели, как использовать различные камни для добавления изображений в PDF, отправки PDF-вложений по электронной почте и добавления основных стилей в документы.
Эта статья - скорее набросок, чем глубокое погружение. Вы можете изучить уникальный стиль создания PDF-файлов с помощью каждого самоцвета, а также способы создания более сложных документов, чем те, которые мы рассмотрели здесь.
Счастливого кодинга!