prawn-table-continued 1.0.0.rc1

data/manual/contents.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+#
+# Generates the Prawn by example manual.
+
+require_relative "example_helper"
+
+Encoding.default_external = Encoding::UTF_8
+
+Prawn::ManualBuilder::Example.generate("manual.pdf",
+  :skip_page_creation => true, :page_size => "FOLIO") do
+
+  load_package "table"
+end

data/manual/example_helper.rb

@@ -0,0 +1,8 @@
+# encoding: UTF-8
+
+require "prawn"
+require_relative "../lib/prawn/table"
+
+require "prawn/manual_builder"
+
+Prawn::ManualBuilder.manual_dir = File.dirname(__FILE__)

data/manual/table/basic_block.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+#
+# All of the previous styling options we've seen deal with all the table cells
+# at once.
+#
+# With initializer blocks we may deal with specific cells.
+# A block passed to one of the table methods (<code>Prawn::Table.new</code>,
+# <code>Prawn::Document#table</code>, <code>Prawn::Document#make_table</code>)
+# will be called after cell setup but before layout. This is a very flexible way
+# to specify styling and layout constraints.
+#
+# Just like the <code>Prawn::Document.generate</code> method, the table
+# initializer blocks may be used with and without a block argument.
+#
+# The table class has three methods that are handy within an initializer block:
+# <code>cells</code>, <code>rows</code> and <code>columns</code>. All three
+# return an instance of <code>Prawn::Table::Cells</code> which represents
+# a selection of cells.
+#
+# <code>cells</code> return all the table cells, while <code>rows</code> and
+# <code>columns</code> accept a number or a range as argument which returns a
+# single row/column or a range of rows/columns respectively. (<code>rows</code>
+# and <code>columns</code> are also aliased as <code>row</code> and
+# <code>column</code>)
+#
+# The <code>Prawn::Table::Cells</code> class also defines <code>rows</code> and
+# <code>columns</code> so they may be chained to narrow the selection of cells.
+#
+# All of the cell styling options we've seen on previous examples may be set as
+# properties of the selection of cells.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Header",           "A " * 5, "B"],
+           ["Data row",         "C",      "D " * 5],
+           ["Another data row", "E",      "F"]]
+
+  table(data) do
+    cells.padding = 12
+    cells.borders = []
+
+    row(0).borders      = [:bottom]
+    row(0).border_width = 2
+    row(0).font_style   = :bold
+
+    columns(0..1).borders = [:right]
+
+    row(0).columns(0..1).borders = [:bottom, :right]
+  end
+end

data/manual/table/before_rendering_page.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# <code>Prawn::Table#initialize</code> takes a
+# <code>:before_rendering_page</code> argument, to adjust the way an entire page
+# of table cells is styled. This allows you to do things like draw a border
+# around the entire table as displayed on a page.
+#
+# The callback is passed a Cells object that is numbered based on the order of
+# the cells on the page (e.g., the first row on the page is
+# <code>cells.row(0)</code>).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  table([["foo", "bar", "baz"]] * 40) do |t|
+    t.cells.border_width = 1
+    t.before_rendering_page do |page|
+      page.row(0).border_top_width       = 3
+      page.row(-1).border_bottom_width   = 3
+      page.column(0).border_left_width   = 3
+      page.column(-1).border_right_width = 3
+    end
+  end
+end

data/manual/table/cell_border_lines.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# The <code>border_lines</code> option accepts an array with the styles of the
+# border sides. The default is <code>[:solid, :solid, :solid, :solid]</code>.
+#
+# <code>border_lines</code> must be set to an array.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data =  [ ["Look at how the cell border lines can be mixed", "", ""],
+            ["dotted top border", "", ""],
+            ["solid right border", "", ""],
+            ["dotted bottom border", "", ""],
+            ["dashed left border", "", ""]
+          ]
+
+  text "Cell :border_lines => [:dotted, :solid, :dotted, :dashed]"
+
+  table(data, :cell_style =>
+    { :border_lines => [:dotted, :solid, :dotted, :dashed] })
+end

data/manual/table/cell_borders_and_bg.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# The <code>borders</code> option accepts an array with the border sides that
+# will be drawn. The default is <code>[:top, :bottom, :left, :right]</code>.
+#
+# <code>border_width</code> may be set with a numeric value.
+#
+# Both <code>border_color</code> and <code>background_color</code> accept an
+# HTML like RGB color string ("FF0000")
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  { :borders => [:top, :left],
+    :border_width => 3,
+    :border_color => "FF0000"}.each do |property, value|
+
+      text "Cell #{property}: #{value.inspect}"
+      table(data, :cell_style => {property => value})
+      move_down 20
+  end
+
+  text "Cell background_color: FFFFCC"
+  table(data, :cell_style => {:background_color => "FFFFCC"})
+end

