prawn 1.0.0.rc1 → 1.0.0.rc2

data/manual/repeatable_content/page_numbering.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+#
+# The <code>number_pages</code> method is a simple way to number the pages of
+# your document. It should be called towards the end of the document since
+# pages created after the call won't be numbered.
+#
+# It accepts a string and a hash of options:
+#
+# <code>start_count_at</code> is the value from which to start numbering pages
+#
+# <code>total_pages</code> If provided, will replace <code>total</code> with
+# the value given.  Useful for overriding the total number of pages when using
+# the start_count_at option.
+#
+# <code>page_filter</code>, which is one of: <code>:all</code>,
+# <code>:odd</code>, <code>:even</code>, an array, a range, or a Proc that
+# receives the page number as an argument and should return true if the page
+# number should be printed on that page.
+#
+# <code>color</code> which accepts the same values as <code>fill_color</code>
+#
+# As well as any option accepted by <code>text_box</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
+  text "This is the first page!"
+  
+  10.times do
+    start_new_page
+    text "Here comes yet another page."
+  end
+
+  string = "page <page> of <total>"
+  # Green page numbers 1 to 7
+  options = { :at => [bounds.right - 150, 0],
+              :width => 150,
+              :align => :right,
+              :page_filter => (1..7),
+              :start_count_at => 1,
+              :color => "007700" }
+  number_pages string, options
+
+  # Gray page numbers from 8 on up
+  options[:page_filter]    = lambda{ |pg| pg > 7}
+  options[:start_count_at] = 8
+  options[:color]          = "333333"
+  number_pages string, options
+  
+  start_new_page
+  text "See. This page isn't numbered and doesn't count towards the total."
+end

data/manual/repeatable_content/repeatable_content.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# Examples for stamps and repeaters.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("repeatable_content.pdf", :page_size => "FOLIO") do
+  
+  package "repeatable_content" do |p|
+    
+    p.example "repeater",       :eval_source => false
+    p.example "stamp"
+    p.example "page_numbering", :eval_source => false
+    
+    p.intro do
+      prose("Prawn offers two ways to handle repeatable content blocks. Repeater is useful for content that gets repeated at well defined intervals while Stamp is more appropriate if you need better control of when to repeat it.
+
+      There is also one very specific helper for numbering pages.
+
+      The examples show:")
+
+      list( "How to repeat content on several pages with a single invocation",
+            "How to create a new Stamp",
+            'How to "stamp" the content block on the page',
+            "How to number the document pages with one simple call"
+          )
+    end
+    
+  end
+end

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