HTML to PDF API for Ruby

This is the documentation of the Ruby client library for the Pdfcrowd HTML to PDF API. Here are some sample PDFs generated by the API:

Status report JavaScript vector chart Wikipedia page Invoice Newsletter

Installation

Integration with your application is a matter of a few minutes:

  1. Sign up and obtain your username and API key.
  2. You can either install the gem from rubygems.org:
      
     $ gem install pdfcrowd
    Or download pdfcrowd-2.4.0.gem and run
      
     $ gem install pdfcrowd-2.4.0.gem

You can also check out the source on Github: pdfcrowd-ruby

Getting Started

In the following examples, do not forget to replace "username" and "apikey" with your username and API key.

HTML to PDF Example Application

The following code shows how to convert a web page, raw HTML code, and a local HTML file: 

require 'rubygems'
require 'pdfcrowd'

begin
    # create an API client instance
    client = Pdfcrowd::Client.new("username", "apikey")

    # convert a web page and store the generated PDF into a pdf variable
    pdf = client.convertURI('http://www.google.com')

    # convert an HTML string and save the result to a file
    html="<head></head><body>My HTML Layout</body>"
    File.open('html.pdf', 'wb') {|f| client.convertHtml(html, f)}

    # convert an HTML file
    File.open('file.pdf', 'wb') {|f| client.convertFile('/path/to/MyLayout.html', f)}

    # retrieve the number of tokens in your account
    ntokens = client.numTokens()

rescue Pdfcrowd::Error => why
    print 'FAILED: ', why
end

HTML to PDF in Ruby on Rails

The following code shows how to convert a web page in a Ruby on Rails controller method: 

require 'rubygems'
require 'pdfcrowd'

def generatePdf
  begin
    # create an API client instance
    client = Pdfcrowd::Client.new("username", "apikey")

    # convert a web page and store the generated PDF to a variable
    pdf = client.convertURI("http://www.google.com")

    # send the generated PDF
    send_data(pdf, 
              :filename => "google_com.pdf",
              :type => "application/pdf",
              :disposition => "attachment")
  rescue Pdfcrowd::Error => why
    render :text => why
  end
end

You can also convert raw HTML code, just use the convertHtml() method instead of convertURI(): 

    pdf = client.convertHtml("<head></head><body>My HTML Layout</body>")

The API lets you also convert a local HTML file: 

    pdf = client.convertFile("/path/to/MyLayout.html")

Error Handling

begin
    # ..
    # call the API
rescue Pdfcrowd::Error => why
    # handle the error
end

API Reference

class Pdfcrowd::Client (view source)

Provides access to the Pdfcrowd API from your Ruby applications.

Constructor

def initialize(username, apikey)
Arguments are your username at Pdfcrowd and apikey which can be found in your account.

Conversion

 
def convertHtml(html, outstream=nil)
Converts the html string to PDF and writes the result to outstream. outstream can be any object having a write(str) method. If outstream is not provided then the return value is a string containing the created PDF. 
def convertFile(fpath, outstream=nil)
Converts a local file fpath to PDF and writes the result to outstream. The file can be either an HTML document or a .zip, .tar.gz., or .tar.bz2 archive which can contain external resources such as images, stylesheets, etc.
outstream can be any object having a write(str) method. If outstream is not provided then the return value is a string containing the created PDF. 
def convertURI(url, outstream=nil)
Converts a web page at url to PDF and writes the result to outstream. outstream can be any object having a write(str) method. If outstream is not provided then the return value is a string containing the created PDF.

Page Setup

 
def setPageWidth(value)
Sets PDF page width in units. 
def setPageHeight(value)
Sets PDF page height in units. Use -1 for a single page PDF. 
def setPageMargins(top, right, bottom, left)
Sets PDF page margins in units. 
def setHorizontalMargin(value)
Deprecated. Use setPageMargins instead. 
def setVerticalMargin(value)
Deprecated. Use setPageMargins instead.

Header and Footer

 
def setFooterHtml(html)
Places the specified html code inside the page footer. The following variables are expanded:
  • %u - URL to convert.
  • %p - The current page number.
  • %n - Total number of pages.