data/manual/table/cell_dimensions.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+#
+# To style all the table cells you can use the <code>:cell_style</code> option
+# with the table methods. It accepts a hash with the cell style options.
+#
+# Some straightforward options are <code>width</code>, <code>height</code>,
+# and <code>padding</code>. All three accept numeric values to set the property.
+#
+# <code>padding</code> also accepts a four number array that defines the padding
+# in a CSS like syntax setting the top, right, bottom, left sequentially. The
+# default is 5pt for all sides.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  {:width => 160, :height => 50, :padding => 12}.each do |property, value|
+    text "Cell's #{property}: #{value}"
+    table(data, :cell_style => {property => value})
+    move_down 20
+  end
+
+  text "Padding can also be set with an array by specifying values for all sides: [0, 0, 0, 30]"
+  table(data, :cell_style => {:padding => [0, 0, 0, 30]}) # top, right, bottom, left
+
+  text "Padding can also be set by specifying only vertical and horizontal values: [0,30]"
+  table(data, :cell_style => {:padding => [0, 30]}) # vertical, horizontal
+
+  text "Padding can also be set by specifying top, horizontal and bottom values: [0,30,10]"
+  table(data, :cell_style => {:padding => [0, 30, 10]}) # top, horizontal, bottom
+end

data/manual/table/cell_text.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Text cells accept the following options: <code>align</code>,
+# <code>font</code>, <code>font_style</code>, <code>inline_format</code>,
+# <code>kerning</code>, <code>leading</code>, <code>min_font_size</code>,
+# <code>overflow</code>, <code>rotate</code>, <code>rotate_around</code>,
+# <code>single_line</code>, <code>size</code>, <code>text_color</code>,
+# and <code>valign</code>.
+#
+# Most of these style options are direct translations from the text methods
+# styling options.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  table data, :cell_style => { :font => "Times-Roman", :font_style => :italic }
+  move_down 20
+
+  table data, :cell_style => { :size => 18, :text_color => "346842" }
+  move_down 20
+
+  table [["Just <font size='18'>some</font> <b><i>inline</i></b>", "", ""],
+         ["<color rgb='FF00FF'>styles</color> being applied here", "", ""]],
+         :cell_style => { :inline_format => true }
+  move_down 20
+
+  table [["1", "2", "3", "rotate"]], :cell_style => { :rotate => 30 }
+  move_down 20
+
+  table data, :cell_style => { :overflow => :shrink_to_fit, :min_font_size => 8,
+                               :width => 60, :height => 30 }
+end

data/manual/table/column_widths.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# Prawn will make its best attempt to identify the best width for the columns.
+# If the end result isn't good, we can override it with some styling.
+#
+# Individual column widths can be set with the <code>:column_widths</code>
+# option. Just provide an array with the sequential width values for the columns
+# or a hash were each key-value pair represents the column 0-based index and its
+# width.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["this is not quite as long as the others",
+            "here we have a line that is long but with smaller words",
+            "this is so very looooooooooooooooooooooooooooooong"] ]
+
+  text "Prawn trying to guess the column widths"
+  table(data)
+  move_down 20
+
+  text "Manually setting all the column widths"
+  table(data, :column_widths => [100, 200, 240])
+  move_down 20
+
+  text "Setting only the last column width"
+  table(data, :column_widths => {2 => 240})
+end

data/manual/table/content_and_subtables.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+#
+# There are five kinds of objects which can be put in table cells:
+#   1. String: produces a text cell (the most common usage)
+#   2. <code>Prawn::Table::Cell</code>
+#   3. <code>Prawn::Table</code>
+#   4. Array
+#   5. Images
+#
+# Whenever a table or an array is provided as a cell, a subtable will be created
+# (a table within a cell).
+#
+# If you'd like to provide a cell or table directly, the best way is to
+# use the <code>make_cell</code> and <code>make_table</code> methods as they
+# don't call <code>draw</code> on the created object.
+#
+# To insert an image just provide a hash with an with an <code>:image</code> key
+# pointing to the image path.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  cell_1 = make_cell(:content => "this row content comes directly ")
+  cell_2 = make_cell(:content => "from cell objects")
+
+  two_dimensional_array = [ ["..."], ["subtable from an array"], ["..."] ]
+
+  my_table = make_table([ ["..."], ["subtable from another table"], ["..."] ])
+
+  image_path = File.expand_path("../images/stef.jpg", __dir__)
+
+  table([ ["just a regular row", "", "", "blah blah blah"],
+          [cell_1, cell_2, "", ""],
+          ["", "", two_dimensional_array, ""],
+          ["just another regular row", "", "", ""],
+          [{:image => image_path}, "", my_table, ""]])
+end

