class Prawn::Table

This class implements simple PDF table generation.

Prawn tables have the following features:

* Can be generated with or without headers
* Can tweak horizontal and vertical padding of text
* Minimal styling support (borders / row background colors)
* Can be positioned by bounding boxes (left/center aligned) or an
  absolute x position
* Automated page-breaking as needed
* Column widths can be calculated automatically or defined explictly on a 
  column by column basis
* Text alignment can be set for the whole table or by column

The current implementation is a bit barebones, but covers most of the basic needs for PDF table generation. If you have feature requests, please share them at: groups.google.com/group/prawn-ruby

Tables will be revisited before the end of the Ruby Mendicant project and the most commonly needed functionality will likely be added.

Public Class Methods

new(data, document, options={}) click to toggle source

Creates a new Document::Table object. This is generally called indirectly through Prawn::Document#table but can also be used explictly.

The data argument is a two dimensional array of strings, organized by row, e.g. [[“r1-col1”,“r1-col2”],]. As with all Prawn text drawing operations, strings must be UTF-8 encoded.

The following options are available for customizing your tables, with defaults shown in [] at the end of each description.

:headers

An array of table headers, either strings or Cells. [Empty]

:align_headers

Alignment of header text. Specify for entire header (:left) or by column ({ 0 => :right, 1 => :left}). If omitted, the header alignment is the same as the column alignment.

:header_text_color

Sets the text color of the headers

:header_color

Manually sets the header color

:font_size

The font size for the text cells . [12]

:horizontal_padding

The horizontal cell padding in PDF points [5]

:vertical_padding

The vertical cell padding in PDF points [5]

:padding

Horizontal and vertical cell padding (overrides both)

:border_width

With of border lines in PDF points [1]

:border_style

If set to :grid, fills in all borders. If set to :underline_header, underline header only. Otherwise, borders are drawn on columns only, not rows

:border_color

Sets the color of the borders.

:position

One of :left, :center or n, where n is an x-offset from the left edge of the current bounding box

:width

A set width for the table, defaults to the sum of all column widths

:column_widths

A hash of indices and widths in PDF points. E.g. { 0 => 50, 1 => 100 }

:row_colors

Used to specify background colors for rows. See below for usage.

:align

Alignment of text in columns, for entire table (:center) or by column ({ 0 => :left, 1 => :center})

Row colors (:row_colors) are specified as HTML hex color values, e.g., “ccaaff”. They can take several forms:

  • An array of colors, used cyclically to “zebra stripe” the table: ['ffffff', 'cccccc', '336699'].

  • A hash taking 0-based row numbers to colors: { 0 => 'ffffff', 2 => 'cccccc'}.

  • The symbol :pdf_writer, for PDF::Writer's default color scheme.

See Prawn::Document#table for typical usage, as directly using this class is not recommended unless you know why you want to do it.

# File lib/prawn/table.rb, line 121
def initialize(data, document, options={})     
  unless data.all? { |e| Array === e }
    raise Prawn::Errors::InvalidTableData,
      "data must be a two dimensional array of Prawn::Cells or strings"
  end
  
  @data     = data        
  @document = document
  
  Prawn.verify_options [:font_size,:border_style, :border_width,
   :position, :headers, :row_colors, :align, :align_headers, 
   :header_text_color, :border_color, :horizontal_padding, 
   :vertical_padding, :padding, :column_widths, :width, :header_color ], 
   options     
                                      
  configuration.update(options)  

  if padding = options[:padding]
    C(:horizontal_padding => padding, :vertical_padding => padding) 
  end
   
  if options[:row_colors] == :pdf_writer 
    C(:row_colors => ["ffffff","cccccc"])  
  end
  
  if options[:row_colors]
    C(:original_row_colors => C(:row_colors)) 
  end

  calculate_column_widths(options[:column_widths], options[:width])
end

Public Instance Methods

draw() click to toggle source

Draws the table onto the PDF document

# File lib/prawn/table.rb, line 163
def draw  
  @parent_bounds = @document.bounds  
  case C(:position) 
  when :center
    x = (@document.bounds.width - width) / 2.0
    dy = @document.bounds.absolute_top - @document.y
    final_pos = nil

    @document.bounding_box [x, @parent_bounds.top], :width => width do 
      @document.move_down(dy)
      generate_table
      final_pos = @document.y
    end

    @document.y = final_pos
  when Numeric     
    x, y = C(:position), @document.cursor
    final_pos = nil

    @document.bounding_box([x,y], :width => width) do
      generate_table
      final_pos = @document.y 
    end

    @document.y = final_pos
  else
    generate_table
  end
end
width() click to toggle source

Width of the table in PDF points

# File lib/prawn/table.rb, line 157
def width
   @column_widths.inject(0) { |s,r| s + r }
end