prawn 1.0.0.rc1 → 1.0.0.rc2

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::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,30 @@
+# 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::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: [0, 0, 0, 30]"
+  table(data, :cell_style => {:padding => [0, 0, 0, 30]})
+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::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::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::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 = "#{Prawn::DATADIR}/images/stef.jpg"
+  
+  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::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::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::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::Example.generate(filename) do
+  image = "#{Prawn::DATADIR}/images/prawn.png"
+
+  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::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::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::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,22 @@
+# 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.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::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
+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::Example.generate("table.pdf", :page_size => "FOLIO") do
+  
+  package "table" do |p|
+    
+    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 comes with table support out of the box. 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