README.md in wicked_pdf-2.1.0 vs README.md in wicked_pdf-2.6.0
- old
+ new
@@ -1,6 +1,6 @@
-# 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)
+# Wicked PDF [](http://badge.fury.io/rb/wicked_pdf) [](https://github.com/mileszs/wicked_pdf/actions/workflows/ci.yml) [](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.
@@ -41,11 +41,12 @@
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'
+ exe_path: '/usr/local/bin/wkhtmltopdf',
+ enable_local_file_access: true
}
```
For more information about `wkhtmltopdf`, see the project's [homepage](http://wkhtmltopdf.org/).
@@ -109,30 +110,29 @@
#### Webpacker usage
wicked_pdf supports webpack assets.
-Use `wicked_pdf_stylesheet_pack_tag` for stylesheets
-Use `wicked_pdf_javascript_pack_tag` for javascripts
+- Use `wicked_pdf_stylesheet_pack_tag` for stylesheets
+- Use `wicked_pdf_javascript_pack_tag` for javascripts
+- Use `wicked_pdf_asset_pack_path` to access an asset directly, for example: `image_tag wicked_pdf_asset_pack_path("media/images/foobar.png")`
-Use `wicked_pdf_asset_pack_path` to access an asset directly, for example: `image_tag wicked_pdf_asset_pack_path("media/images/foobar.png")`
-
#### 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" %>
+<!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" %>
```
### Advanced Usage with all available options
_NOTE: Certain options are only supported in specific versions of wkhtmltopdf._
@@ -183,15 +183,16 @@
grayscale: true,
lowquality: true,
enable_plugins: true,
disable_internal_links: true,
disable_external_links: true,
+ keep_relative_links: true,
print_media_type: true,
# define as true the key 'disable_local_file_access' or 'enable_local_file_access', not both
disable_local_file_access: true,
- enable_local_file_access: false,
+ enable_local_file_access: false, # must be true when using wkhtmltopdf > 0.12.6
disable_smart_shrinking: true,
use_xserver: true,
background: false, # background needs to be true to enable background colors to render
no_background: true,
@@ -428,29 +429,59 @@
JESii's post [WickedPDF, wkhtmltopdf, and Heroku...a tricky combination](http://www.nubyrubyrailstales.com/2013/06/wickedpdf-wkhtmltopdf-and-herokua.html)
Berislav Babic's post [Send PDF attachments from Rails with WickedPdf and ActionMailer](http://berislavbabic.com/send-pdf-attachments-from-rails-with-wickedpdf-and-actionmailer/)
+Corsego's 2021 post [Complete guide to generating PDFs with gem wicked_pdf](https://blog.corsego.com/gem-wicked-pdf)
+
+PDFTron's post [How to Generate PDFs With Ruby on Rails](https://www.pdftron.com/blog/rails/how-to-generate-pdf-with-ruby-on-rails/)
+
StackOverflow [questions with the tag "wicked-pdf"](http://stackoverflow.com/questions/tagged/wicked-pdf)
+### Screencasts
+
+* SupeRails Screencast [EN]
+
+[](https://youtu.be/tFvtwEmW-GE)
+
+* codigofacilito Screencast [ES]
+
+[](https://youtu.be/jeWM_gusmJc)
+
### Debugging
Now you can use a debug param on the URL that shows you the content of the pdf in plain html to design it faster.
First of all you must configure the render parameter `show_as_html: params.key?('debug')` and then just use it like you normally would but add "debug" as a GET param in the URL:
http://localhost:3001/CONTROLLER/X.pdf?debug
However, the wicked_pdf_* helpers will use file:/// paths for assets when using :show_as_html, and your browser's cross-domain safety feature will kick in, and not render them. To get around this, you can load your assets like so in your templates:
```html
- <%= params.key?('debug') ? image_tag('foo') : wicked_pdf_image_tag('foo') %>
+<%= 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 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.
+
+### Security considerations
+
+WickedPdf renders page content on the server by saving HTML and assets to temporary files on disk, then executing `wkhtmltopdf` to convert that HTML to a PDF file.
+
+It is highly recommended if you allow user-generated HTML/CSS/JS to be converted to PDF, you sanitize it first, or at least disallow requesting content from internal IP addresses and hostnames.
+
+For example, these could potentially leak internal AWS metadata:
+```html
+<iframe src="http://169.254.169.254/latest/meta-data/"></iframe>
+<object data="http://169.254.169.254/latest/meta-data/" type="text/html">
+```
+
+Thank you to Adam Gold from [Snyk](https://snyk.io) for reporting this.
+We are considering adding host allow & block lists and/or potentially HTML element sanitizing.
+Please open an issue or PR to help us out with this.
### 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.