Class: Prawn::Outline

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/prawn/outline.rb

Overview

The Outline class organizes the outline tree items for the document. Note that the prev and parent instance variables are adjusted while navigating through the nested blocks. These variables along with the presence or absense of blocks are the primary means by which the relations for the various OutlineItems and the OutlineRoot are set. Unfortunately, the best way to understand how this works is to follow the method calls through a real example.

Some ideas for the organization of this class were gleaned from name_tree. In particular the way in which the OutlineItems are finally rendered into document objects in PdfObject through a hash.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ Outline

Returns a new instance of Outline.



55
56
57
58
59
60
61
 
# File 'lib/prawn/outline.rb', line 55

def initialize(document)
  @document = document
  @outline_root = document.outline_root(OutlineRoot.new)
  @parent = outline_root
  @prev = nil
  @items = {}
end

Instance Attribute Details

#document ⇒ Object

Returns the value of attribute document.



51
52
53
 
# File 'lib/prawn/outline.rb', line 51

def document
  @document
end

#items ⇒ Object

Returns the value of attribute items.



53
54
55
 
# File 'lib/prawn/outline.rb', line 53

def items
  @items
end

#outline_root ⇒ Object

Returns the value of attribute outline_root.



52
53
54
 
# File 'lib/prawn/outline.rb', line 52

def outline_root
  @outline_root
end

#parent ⇒ Object

Returns the value of attribute parent.



49
50
51
 
# File 'lib/prawn/outline.rb', line 49

def parent
  @parent
end

#prev ⇒ Object

Returns the value of attribute prev.



50
51
52
 
# File 'lib/prawn/outline.rb', line 50

def prev
  @prev
end

Instance Method Details

#add_section(&block) ⇒ Object

Adds an outine section to the outline tree (see define_outline). Although you will probably choose to exclusively use define_outline so that your outline tree is contained and easy to manage, this method gives you the option to add sections to the outline tree at any point during document generation. Note that the section will be added at the top level at the end of the outline. For more a more flexible API try using outline.insert_section_after.

block uses the same DSL syntax as define_outline, for example: 

outline.add_section do
  section 'Added Section', :page => 3 do
    page 3, :title => 'Page 3'
  end
end



121
122
123
124
125
126
127
 
# File 'lib/prawn/outline.rb', line 121

def add_section(&block)
  @parent = outline_root
  @prev = outline_root.data.last
  if block
    block.arity < 1 ? instance_eval(&block) : block[self]
  end      
end

#define(&block) ⇒ Object

Defines an outline for the document. The outline is an optional nested index that appears on the side of a PDF document usually with direct links to pages. The outline DSL is defined by nested blocks involving two methods: section and page.

section(title, options{}, &block)

title: the outline text that appears for the section.
options: page - optional integer defining the page number for a destination link.
              - currently only :FIT destination supported with link to top of page.
         closed - whether the section should show its nested outline elements.
                - defaults to false.

page(page, options{})

page: integer defining the page number for the destination link.
      currently only :FIT destination supported with link to top of page.
      set to nil if destination link is not desired.
options: title - the outline text that appears for the section.
         closed - whether the section should show its nested outline elements.
                - defaults to false.

The syntax is best illustrated with an example:

Prawn::Document.generate(outlined document) do

text "Page 1. This is the first Chapter. "
start_new_page
text "Page 2. More in the first Chapter. "
start_new_page
define_outline do
  section 'Chapter 1', :page => 1, :closed => true do 
    page 1, :title => 'Page 1'
    page 2, :title => 'Page 2'
  end
end

end

It should be noted that not defining a title for a page element will raise a RequiredOption error



100
101
102
103
104
 
# File 'lib/prawn/outline.rb', line 100

def define(&block)
  if block
    block.arity < 1 ? instance_eval(&block) : block[self]
  end
end

#insert_section_after(title, &block) ⇒ Object

Inserts an outline section to the outline tree (see define_outline). Although you will probably choose to exclusively use define_outline so that your outline tree is contained and easy to manage, this method gives you the option to insert sections to the outline tree at any point during document generation. Unlike outline.add_section, this method allows you to enter a section after any other item at any level in the outline tree. Currently the only way to locate the place of entry is with the title for the item. If your titles names are not unique consider using define_outline.

block uses the same DSL syntax as define_outline, for example: 

go_to_page 2
start_new_page
text "Inserted Page"
outline.insert_section_after :title => 'Page 2' do 
  page page_number, :title => "Inserted Page"
end



147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/prawn/outline.rb', line 147

def insert_section_after(title, &block)
  @prev = items[title]
  if @prev
    @parent = @prev.data.parent
    nxt = @prev.data.next
    if block
      block.arity < 1 ? instance_eval(&block) : block[self]
    end
    adjust_relations(nxt)
  else
    raise Prawn::Errors::UnknownOutlineTitle, 
      "\n No outline item with title: '#{title}' exists in the outline tree"
  end
end