def setFooterUrl(url)
Loads HTML code from the specified url and places it inside the page footer. See setFooterHtml for the list of variables that are expanded. 
def setHeaderHtml(html)
Places the specified html code inside the page header. See setFooterHtml for the list of variables that are expanded. 
def setHeaderUrl(url)
Loads HTML code from the specified url and places it inside the page header. See setFooterHtml for the list of variables that are expanded. 
def setHeaderFooterPageExcludeList(exclist)
exclist is a comma seperated list of physical page numbers on which the header a footer are not printed. Negative numbers count backwards from the last page: -1 is the last page, -2 is the last but one page, and so on.
Example: "1,-1" will not print the header and footer on the first and the last page. 
def setPageNumberingOffset(offset)
An offset between physical and logical page numbers. The default value is 0.
Example: if set to "1" then the page numbering will start with 1 on the second page.

HTML options

 
def enableImages(value)
Set value to false to disable printing images to the PDF. The default is true 
def enableBackgrounds(value)
Set value to false to disable printing backgrounds to the PDF. The default is true 
def setHtmlZoom(value)
Set HTML zoom in percents. It determines the precision used for rendering of the HTML content. Despite its name, it does not zoom the HTML content. Higher values can improve glyph positioning and can lead to overall better visual appearance of generated PDF .The default value is 200. See also setPdfScalingFactor(). 
def enableJavaScript(value)
Set value to false to disable JavaScript in web pages. The default is true. 
def enableHyperlinks(value)
Set value to false to disable hyperlinks in the PDF. The default is true. 
def setDefaultTextEncoding(value)
value is the text encoding used when none is specified in a web page. The default is utf-8. 
def usePrintMedia(value)
If value is true then the print CSS media type is used (if available).

PDF options

 
def setEncrypted(value)
If value is set to true then the PDF is encrypted. This prevents search engines from indexing the document. The default is false. 
def setUserPassword(pwd)
Protects the PDF with a user password. When a PDF has a user password, it must be supplied in order to view the document and to perform operations allowed by the access permissions. At most 32 characters. 
def setOwnerPassword(pwd)
Protects the PDF with an owner password. Supplying an owner password grants unlimited access to the PDF including changing the passwords and access permissions. At most 32 characters. 
def setNoPrint(value)
Set value to true disables printing the generated PDF. The default is false. 
def setNoModify(value)
Set value to true to disable modifying the PDF. The default is false. 
def setNoCopy(value)
Set value to true to disable extracting text and graphics from the PDF. The default is false. 
def setPageLayout(value)
Specifies the initial page layout when the PDF is opened in a viewer.
  • SINGLE_PAGE
  • CONTINUOUS
  • CONTINUOUS_FACING
def setPageMode(value)
Specifies the appearance of the PDF when opened.
  • FULLSCREEN - Full-screen mode.
def setInitialPdfZoomType(value)
value specifies the appearance of the PDF when opened.
  • FIT_WIDTH
  • FIT_HEIGHT
  • FIT_PAGE
def setInitialPdfExactZoom(value)
value specifies the initial page zoom of the PDF when opened. 
def setPdfScalingFactor(value)
The scaling factor used to convert between HTML and PDF. The default value is 1.0. 
def setPageBackgroundColor(value)
The page background color in RRGGBB hexadecimal format. 
def setTransparentBackground(value)
Does not print the body background. Requires the following CSS rule to be declared:
body {background-color:rgba(255,255,255,0.0);} 
def setAuthor(author)
Sets the author field in the created PDF.

Watermark

 
def setWatermark(url, offset_x=0, offset_y=0)
url is a public absolute URL of the watermark image (must start either with http:// or https://). The supported formats are PNG and JPEG. offset_x and offset_y is the watermark offset in units. The default offset is (0,0). 
def setWatermarkRotation(angle)
Rotates the watermark by angle degrees. 
def setWatermarkInBackground(value)
When value is set to true then the watermark is be placed in the background. By default, the watermark is placed in the foreground.

Miscellaneous

 
def useSSL(use_ssl)
Set to true to call the API over a secure connection. The default is false. 
def numTokens()
Returns the number of available conversion tokens in your account. 
def setMaxPages(npages)
Prints at most npages pages. 
def setFailOnNon200(value)
If value is true then the conversion will fail when the source URI returns 4xx or 5xx HTTP status code. The default is false.

class Pdfcrowd::Error

Derived from RuntimeError. It is thrown when an error occurs. Use to_s() method to get the error message.

Units

Page dimensions and margins can be specified in inches (in), millimeters (mm), centimeters (cm), or points (pt). If no units are specified, points are assumed. Examples: "210mm", "8.5in".