Prawn::Grouping

An experimental gem to add a more flexible grouping option to the excellent prawn gem.

Installation

Add this line to your application's Gemfile:

gem 'prawn-grouping'

And then execute:

$ bundle

Or install it yourself as:

$ gem install prawn-grouping

Usage

Grouping

Prawn::Document.new do
  20.times { text "Regular text" }
  group do |g|
    20.times { g.text "Paragraphs not separated unless necessary" }
  end
end

Nested Groups

Prawn::Document.new do
  5.times { text "Regular text" }
  group do |g|
    15.times { g.text "Paragraphs not separated unless necessary" }
    group do |g|
      30.times { g.text "Subparagraphs not separated unless necessary" }
    end
  end
end

Do not overuse nesting because a every combination has to be tested recursively in a temporary document

Options

Currently three callbacks are supported:

:fits_current_context A proc called before the content is rendered and does fit context.
:fits_new_context A proc called before the content is rendered and does fit a single context.
:too_tall A proc called before the content is rendered and does not fit a single context.

Prawn::Document.new do
  5.times { text "Regular text" }

  group :too_tall => lambda { start_new_page } do |g|
    15.times { g.text "Paragraphs not separated unless necessary" }
  end
end

The example above starts a new page if the content is too tall for a single page. Default behavior would be to just append the content.

Troubleshooting

When using JRuby on a version smaller than 0.2.0 a block parameter has to be supplied. For the other tested Interpreters this was optional.

Prawn::Document.new do
  5.times { text "Regular text" }

  group do |g|
    15.times { g.text "Paragraphs not separated unless necessary" }
  end
end

Manipulating objects within the group block

The grouping internally works by executing the block one or multiple times and checking the results, because deep copy did not work well for the original implementation in many cases. As a result you should not manipulate your data objects within the block. See issue #7 for details.

Contributing

Fork it ( http://github.com//prawn-grouping/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request