README.md in wicked_pdf-1.1.0 vs README.md in wicked_pdf-1.2.0
- old
+ new
@@ -1,12 +1,12 @@
-# Wicked PDF [](http://travis-ci.org/mileszs/wicked_pdf) [](http://badge.fury.io/rb/wicked_pdf)
+# Wicked PDF [](http://badge.fury.io/rb/wicked_pdf) [](http://travis-ci.org/mileszs/wicked_pdf) [](https://codeclimate.com/github/mileszs/wicked_pdf) [](https://www.codetriage.com/mileszs/wicked_pdf)
## A PDF generation plugin for Ruby on Rails
Wicked PDF uses the shell utility [wkhtmltopdf](http://wkhtmltopdf.org) to serve a PDF file to a user from HTML. In other words, rather than dealing with a PDF generation DSL of some sort, you simply write an HTML view as you would normally, then let Wicked PDF take care of the hard stuff.
-_Wicked PDF has been verified to work on Ruby versions 1.8.7 through 2.3; Rails 2 through 5.0_
+_Wicked PDF has been verified to work on Ruby versions 1.8.7 through 2.6; Rails 2 through 5.2_
### Installation
Add this to your Gemfile and run `bundle install`:
@@ -24,21 +24,23 @@
```
to `config/initializers/mime_types.rb` in older versions of Rails.
Because `wicked_pdf` is a wrapper for [wkhtmltopdf](http://wkhtmltopdf.org/), you'll need to install that, too.
-The simplest way to install all of the binaries (Linux, OSX, Windows) is through the gem [wkhtmltopdf-binary](https://github.com/steerio/wkhtmltopdf-binary).
-To install that, add a second gem
+The simplest way to install all of the binaries on most Linux or OSX systems is through the gem [wkhtmltopdf-binary](https://github.com/zakird/wkhtmltopdf_binary_gem). Builds for other systems are available [here](https://wkhtmltopdf.org/downloads.html)
+To install that gem, add this:
```ruby
gem 'wkhtmltopdf-binary'
```
To your Gemfile and run `bundle install`.
-This wrapper may trail in versions, at the moment it wraps the 0.9 version of `wkhtmltopdf` while there is 0.12 version available. Some of the advanced options listed below are not available with 0.9.
+This gem currently installs version 0.12.x of `wkhtmltopdf`. Some of the options listed below are specific 0.9 or below, and others are for 0.12 and up.
+You can see what flags are supported for the current version in [wkhtmltopdf's auto-generated manual](https://wkhtmltopdf.org/usage/wkhtmltopdf.txt)
+
If your wkhtmltopdf executable is not on your webserver's path, you can configure it in an initializer:
```ruby
WickedPdf.config = {
exe_path: '/usr/local/bin/wkhtmltopdf'
@@ -104,46 +106,49 @@
</div>
</body>
</html>
```
+#### Asset pipeline usage
+
+It is best to precompile assets used in PDF views. This will help avoid issues when it comes to deploying, as Rails serves asset files differently between development and production (`config.assets.compile = false`), which can make it look like your PDFs work in development, but fail to load assets in production.
+
+ config.assets.precompile += ['blueprint/screen.css', 'pdf.css', 'jquery.ui.datepicker.js', 'pdf.js', ...etc...]
+
#### CDN reference
In this case, you can use that standard Rails helpers and point to the current CDN for whichever framework you are using. For jQuery, it would look somethng like this, given the current versions at the time of this writing.
```html
<!doctype html>
<html>
<head>
<%= javascript_include_tag "http://code.jquery.com/jquery-1.10.0.min.js" %>
<%= javascript_include_tag "http://code.jquery.com/ui/1.10.3/jquery-ui.min.js" %>
```
-#### Asset pipeline usage
-The way to handle this for the asset pipeline on Heroku is to include these files in your asset precompile list, as follows:
-
- config.assets.precompile += ['blueprint/screen.css', 'pdf.css', 'jquery.ui.datepicker.js', 'pdf.js', ...etc...]
-
### Advanced Usage with all available options
```ruby
class ThingsController < ApplicationController
def show
respond_to do |format|
format.html
format.pdf do
render pdf: 'file_name',
disposition: 'attachment', # default 'inline'
template: 'things/show',
- file: "#{Rails.root}/files/foo.erb"
- layout: 'pdf', # for a pdf.html.erb file
+ file: "#{Rails.root}/files/foo.erb",
+ inline: '<!doctype html><html><head></head><body>INLINE HTML</body></html>',
+ layout: 'pdf', # for a pdf.pdf.erb file
wkhtmltopdf: '/usr/local/bin/wkhtmltopdf', # path to binary
show_as_html: params.key?('debug'), # allow debugging based on url param
orientation: 'Landscape', # default Portrait
page_size: 'A4, Letter, ...', # default A4
page_height: NUMBER,
page_width: NUMBER,
save_to_file: Rails.root.join('pdfs', "#{filename}.pdf"),
save_only: false, # depends on :save_to_file being set first
+ default_protocol: 'http',
proxy: 'TEXT',
basic_auth: false # when true username & password are automatically sent from session
username: 'TEXT',
password: 'TEXT',
title: 'Alternate Title', # otherwise first page title is used
@@ -169,14 +174,15 @@
disable_internal_links: true,
disable_external_links: true,
print_media_type: true,
disable_smart_shrinking: true,
use_xserver: true,
- background: false, # backround needs to be true to enable background colors to render
+ background: false, # background needs to be true to enable background colors to render
no_background: true,
viewport_size: 'TEXT', # available only with use_xserver or patched QT
extra: '', # directly inserted into the command to wkhtmltopdf
+ raise_on_all_errors: nil, # raise error for any stderr output. Such as missing media, image assets
outline: { outline: true,
outline_depth: LEVEL },
margin: { top: SIZE, # default 10 (mm)
bottom: SIZE,
left: SIZE,
@@ -228,11 +234,12 @@
no_dots: true,
disable_dotted_lines: true,
disable_links: true,
disable_toc_links: true,
disable_back_links:true,
- xsl_style_sheet: 'file.xsl'} # optional XSLT stylesheet to use for styling table of contents
+ xsl_style_sheet: 'file.xsl'}, # optional XSLT stylesheet to use for styling table of contents
+ progress: proc { |output| puts output } # proc called when console output changes
end
end
end
end
```
@@ -265,30 +272,62 @@
# create a pdf from a URL
pdf = WickedPdf.new.pdf_from_url('https://github.com/mileszs/wicked_pdf')
# create a pdf from string using templates, layouts and content option for header or footer
pdf = WickedPdf.new.pdf_from_string(
- render_to_string('templates/pdf', layout: 'pdfs/layout_pdf'),
+ render_to_string('templates/pdf', layout: 'pdfs/layout_pdf.html'),
footer: {
- content: render_to_string(layout: 'pdfs/layout_pdf')
+ content: render_to_string(
+ 'templates/footer',
+ layout: 'pdfs/layout_pdf.html'
+ )
}
)
+# It is possible to use footer/header templates without a layout, in that case you need to provide a valid HTML document
+pdf = WickedPdf.new.pdf_from_string(
+ render_to_string('templates/full_pdf_template'),
+ header: {
+ content: render_to_string('templates/full_header_template')
+ }
+)
+
# or from your controller, using views & templates and all wicked_pdf options as normal
pdf = render_to_string pdf: "some_file_name", template: "templates/pdf", encoding: "UTF-8"
# then save to a file
save_path = Rails.root.join('pdfs','filename.pdf')
File.open(save_path, 'wb') do |file|
file << pdf
end
+
+# you can also track progress on your PDF generation, such as when using it from within a Resque job
+class PdfJob
+ def perform
+ blk = proc { |output|
+ match = output.match(/\[.+\] Page (?<current_page>\d+) of (?<total_pages>\d+)/)
+ if match
+ current_page = match[:current_page].to_i
+ total_pages = match[:total_pages].to_i
+ message = "Generated #{current_page} of #{total_pages} pages"
+ at current_page, total_pages, message
+ end
+ }
+ WickedPdf.new.pdf_from_string(html, progress: blk)
+ end
+end
```
If you need to display utf encoded characters, add this to your pdf views or layouts:
```html
<meta charset="utf-8" />
```
-
+If you need to return a PDF in a controller with Rails in API mode:
+```ruby
+pdf_html = ActionController::Base.new.render_to_string(template: 'controller_name/action_name', layout: 'pdf')
+pdf = WickedPdf.new.pdf_from_string(pdf_html)
+send_data pdf, filename: 'file.pdf'
+```
### Page Breaks
You can control page breaks with CSS.
Add a few styles like this to your stylesheet or page:
@@ -338,18 +377,31 @@
```ruby
# in application.rb (Rails3) or environment.rb (Rails2)
require 'wicked_pdf'
config.middleware.use WickedPdf::Middleware
```
-If you want to turn on or off the middleware for certain urls, use the `:only` or `:except` conditions like so:
+If you want to turn on or off the middleware for certain URLs, use the `:only` or `:except` conditions like so:
```ruby
# conditions can be plain strings or regular expressions, and you can supply only one or an array
config.middleware.use WickedPdf::Middleware, {}, only: '/invoice'
config.middleware.use WickedPdf::Middleware, {}, except: [ %r[^/admin], '/secret', %r[^/people/\d] ]
```
If you use the standard `render pdf: 'some_pdf'` in your app, you will want to exclude those actions from the middleware.
+
+### Include in an email as an attachment
+
+To include a rendered pdf file in an email you can do the following:
+
+```ruby
+attachments['attachment.pdf'] = WickedPdf.new.pdf_from_string(
+ render_to_string('link_to_view.pdf.erb', layout: 'pdf')
+)
+```
+
+This will render the pdf to a string and include it in the email. This is very slow so make sure you schedule your email delivery in a job.
+
### Further Reading
Mike Ackerman's post [How To Create PDFs in Rails](https://www.viget.com/articles/how-to-create-pdfs-in-rails)
Andreas Happe's post [Generating PDFs from Ruby on Rails](http://www.snikt.net/blog/2012/04/26/wicked-pdf/)
@@ -373,10 +425,12 @@
<%= params.key?('debug') ? image_tag('foo') : wicked_pdf_image_tag('foo') %>
```
#### Gotchas
-If one image from your HTML cannot be found (relative or wrong path for ie), others images with right paths **may not** be displayed in the output PDF as well (it seems to be an issue with wkhtmltopdf).
+If one image from your HTML cannot be found (relative or wrong path for example), others images with right paths **may not** be displayed in the output PDF as well (it seems to be an issue with wkhtmltopdf).
+
+wkhtmltopdf may render at different resolutions on different platforms. For example, Linux prints at 75 dpi (native for WebKit) while on Windows it's at the desktop's DPI (which is normally 96 dpi). [Use `:zoom => 0.78125`](https://github.com/wkhtmltopdf/wkhtmltopdf/issues/2184) (75/96) to match Linux rendering to Windows.
### Inspiration
You may have noticed: this plugin is heavily inspired by the PrinceXML plugin [princely](http://github.com/mbleigh/princely/tree/master). PrinceXML's cost was prohibitive for me. So, with a little help from some friends (thanks [jqr](http://github.com/jqr)), I tracked down wkhtmltopdf, and here we are.