data/manual/table/creation.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# Creating tables with Prawn is fairly easy. There are two methods that will
+# create tables for us <code>table</code> and <code>make_table</code>.
+#
+# Both are wrappers that create a new <code>Prawn::Table</code> object. The
+# difference is that <code>table</code> calls the <code>draw</code> method
+# after creating the table and <code>make_table</code> only returns the created
+# table, so you have to call the <code>draw</code> method yourself.
+#
+# The most simple table can be created by providing only an array of arrays
+# containing your data where each inner array represents one row.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  t = make_table([ ["this is the first row"],
+                   ["this is the second row"] ])
+  t.draw
+  move_down 20
+
+  table([ ["short", "short", "loooooooooooooooooooong"],
+          ["short", "loooooooooooooooooooong", "short"],
+          ["loooooooooooooooooooong", "short", "short"] ])
+end

data/manual/table/filtering.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+#
+# Another way to reduce the number of cells is to <code>filter</code> the table.
+#
+# <code>filter</code> is just like <code>Enumerable#select</code>. Pass it a
+# block and it will iterate through the cells returning a new
+# <code>Prawn::Table::Cells</code> instance containing only those cells for
+# which the block was not false.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Item", "Jan Sales", "Feb Sales"],
+           ["Oven", 17, 89],
+           ["Fridge", 62, 30],
+           ["Microwave", 71, 47]
+         ]
+
+  table(data) do
+    values = cells.columns(1..-1).rows(1..-1)
+
+    bad_sales = values.filter do |cell|
+      cell.content.to_i < 40
+    end
+
+    bad_sales.background_color = "FFAAAA"
+
+    good_sales = values.filter do |cell|
+      cell.content.to_i > 70
+    end
+
+    good_sales.background_color = "AAFFAA"
+  end
+end

data/manual/table/flow_and_header.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+#
+# If the table cannot fit on the current page it will flow to the next page just
+# like free flowing text. If you would like to have the first row treated as a
+# header which will be repeated on subsequent pages set the <code>:header</code>
+# option to true.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [["This row should be repeated on every new page"]]
+  data += [["..."]] * 30
+
+  table(data, :header => true)
+end

data/manual/table/image_cells.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+#
+# Prawn can insert images into a table. Just pass a hash into
+# <code>table()</code> with an <code>:image</code> key pointing to the image.
+#
+# You can pass the <code>:scale</code>, <code>:fit</code>,
+# <code>:position</code>, and <code>:vposition</code> arguments in alongside
+# <code>:image</code>; these will function just as in <code>image()</code>.
+#
+# The <code>:image_width</code> and <code>:image_height</code> arguments set
+# the width/height of the image within the cell, as opposed to the
+# <code>:width</code> and <code>:height</code> arguments, which set the table
+# cell's dimensions.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  image = File.expand_path("../images/prawn.png", __dir__)
+
+  table [
+    ["Standard image cell",   {:image => image}],
+    [":scale => 0.5",         {:image => image, :scale => 0.5}],
+    [":fit => [100, 200]",    {:image => image, :fit => [100, 200]}],
+    [":image_height => 50,
+      :image_width => 100",   {:image => image, :image_height => 50,
+                                                :image_width  => 100}],
+    [":position => :center",  {:image => image, :position  => :center}],
+    [":vposition => :center", {:image => image, :vposition => :center,
+                                                :height => 200}]
+  ], :width => bounds.width
+end

data/manual/table/position.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+#
+# The <code>table()</code> method accepts a <code>:position</code> argument to
+# determine horizontal position of the table within its bounding box. It can be
+# <code>:left</code> (the default), <code>:center</code>, <code>:right</code>,
+# or a number specifying a distance in PDF points from the left side.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [["The quick brown fox jumped over the lazy dogs."]] * 2
+
+  text "Left:"
+  table data, :position => :left
+  move_down 10
+
+  text "Center:"
+  table data, :position => :center
+  move_down 10
+
+  text "Right:"
+  table data, :position => :right
+  move_down 10
+
+  text "100pt:"
+  table data, :position => 100
+end

