The Artima Developer Community
Ruby Code & Style | Discuss | Print | Email | First Page | Previous | Next
Sponsored Link

Ruby Code & Style
Creating Printable Documents with Ruby
by Austin Ziegler
October 10, 2005

Page 1 of 4  >>

Advertisement

Summary
In this article, Austin Ziegler introduces the creation of a variety of types of documents with PDF::Writer for Ruby. This introduction covers basic creation, partial document generation and customization, and Rails-generated documents.

Two years ago, Ruby had no cross-platform libraries to create PDF documents. There were three C library bindings written to work with existing libraries, but these worked best in Unix environments, not Windows environments. Noritsugu Nakimura had written bindings[0] to ClibPDF[1] and Panda PDF[2] in 2001; the interfaces never left “alpha” status. TAKAHASHI Hitoshi released bindings[3] to PDFlib[4] in 2002, but PDFlib is commercially licensed software, which makes it inappropriate for a wide variety of projects.

Around the same time, I had need of a PDF document generator to tie in with some Ruby code I was working for a consulting job. I looked around and found the free PHP library “cPDF” by R & OS[5] of New Zealand. With some effort, I ported an initial pass to Ruby and released it as a technology preview in September 2003 (ruby-talk:82246)[6]. My needs passed, but I continued to plan an upgrade to PDF::Writer, but was distracted with other projects for some time. Earlier this year, I started reworking the API to PDF::Writer and by June, I had something that I was happy with and released it as version 1.0. As of this writing, the current version is PDF::Writer 1.1.3[7].

One of the things that sets PDF::Writer apart from most other projects is the amount of documentation provided. As of the latest version, the manual—which is itself generated with PDF::Writer—is ninety-five pages and covers not only the various aspects of PDF::Writer, but its prerequisite libraries (Transaction::Simple[8] and color-tools[9]). This article is intended to provide an even briefer introduction to the most interesting aspects of PDF::Writer, introduce a couple of techniques that are as of yet not (fully) documented, and provide a brief insight into the future of this vibrant project. This article does not provide an introduction to Ruby itself.

Getting Started

The first step in using PDF::Writer is to install it. The preferred way to do this is with RubyGems, as this will drag in the prerequisite libraries. If, instead, you choose to install PDF::Writer from the .tar.gz archives, you will also need to install the latest versions of Transaction::Simple and color-tools.

There are two well-known problems with installing and using PDF::Writer. The first is for users of PDF::Writer on Mac OS X 10.4 (“Tiger”). If you are using this version of PDF::Writer, the Ruby initially included was compiled with the wrong endianness and is unable to read images properly. This can be fixed by building Ruby yourself or finding someone who has compiled it properly and installing that version.

The second is for users of the PDF::Writer RubyGem. Before you can use PDF::Writer, you must load the RubyGems library. The easiest way to do this is by setting the RUBYOPT environment variable to include rubygems. The most reliable way to do this is to require 'rubygems' at the head of your scripts. When running the demo programs (available as a separate download for RubyGems users), remember to run them with ruby -rubygems demo-name.

The simplest possible program to write with PDF::Writer is, of course, a “hello, world”-type of program.

      require "pdf/writer"

      pdf = PDF::Writer.new
      pdf.select_font "Times-Roman"
      pdf.text "Hello, Ruby.", :font_size => 72, :justification => :center
      pdf.save_as("hello.pdf")
    
Hello, Ruby PDF example
Figure 1. Hello, Ruby

After requiring PDF::Writer, a document is created with the default options and the “Times-Roman” default font is selected. The text “Hello, Ruby.” is added to the document at 72 points in the centre of the line. This document is then saved as “hello.pdf”. It doesn’t get much simpler. The text method handles any text wrapping or pagination that needs to be done because the text will not fit on the displayed page.

Taking hello.rb to the Web

While it’s certainly useful to be able to write PDF documents directly to disk, more useful for many developers is the ability to send a generated PDF across the network. The changes to make this work aren’t large:

      #!/usr/bin/ruby
      require "pdf/writer"
      require "cgi"

      cgi = CGI.new
      pdf = PDF::Writer.new
      pdf.select_font "Times-Roman"
      pdf.text "Hello, Ruby.", :font_size => 72, :justification => :center

      str = pdf.render

      puts <<-EOS
      Content-Type: application/pdf
      Size: #{str.size}

      EOS

      puts str
    

In Ruby on Rails[10] it’s not much different. If you want a new action on your controller (say, “/pdf”), you add a “pdf” method to your controller and fill it in like so:

      require "pdf/writer"

      class HelloController < ApplicationController
        # ...
        def pdf
          _pdf = PDF::Writer.new
          _pdf.select_font "Times-Roman"
          _pdf.text "Hello, Ruby.", :font_size => 72, :justification => :center

          send_data _pdf.render, :filename => "hello.pdf",
                    :type => "application/pdf"
        end
        # ...
      end
    

Page 1 of 4  >>

Ruby Code & Style | Discuss | Print | Email | First Page | Previous | Next

Sponsored Links



Google
  Web Artima.com   
Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us