Class: Prawn::Outline
- Inherits:
-
Object
- Object
- Prawn::Outline
- 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
-
#document ⇒ Object
Returns the value of attribute document.
-
#items ⇒ Object
Returns the value of attribute items.
-
#parent ⇒ Object
Returns the value of attribute parent.
-
#prev ⇒ Object
Returns the value of attribute prev.
Instance Method Summary collapse
-
#add_subsection_to(title, position = :last, &block) ⇒ Object
Inserts an outline section to the outline tree (see outline#define).
-
#define(&block) ⇒ Object
(also: #update)
Defines/Updates an outline for the document.
-
#initialize(document) ⇒ Outline
constructor
A new instance of Outline.
-
#insert_section_after(title, &block) ⇒ Object
Inserts an outline section to the outline tree (see outline#define).
-
#page(options = {}) ⇒ Object
See Outline#define above for more documentation on how it is used in that context.
-
#section(title, options = {}, &block) ⇒ Object
See outline#define above for documentation on how this is used in that context.
Constructor Details
Instance Attribute Details
#document ⇒ Object
Returns the value of attribute document.
39 40 41 |
# File 'lib/prawn/outline.rb', line 39 def document @document end |
#items ⇒ Object
Returns the value of attribute items.
40 41 42 |
# File 'lib/prawn/outline.rb', line 40 def items @items end |
#parent ⇒ Object
Returns the value of attribute parent.
37 38 39 |
# File 'lib/prawn/outline.rb', line 37 def parent @parent end |
#prev ⇒ Object
Returns the value of attribute prev.
38 39 40 |
# File 'lib/prawn/outline.rb', line 38 def prev @prev end |
Instance Method Details
#add_subsection_to(title, position = :last, &block) ⇒ Object
Inserts an outline section to the outline tree (see outline#define). Although you will probably choose to exclusively use outline#define 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. This method allows you to add a child subsection to 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 title names are not unique consider using define_outline. The method takes the following arguments:
title: a string that must match an outline title to add the subsection to
position: either :first or :last(the default) where the subsection will be placed relative
to other child elements. If you need to position your subsection in between
other elements then consider using #insert_section_after
block: uses the same DSL syntax as outline#define, for example:
Consider using this method inside of outline.update if you want to have the outline object to be scoped as self (see #insert_section_after example).
go_to_page 2
start_new_page
text "Inserted Page"
outline.add_subsection_to :title => 'Page 2', :first do
outline.page :destination => page_number, :title => "Inserted Page"
end
108 109 110 111 112 113 114 115 |
# File 'lib/prawn/outline.rb', line 108 def add_subsection_to(title, position = :last, &block) @parent = items[title] raise Prawn::Errors::UnknownOutlineTitle, "\n No outline item with title: '#{title}' exists in the outline tree" unless @parent @prev = position == :first ? nil : @parent.data.last nxt = position == :first ? @parent.data.first : nil insert_section(nxt, &block) end |
#define(&block) ⇒ Object Also known as: update
Defines/Updates 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; see the documentation on those methods for their arguments and options. Note that one can also use outline#update to add more sections to the end of the outline tree using the same syntax and scope.
The syntax is best illustrated with an example:
Prawn::Document.generate(outlined_document.pdf) do
text "Page 1. This is the first Chapter. "
start_new_page
text "Page 2. More in the first Chapter. "
start_new_page
outline.define do
section 'Chapter 1', :destination => 1, :closed => true do
page :destination => 1, :title => 'Page 1'
page :destination => 2, :title => 'Page 2'
end
end
start_new_page do
outline.update do
section 'Chapter 2', :destination => 2, do
page :destination => 3, :title => 'Page 3'
end
end
end
77 78 79 |
# File 'lib/prawn/outline.rb', line 77 def define(&block) instance_eval(&block) if block end |
#insert_section_after(title, &block) ⇒ Object
Inserts an outline section to the outline tree (see outline#define). Although you will probably choose to exclusively use outline#define 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 title names are not unique consider using define_outline. The method takes the following arguments:
title: the title of other section or page to insert new section after
block: uses the same DSL syntax as outline#define, for example:
go_to_page 2
start_new_page
text "Inserted Page"
update_outline do
insert_section_after :title => 'Page 2' do
page :destination => page_number, :title => "Inserted Page"
end
end
138 139 140 141 142 143 144 145 |
# File 'lib/prawn/outline.rb', line 138 def insert_section_after(title, &block) @prev = items[title] raise Prawn::Errors::UnknownOutlineTitle, "\n No outline item with title: '#{title}' exists in the outline tree" unless @prev @parent = @prev.data.parent nxt = @prev.data.next insert_section(nxt, &block) end |
#page(options = {}) ⇒ Object
See Outline#define above for more documentation on how it is used in that context
Adds a page to the outline. Although you will probably choose to exclusively use outline#define so that your outline tree is contained and easy to manage, this method also gives you the option to add pages to the root of outline tree at any point during document generation. Note that the page will be added at the top level after the other root outline elements. For more flexible placement try using outline#insert_section_after and/or outline#add_subsection_to.
Takes the following arguments:
options:
title - REQUIRED. The outline text that appears for the page.
destination - integer defining the page number for the 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.
example usage:
outline.page :title => "Very Last Page"
Note: this method is almost identical to section except that it does not accept a block thereby defining the outline item as a leaf on the outline tree structure.
196 197 198 199 200 201 202 203 204 |
# File 'lib/prawn/outline.rb', line 196 def page( = {}) if [:title] title = [:title] else raise Prawn::Errors::RequiredOption, "\nTitle is a required option for page" end add_outline_item(title, ) end |
#section(title, options = {}, &block) ⇒ Object
See outline#define above for documentation on how this is used in that context
Adds an outine section to the outline tree. Although you will probably choose to exclusively use outline#define 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. When not being called from within another #section block the section will be added at the top level after the other root elements of the outline. For more flexible placement try using outline#insert_section_after and/or
outline#add_subsection_to Takes the following arguments:
title: the outline text that appears for the section.
options: destination - 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.
block: more nested subsections and/or page blocks
example usage:
outline.section 'Added Section', :destination => 3 do
outline.page :destionation => 3, :title => 'Page 3'
end
170 171 172 |
# File 'lib/prawn/outline.rb', line 170 def section(title, = {}, &block) add_outline_item(title, , &block) end |