h1. WkhtmltopdfOnRails

wkhtmltopdf_on_rails is a plugin that gives you a new controller method: render_to_pdf (See the example usage below)

The plugin utilizes the wkhtmltopdf command line linux tool: http://code.google.com/p/wkhtmltopdf/ The tool uses the WebKit to convert HTML and CSS to pdf, so there is full support. Essentially, the pdf that is created is the same as choosing "save as pdf" or "print to pdf" in your browser.

There is only one depency, Wkhtmltopdf.

To install (on linux):

wget http://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-0.8.3-static.tar.bz2
tar -jxvf wkhtmltopdf-0.8.3-static.tar.bz2
sudo ln -s /full_path_to/wkhtmltopdf /usr/local/bin/wkhtmltopdf

(I installed my copy to /opt/wkhtmltopdf)

after you install wkhtmltopdf, install the wkhtmltopdf_on_rails plugin:

script/plugin install git://github.com/tcocca/wkhtmltopdf_on_rails.git

h2. Example

Current there are 2 options for saving the PDFs and sending them back in rails:

The first is to provide a URL for the page that you want converted to a pdf, this is good when the page is a public facing page that anybody can see:

h4. Usage:

respond_to do |format|
  format.html {
    Normal html stuff ....
  }
  format.pdf do
    render_to_pdf({
      :pdf       => "test_wkhtmltopdf", 
      :file_path => File.join(RAILS_ROOT, 'pdfs'), 
      :source    => root_url
    })
  end
end

The render_to_pdf method takes the following options in the hash:

  :pdf => name of your pdf (without the .pdf extension - added automatically)
  :file_path => where your generated pdf will be created by the command line tool
  :source => url for the page you want to convert to a pdf

The second usage is to generate a html file locally and pass that file to the tool.

This should be used when the page that needs to be converted to pdf is behind a login, as the wkhtmltopdf will not be logged in and will be redirected most likely to another page.

h4. Usage:

  
respond_to do |format|
  format.html {
    Normal html stuff ....
  }
  format.pdf do
    render_to_pdf({
      :pdf                   => "test_wkhtmltopdf", 
      :file_path             => File.join(RAILS_ROOT, 'pdfs'), 
      :template              => "/controller/action.html.erb",
      :layout                => "application.html.erb",
      :delete_generated_pdf  => true
    })
  end
end

The render_to_pdf method takes the following options in the hash:

  :pdf => name of your pdf (without the .pdf extension - added automatically)
  :file_path => where your generated pdf will be created by the command line tool
  :template => the path the to controller and action template you wish to convert to pdf

h6. Optional params:

  :layout => If you wish for rails to render your template in a layout specify the layout in this param
  :delete_generated_pdf => set this to true if you want to plugin to delete the generated pdf after it has been sent back to the user
    *NOTE: this is slow because rails needs to read in the entire file before sending instead of sending as it reads, 
        but this is the only way the delete the file in the same call as the send_file
  :wkhtmltopdf_options => takes a hash of optional params for wkhtmltopdf

For these optional params, any optional flag for the wkhtmltopdf command line call is supported To see a list of these run the command:


wkhtmltopdf --help

  For the list the name of the command is the key in the optional hash as a string, eg: "key-name", without the -- in front
  The value is either true or a string.  If the option requires text to follow use the text you want as the value:

  Eg: --header-center   would be:  "header-center" => "This is my header text"

  Note: You do not need to add the quotes to the value, the library will automatically quote the value (text) for the option when it passes it to the command line.

  If the command does not require text, eg: --print-media-type then use the following:  "print-media-type" => true

h5. See some more examples:

render_to_pdf({
  :pdf                   => "test_wkhtmltopdf", 
  :file_path             => File.join(RAILS_ROOT, 'pdfs'), 
  :template              => "/controller/action.html.erb",
  :layout                => "application.html.erb",
  :delete_generated_pdf  => true,
  :wkhtmltopdf_options   => {
    "print-media-type" => true
  }
}) 

render_to_pdf({
  :pdf       => "test_wkhtmltopdf", 
  :file_path  => File.join(RAILS_ROOT, 'pdfs'), 
  :source    => root_url,
  :wkhtmltopdf_options => {
    "footer-line" => true,
    "footer-center" => "[page] / [toPage]"
  }
})

h2. TODO

• Automatically create the directory for the pdf's if the specified :file_path folder does not exist

h6. Copyright (c) 2009 Tom Cocca ( tom dot cocca at gmail dot com ), released under the MIT license