Class: Prawn::Outline

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

Overview

The Outline class organizes the outline tree items for the document. Note that the #prev and #parent are adjusted while navigating through the nested blocks. These attributes along with the presence or absence of blocks are the primary means by which the relations for the various PDF::Core::OutlineItems and the PDF::Core::OutlineRoot are set.

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

Stable API collapse

Constructor Details

#initialize(document) ⇒ Outline

Returns a new instance of Outline.

Parameters:

Source Code
lib/prawn/outline.rb, line 31
31
def initialize(document)

32
  @document = document

33
  @parent = root

34
  @prev = nil

35
  @items = {}

36
end

Instance Method Details

#add_subsection_to(title, position = :last) { ... } ⇒ void

This method returns an undefined value.

Inserts an outline section to the outline tree (see #define).

Although you will probably choose to exclusively use #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.

Consider using this method instead of #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

Parameters:

  • title (String) —

    An outline title to add the subsection to.

  • position (:first, :last) (defaults to: :last) —

    (:last) 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.

Yields:

  • Uses the same DSL syntax as #define

Source Code
lib/prawn/outline.rb, line 115
115
def add_subsection_to(title, position = :last, &block)

116
  @parent = items[title]

117
  unless @parent

118
    raise Prawn::Errors::UnknownOutlineTitle,

119
      "\n No outline item with title: '#{title}' exists in the outline tree"

120
  end

121
  @prev = position == :first ? nil : @parent.data.last

122
  nxt = position == :first ? @parent.data.first : nil

123
  insert_section(nxt, &block)

124
end

#define { ... } ⇒ void Also known as: update

This method returns an undefined value.

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. Note that one can also use #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

Yields:

Source Code
lib/prawn/outline.rb, line 80
80
def define(&block)

81
  instance_eval(&block) if block

82
end

#insert_section_after(title) { ... } ⇒ void

This method returns an undefined value.

Inserts an outline section to the outline tree (see #define).

Although you will probably choose to exclusively use #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 #add_subsection_to, 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.

Examples:

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

Parameters:

  • title (String) —

    The title of other section or page to insert new section after.

Yields:

  • Uses the same DSL syntax as #define.

Source Code
lib/prawn/outline.rb, line 151
151
def insert_section_after(title, &block)

152
  @prev = items[title]

153
  unless @prev

154
    raise Prawn::Errors::UnknownOutlineTitle,

155
      "\n No outline item with title: '#{title}' exists in the outline tree"

156
  end

157
  @parent = @prev.data.parent

158
  nxt = @prev.data.next

159
  insert_section(nxt, &block)

160
end

#page(options = {}) ⇒ void

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.

This method returns an undefined value.

Adds a page to the outline.

Although you will probably choose to exclusively use #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 #insert_section_after and/or #add_subsection_to.

Examples:

outline.page title: "Very Last Page"

Parameters:

  • options (Hash{Symbol => any}) (defaults to: {})

Options Hash (options):

  • :title (String) —

    REQUIRED. The outline text that appears for the page.

  • :destination (Integer, Array) —
    • The page number for a destination link to the top of the page (using a :FIT destination).
    • An array with a custom destination (see the #dest_* methods of the PDF::Core::Destination module).
  • :closed (Boolean) — default: false —

    Whether the section should show its nested outline elements.

Source Code
lib/prawn/outline.rb, line 219
219
def page(options = {})

220
  if options[:title]

221
    title = options[:title]

222
  else

223
    raise Prawn::Errors::RequiredOption,

224
      "\nTitle is a required option for page"

225
  end

226
  add_outline_item(title, options)

227
end

#page_number ⇒ Integer

Returns the current page number of the document.

Returns:

  • (Integer)
Source Code
lib/prawn/outline.rb, line 43
43
def page_number

44
  @document.page_number

45
end

#section(title, options = {}) { ... } ⇒ void

This method returns an undefined value.

Adds an outline section to the outline tree.

Although you will probably choose to exclusively use #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 #insert_section_after and/or #add_subsection_to.

Examples:

outline.section 'Added Section', destination: 3 do
  outline.page destionation: 3, title: 'Page 3'
end

Parameters:

  • title (String) —

    The outline text that appears for the section.

  • options (Hash{Symbol => any}) (defaults to: {})

Options Hash (options):

  • :destination (Integer, Array) —
    • Optional page number for a destination link to the top of the page (using a :FIT destination).
    • An array with a custom destination (see the #dest_* methods of the PDF::Core::Destination module).
  • :closed (Boolean) — default: false —

    Whether the section should show its nested outline elements.

Yields:

  • More nested subsections and/or page blocks.

Source Code
lib/prawn/outline.rb, line 188
188
def section(title, options = {}, &block)

189
  add_outline_item(title, options, &block)

190
end