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.
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.
# 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
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
Generated with the Darkfish Rdoc Generator 2.