Parent

Prawn::Outline

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.

Attributes

parent[RW]
prev[RW]
document[RW]
outline_root[RW]
items[RW]

Public Class Methods

new(document) click to toggle source
    # File lib/prawn/outline.rb, line 55
55:     def initialize(document)
56:       @document = document
57:       @outline_root = document.outline_root(OutlineRoot.new)
58:       @parent = outline_root
59:       @prev = nil
60:       @items = {}
61:     end

Public Instance Methods

add_section(&block) click to toggle source

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
     # File lib/prawn/outline.rb, line 121
121:     def add_section(&block)
122:       @parent = outline_root
123:       @prev = outline_root.data.last
124:       if block
125:         block.arity < 1 ? instance_eval(&block) : block[self]
126:       end      
127:     end
define(&block) click to toggle source

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

     # File lib/prawn/outline.rb, line 100
100:     def define(&block)
101:       if block
102:         block.arity < 1 ? instance_eval(&block) : block[self]
103:       end
104:     end
insert_section_after(title, &block) click to toggle source

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
     # File lib/prawn/outline.rb, line 147
147:     def insert_section_after(title, &block)
148:       @prev = items[title]
149:       if @prev
150:         @parent = @prev.data.parent
151:         nxt = @prev.data.next
152:         if block
153:           block.arity < 1 ? instance_eval(&block) : block[self]
154:         end
155:         adjust_relations(nxt)
156:       else
157:         raise Prawn::Errors::UnknownOutlineTitle, 
158:           "\n No outline item with title: '#{title}' exists in the outline tree"
159:       end
160:     end

Private Instance Methods

add_outline_item(title, options, &block) click to toggle source
     # File lib/prawn/outline.rb, line 179
179:     def add_outline_item(title, options, &block)
180:       outline_item = create_outline_item(title, options)
181:       set_relations(outline_item)
182:       increase_count
183:       set_variables_for_block(outline_item, block)
184:       block.call if block
185:       reset_parent(outline_item)
186:     end
adjust_relations(nxt) click to toggle source
     # File lib/prawn/outline.rb, line 230
230:     def adjust_relations(nxt)
231:       if nxt 
232:         nxt.data.prev = @prev
233:         @prev.data.next = nxt
234:         @parent.data.last = nxt
235:       else 
236:         @parent.data.last = @prev
237:       end
238:     end
create_outline_item(title, options) click to toggle source
     # File lib/prawn/outline.rb, line 188
188:     def create_outline_item(title, options)
189:       outline_item = OutlineItem.new(title, parent, options)
190: 
191:       if options[:page]
192:         page_index = options[:page] - 1
193:         outline_item.dest = [document.pages[page_index].dictionary, :Fit] 
194:       end
195: 
196:       outline_item.prev = prev if @prev
197:       items[title] = document.ref!(outline_item)
198:     end
increase_count() click to toggle source
     # File lib/prawn/outline.rb, line 206
206:     def increase_count
207:       counting_parent = parent
208:       while counting_parent
209:         counting_parent.data.count += 1
210:         if counting_parent == outline_root
211:           counting_parent = nil
212:         else
213:           counting_parent = counting_parent.data.parent
214:         end
215:       end
216:     end
page(page = nil, options = {}) click to toggle source
     # File lib/prawn/outline.rb, line 168
168:     def page(page = nil, options = {})
169:       if options[:title]
170:         title = options[:title] 
171:         options[:page] = page
172:       else
173:         raise Prawn::Errors::RequiredOption, 
174:           "\nTitle is a required option for page"
175:       end
176:       add_outline_item(title, options)
177:     end
reset_parent(outline_item) click to toggle source
     # File lib/prawn/outline.rb, line 223
223:     def reset_parent(outline_item)
224:       if parent == outline_item
225:         self.prev = outline_item
226:         self.parent = outline_item.data.parent
227:       end
228:     end
section(title, options = {}, &block) click to toggle source
     # File lib/prawn/outline.rb, line 164
164:     def section(title, options = {}, &block)
165:       add_outline_item(title, options, &block)
166:     end
set_relations(outline_item) click to toggle source
     # File lib/prawn/outline.rb, line 200
200:     def set_relations(outline_item)
201:       prev.data.next = outline_item if prev
202:       parent.data.first = outline_item unless prev
203:       parent.data.last = outline_item
204:     end
set_variables_for_block(outline_item, block) click to toggle source
     # File lib/prawn/outline.rb, line 218
218:     def set_variables_for_block(outline_item, block)
219:       self.prev = block ? nil : outline_item
220:       self.parent = outline_item if block
221:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.