Class: Prawn::Table

Inherits:
Object
  • Object
show all
Includes:
Configurable
Defined in:
lib/prawn/table.rb,
lib/prawn/table/cell.rb

Overview

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.

Defined Under Namespace

Classes: Cell, CellBlock

Constant Summary collapse

NUMBER_PATTERN =

:nodoc:

/^-?(?:0|[1-9]\d*)(?:\.\d+(?:[eE][+-]?\d+)?)?$/

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, document, options = {}) ⇒ Table

Creates a new Document::Table object. This is generally called indirectly through 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 Document#table for typical usage, as directly using this class is not recommended unless you know why you want to do it.



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/prawn/table.rb', line 122

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

Instance Attribute Details

#column_widths ⇒ Object (readonly)

:nodoc:



81
82
83
 
# File 'lib/prawn/table.rb', line 81

def column_widths
  @column_widths
end

Instance Method Details

#draw ⇒ Object

Draws the table onto the PDF document



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/prawn/table.rb', line 164

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 ⇒ Object

Width of the table in PDF points



158
159
160
 
# File 'lib/prawn/table.rb', line 158

def width
   @column_widths.inject(0) { |s,r| s + r }
end