Prawn::Table

You can generate a local copy of the Prawn::Table manual by following these steps:

1. Clone the repository.
2. Run bundle to install dependencies.
3. Run rake manual to generate the documentation.

Additionally, all example files located in the manual folder can be run individually to see the library in action.

When working with tables, colspan and rowspan must be provided as part of the table's data structure. You cannot set them inside an initialization block (e.g., within a pdf.table(...) { ... } block) because the layout engine has already run by that point.

Correct way (in data):

pdf.table([["foo", {:content => "bar", :colspan => 2}]])

Incorrect way (in block):

# This will raise Prawn::Errors::InvalidTableSpan
pdf.table([["foo", "bar"]]) { |t| t.cells[0, 1].colspan = 2 }

You can nest a table inside a cell of another table by providing a Prawn::Table instance as the :content option to a cell. This is handled internally by the Subtable class. When nesting, you can specify :padding for the subtable cell via the options hash.

# Conceptual usage of nesting a table within a cell
inner_table = Prawn::Table.new(pdf, ...)

outer_table = Prawn::Table.new(pdf, {
  rows: [
    ["Cell 1", "Cell 2"],
    ["Nested Table Cell", inner_table] # Passing the table as content
  ]
})

The Prawn::Table::Cell.make method automatically determines the appropriate subclass of Cell based on the type of content provided:

• String: Creates a Cell::Text.
• Prawn::Table: Creates a Cell::Subtable.
• Array: Creates a Cell::Subtable by wrapping the array in a new Prawn::Table.
• Hash with :image key: Creates a Cell::Image.
• Cell instance: Uses the provided Prawn::Table::Cell object directly.

If the content type is unrecognized, it raises Errors::UnrecognizedTableContent.

Use the table method on a Prawn::Document instance to set up and immediately draw a table. The data argument must be a two-dimensional array of 'cellable' objects.

Cellable objects include:

• String: Creates a text cell.
• Prawn::Table::Cell: Existing cell objects or custom subclasses.
• Prawn::Table:: (via make_table): A subtable (a table within a cell).
• Array: A simple subtable (use make_table if you need specific styling).

You can pass an optional block to configure the table after cell setup but before layout and drawing.

# Basic table usage
pdf.table([['Header 1', 'Header 2'], ['Row 1 Col 1', 'Row 1 Col 2']])

# Table with a configuration block
pdf.table(data) do |table|
  table.rows(1..3).width = 72
end

When calling table or make_table, you can pass an options hash to control the table's appearance and behavior. Key options include:

• cell_style: A hash of style options applied to all cells (e.g., :borders, :background_color).
• header: If true, the first row is repeated on every page. If an Integer, the first x rows are repeated on every page.
• column_widths: Sets widths for columns. Can be an Array [w0, w1, ...], a Hash {0 => w0, 1 => w1, ...}, or a Numeric to set all columns to the same width.
• position: Horizontal alignment within the bounding box. Options are :left (default), :center, :right, or a Numeric representing points from the left edge.
• row_colors: An Array of alternating colors used to stripe the rows.

The following errors may be raised during table operations:

• Prawn::Errors::InvalidTableData: Raised when the provided data is not a two-dimensional array.
• Prawn::Errors::EmptyTable: Raised when an empty or nil table is provided for rendering.
• Prawn::Errors::UnrecognizedTableContent: Raised when unrecognized content is provided for a table cell.
• Prawn::Errors::InvalidTableSpan: Raised when cell spans (rowspan/colspan) overlap.
• Prawn::Errors::CannotFit: Raised when the requested table width is too small to contain its contents or too large compared to its maximum width.

Inside a table initialization block, you can use the style method or direct attribute access to apply styles to specific subsets of the table (rows, columns, or individual cells).

pdf.table(data) do
  # Style a specific row
  style(row(0), :background_color => 'ff00ff')

  # Style a specific column with a block
  column(0).style { |c| c.border_width += 1 }
end

When using a Subtable (a table nested within a cell), you can set the text color for all cells within that subtable by calling text_color= on the subtable cell. This operation is proxied to the underlying subtable's cells.

# Assuming 'cell' is a Subtable instance
cell.text_color = "#FF0000"

Use make_table to initialize a Prawn::Table object without drawing it immediately. This is useful for creating subtables that will be inserted into cells of another table. You must explicitly call .draw on the resulting object to render it.

subtable = pdf.make_table(subtable_data, options)
# ... later ...
subtable.draw