Object
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.
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
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
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
# 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
# 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
# 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
# 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
# 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
# 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
# File lib/prawn/outline.rb, line 164 164: def section(title, options = {}, &block) 165: add_outline_item(title, options, &block) 166: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.