Caterpillar

This Ruby gem is a simple wrapper around the Caterpillar API. Caterpillar is a web service that allows you to convert html to pdf.

Add this line to your application's Gemfile:

gem 'caterpillar-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install caterpillar-ruby

Set the following attributes in you Ruby app:

Caterpillar.api_key = 'YOUR_CATERPILLAR_API_KEY' # required
Caterpillar.api_version = 'YOUR_API_VERSION' # optional, default: 'v1'
Caterpillar.base_uri = 'YOUR_API_BASE_URI' # optional, default: 'https://api.caterpillar.io'

For a Rails app you can execute:

$ rails generate caterpillar:install

or create an initializer config/initializers/caterpillar.rb:

Caterpillar.configure do |config|
  config.api_key = 'YOUR_CATERPILLAR_API_KEY'
end

Once set, you can create a PDF document by calling:

Caterpillar.create(source: content, grayscale: true, no_images: true)

You can also create test PDF documents by calling (header and footer options donot work in test mode):

Caterpillar.create(source: content, test: true)

The create call can also take a block, like so:

Caterpillar.create(source: content) do |file, response|
  # file is a tempfile holding the response body
  # response is the HTTParty response object
end

create will return an HTTParty response object, which will be the new file (or errors, if the request was not valid).

The only required parameter is:

• :source - a string containing the HTML or URL for creating the document

For a Rails app you can pass a view as source by converting it to an HTML string using render_to_string.

You might want to set other options in that hash:

You can password protect PDF using AES 256, AES 128, RC4 (128 & 40) encryption algorithms supported by Adobe Reader.

To encrypt PDF you need to pass :password_protect hash in the create method call along with the following required parameters:

• :password - a string containing the secret password which will be further used to unlock the PDF
• :key_length - a number which defines the encryption algorithm to be used. Values can be 40, 128 and 256 only.

You might want to set other options for each encryption algorithm inside :restrictions hash:

Key Length: 40

Key Length: 128

Key Length: 256

Example:

Caterpillar.create(
    source: content,
    password_protect: {
        password: 'YOUR_PASSWORD_HERE',
        key_length: 128,
        restrictions: {
            print: 'low',
            use_aes: 'y'
        }
    }
)

Maintained by KeepWorks

Bug reports and pull requests are welcome on GitHub at https://github.com/keepworks/caterpillar.

The gem is available as open source under the terms of the MIT License.