data/manual/table/row_colors.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+#
+# One of the most common table styling techniques is to stripe the rows with
+# alternating colors.
+#
+# There is one helper just for that. Just provide the <code>:row_colors</code>
+# option an array with color values.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [["This row should have one color"],
+          ["And this row should have another"]]
+
+  data += [["..."]] * 10
+
+  table(data, :row_colors => ["F0F0F0", "FFFFCC"])
+end

data/manual/table/span.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# Table cells can span multiple columns, rows, or both. When building a cell,
+# use the hash argument constructor with a <code>:colspan</code> and/or
+# <code>:rowspan</code> argument. Row or column spanning must be specified when
+# building the data array; you can't set the span in the table's initialization
+# block. This is because cells are laid out in the grid before that block is
+# called, so that references to row and column numbers make sense.
+#
+# Cells are laid out in the order given, skipping any positions spanned by
+# previously instantiated cells. Therefore, a cell with <code>rowspan: 2</code>
+# will be missing at least one cell in the row below it. See the code and table
+# below for an example.
+#
+# It is illegal to overlap cells via spanning. A
+# <code>Prawn::Errors::InvalidTableSpan</code> error will be raised if spans
+# would cause cells to overlap.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  table([
+    ["A", {:content => "2x1", :colspan => 2}, "B"],
+    [{:content => "1x2", :rowspan => 2}, "C", "D", "E"],
+    [{:content => "2x2", :colspan => 2, :rowspan => 2}, "F"],
+    ["G", "H"]
+  ])
+end

data/manual/table/style.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+#
+# We've seen how to apply styles to a selection of cells by setting the
+# individual properties. Another option is to use the <code>style</code> method
+#
+# <code>style</code> lets us define multiple properties at once with a hash. It
+# also accepts a block that will be called for each cell and can be used for
+# some complex styling.
+#
+# Individual cell styles can also be applied when defining the data for the
+# table using a hash syntax for the cell.  This style will take precedence over
+# any table level cell styles.  See the "cell_text" section for a list of
+# options.
+
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  table([[""] * 8] * 8) do
+    cells.style(:width => 24, :height => 24)
+
+    cells.style do |c|
+      c.background_color = ((c.row + c.column) % 2).zero? ? '000000' : 'ffffff'
+    end
+  end
+  move_down 20
+
+  table(
+    [%w[A B], ['C', { content: 'D', text_color: 'ff0000' }]],
+    cell_style: { text_color: '0000ff' }
+  )
+end

data/manual/table/table.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+#
+# Examples for tables.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::ManualBuilder::Example.generate("table.pdf", :page_size => "FOLIO") do
+  package "table" do |p|
+    p.name = "Prawn::Table"
+
+    p.section "Basics" do |s|
+      s.example "creation"
+      s.example "content_and_subtables"
+      s.example "flow_and_header"
+      s.example "position"
+    end
+
+    p.section "Styling" do |s|
+      s.example "column_widths"
+      s.example "width"
+      s.example "row_colors"
+      s.example "cell_dimensions"
+      s.example "cell_borders_and_bg"
+      s.example "cell_border_lines"
+      s.example "cell_text"
+      s.example "image_cells"
+      s.example "span"
+      s.example "before_rendering_page"
+    end
+
+    p.section "Initializer Block" do |s|
+      s.example "basic_block"
+      s.example "filtering"
+      s.example "style"
+    end
+
+    p.intro do
+      prose("Prawn-table provides support for tables in Prawn. Tables can be styled in whatever way you see fit. The whole table, rows, columns and cells can be styled independently from each other.
+
+      The examples show:")
+
+      list( "How to create tables",
+            "What content can be placed on tables",
+            "Subtables (or tables within tables)",
+            "How to style the whole table",
+            "How to use initializer blocks to style only specific portions of the table"
+          )
+    end
+
+  end
+end

data/manual/table/width.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# The default table width depends on the content provided. It will expand up
+# to the current bounding box width to fit the content. If you want the table to
+# have a fixed width no matter the content you may use the <code>:width</code>
+# option to manually set the width.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  text "Normal width:"
+  table [%w[A B C]]
+  move_down 20
+
+  text "Fixed width:"
+  table([%w[A B C]], :width => 300)
+  move_down 20
+
+  text "Normal width:"
+  table([["A", "Blah " * 20, "C"]])
+  move_down 20
+
+  text "Fixed width:"
+  table([["A", "Blah " * 20, "C"]], :width => 300)
+end