prawn 0.11.1 → 0.15.0

data/manual/repeatable_content/repeater.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+#
+# The <code>repeat</code> method is quite versatile when it comes to define
+# the intervals at which the content block should repeat.
+#
+# The interval may be a symbol (<code>:all</code>, <code>:odd</code>,
+# <code>:even</code>), an array listing the pages, a range or a
+# <code>Proc</code> that receives the page number as an argument and should
+# return true if the content is to be repeated on the given page.
+#
+# You may also pass an option <code>:dynamic</code> to reevaluate the code block
+# on every call which is useful when the content changes based on the page
+# number.
+#
+# It is also important to say that no matter where you define the repeater it
+# will be applied to all matching pages.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  repeat(:all) do
+    draw_text "All pages", :at => bounds.top_left
+  end
+
+  repeat(:odd) do
+    draw_text "Only odd pages", :at => [0,0]
+  end
+
+  repeat(:even) do
+    draw_text "Only even pages", :at => [0,0]
+  end
+
+  repeat([1,3,7]) do 
+    draw_text "Only on pages 1, 3 and 7", :at => [100,0]
+  end
+
+  repeat(2..4) do
+    draw_text "From the 2nd to the 4th page", :at => [300,0]
+  end
+
+  repeat(lambda { |pg| pg % 3 == 0 }) do
+    draw_text "Every third page", :at => [250, 20]
+  end
+  
+  repeat(:all, :dynamic => true) do
+    draw_text page_number, :at => [500, 0]
+  end
+
+  10.times do 
+    start_new_page
+    draw_text "A wonderful page", :at => [400,400]
+  end
+end

data/manual/repeatable_content/stamp.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# Stamps should be used when you have content that will be included multiple
+# times in a document. Its advantages over creating the content anew each time
+# are:
+#   1.  Faster document creation
+#   2.  Smaller final document
+#   3.  Faster display on subsequent displays of the repeated
+# element because the viewer application can cache the rendered
+# results
+#
+# The <code>create_stamp</code> method does just what it says. Pass it a block
+# with the content that should be generated and the stamp will be created.
+#
+# There are two methods to render the stamp on a page <code>stamp</code> and
+# <code>stamp_at</code>. The first will render the stamp as is while the
+# second accepts a point to serve as an offset to the stamp content.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  create_stamp("approved") do
+    rotate(30, :origin => [-5, -5]) do
+      stroke_color "FF3333"
+      stroke_ellipse [0, 0], 29, 15
+      stroke_color "000000"
+    
+      fill_color "993333"
+      font("Times-Roman") do
+        draw_text "Approved", :at => [-23, -3]
+      end
+      fill_color "000000"
+    end
+  end
+  
+  stamp "approved"
+  
+  stamp_at "approved", [200, 200]
+end

data/manual/security/encryption.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# The <code>encrypt_document</code> method, as you might have already guessed,
+# is used to encrypt the PDF document.
+#
+# Once encrypted whoever is using the document will need the user password to
+# read the document. This password can be set with the
+# <code>:user_password</code> option. If this is not set the document will be
+# encrypted but a password will not be needed to read the document.
+#
+# There are some caveats when encrypting your PDFs. Be sure to read the source
+# documentation (you can find it here:
+# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
+# using this for anything super serious.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+
+# Bare encryption. No password needed.
+Prawn::Example.generate("bare_encryption.pdf") do
+  text "See, no password was asked but the document is still encrypted."
+  encrypt_document
+end
+
+
+# Simple password. All permissions granted.
+Prawn::Example.generate("simple_password.pdf") do
+  text "You was asked for a password."
+  encrypt_document(:user_password => 'foo', :owner_password => 'bar')
+end

data/manual/security/permissions.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Some permissions may be set for the regular user with the following options:
+# <code>:print_document</code>, <code>:modify_contents</code>,
+# <code>:copy_contents</code>, <code>:modify_annotations</code>. All this
+# options default to true, so if you'd like to revoke just set them to false.
+#
+# A user may bypass all permissions if he provides the owner password which
+# may be set with the <code>:owner_password</code> option. This option may be
+# set to <code>:random</code> so that users will never be able to bypass
+# permissions.
+#
+# There are some caveats when encrypting your PDFs. Be sure to read the source
+# documentation (you can find it here:
+# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
+# using this for anything super serious.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+
+# User cannot print the document.
+Prawn::Example.generate("cannot_print.pdf") do
+  text "If you used the user password you won't be able to print the doc."
+  encrypt_document(:user_password => 'foo', :owner_password => 'bar',
+                   :permissions => { :print_document => false })
+end
+
+
+# All permissions revoked and owner password set to random
+Prawn::Example.generate("no_permissions.pdf") do
+  text "You may only view this and won't be able to use the owner password."
+  encrypt_document(:user_password => 'foo', :owner_password => :random,
+                   :permissions => { :print_document     => false,
+                                     :modify_contents    => false,
+                                     :copy_contents      => false,
+                                     :modify_annotations => false })
+end

data/manual/security/security.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# Examples for document encryption.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("security.pdf", :page_size => "FOLIO") do
+  
+  package "security" do |p|
+    
+    p.example "encryption",  :eval_source => false, :full_source => true
+    p.example "permissions", :eval_source => false, :full_source => true
+    
+    p.intro do
+      prose("Security lets you control who can read the document by defining a password.
+
+      The examples include:")
+
+      list( "How to encrypt the document without the need for a password",
+            "How to configure the regular user permitions",
+            "How to require a password for the regular user",
+            "How to set a owner password that bypass the document permissions"
+          )
+    end
+    
+  end
+end

data/manual/syntax_highlight.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require "coderay"
+
+# Registers a to_prawn method on CodeRay. It returns an array of hashes to be
+# used with formatted_text.
+#
+# Usage:
+#
+# CodeRay.scan(string, :ruby).to_prawn
+#
+class PrawnEncoder < CodeRay::Encoders::Encoder
+  register_for :to_prawn
+
+  COLORS = { :default           => "FFFFFF",
+             
+             :comment           => "AEAEAE",
+             :constant          => "88A5D2",
+             :instance_variable => "E8ED97",
+             :integer           => "C8FF0E",
+             :float             => "C8FF0E",
+             :inline_delimiter  => "EF804F",  # #{} within a string
+             :keyword           => "FEE100",
+             
+             # BUG: There appear to be some problem with this token. Method
+             #      definitions are considered as ident tokens
+             #
+             :method            => "FF5C00",
+             :string            => "56D65E",
+             :symbol            => "C8FF0E" 
+           }
+
+  def setup(options)
+    super
+    @out  = []
+    @open = []
+  end
+
+  def text_token(text, kind)
+    color = COLORS[kind] || COLORS[@open.last] || COLORS[:default]
+    
+    @out << {:text => text, :color => color}
+  end
+
+  def begin_group(kind)
+    @open << kind
+  end
+
+  def end_group(kind)
+    @open.pop
+  end
+end

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::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::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::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::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