## examples/general/repeating_elements.rb
# encoding: utf-8
#
# This demonstrates repeating elements.
#
$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
require "prawn"

Prawn::Document.generate("repeating_elements.pdf") do
  repeating_elements(:all) do
    text "A page"
  end

  repeating_elements(2..4) do
    text "Page 2, 3 or 4"
  end

  repeating_elements(:even) do
    text "An even page"
  end

  repeating_elements(:odd) do
    text "An odd page"
  end

  repeating_elements([2, 4]) do
    text "Page 2 or 4"
  end

  5.times { start_new_page }
end

## Patch [diff]
diff --git a/lib/prawn/document.rb b/lib/prawn/document.rb
index 5ef95b1..2f19777 100644
--- a/lib/prawn/document.rb
+++ b/lib/prawn/document.rb
@@ -158,6 +158,13 @@ module Prawn
       @pages.data[:Count]
     end

+    # Repeats an element across multiple pages. 'spec' can be :all, :even,
+    # :odd, a range or an array.
+    def repeating_elements(spec = :all, &block)
+      @repeating_elements ||= {}
+      @repeating_elements[spec] = block
+    end
+
     # The current y drawing position relative to the innermost bounding box,
     # or to the page margins at the top level.
     #
diff --git a/lib/prawn/document/internals.rb b/lib/prawn/document/internals.rb
index 086078a..b150d02 100644
--- a/lib/prawn/document/internals.rb
+++ b/lib/prawn/document/internals.rb
@@ -71,13 +71,27 @@ module Prawn

       private

-      def finish_page_content
-        @header.draw if @header
-        @footer.draw if @footer
+      def finish_page_content
+        render_repeating_elements if @repeating_elements
         add_content "Q"
         @page_content.compress_stream if compression_enabled?
         @page_content.data[:Length] = @page_content.stream.size
       end
+
+      def render_repeating_elements
+        @repeating_elements.each do |spec, proc|
+          case spec
+          when :all
+            proc.call(self)
+          when :even
+            proc.call(self) if page_count % 2 == 0
+          when :odd
+            proc.call(self) if page_count % 2 != 0
+          when Range, Array
+            proc.call(self) if spec.include?(page_count)
+          end
+        end
+      end

       # Write out the PDF Header, as per spec 3.4.1
       def render_header(output)
diff --git a/spec/document_spec.rb b/spec/document_spec.rb
index 11b91d7..bcb2cb8 100644
--- a/spec/document_spec.rb
+++ b/spec/document_spec.rb
@@ -45,6 +45,68 @@ describe "When creating multi-page documents" do

 end

+describe "The repeating_elements() feature" do
+  before(:each) { @pdf = Prawn::Document.new }
+
+  it "should render the element on all pages with :all" do
+    @pdf.repeating_elements(:all) {|p| p.text "This is rendered on all pages" }
+    4.times { @pdf.start_new_page }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 5
+    strings.uniq.size.should == 1
+  end
+
+  it "should render the element on even pages with :even" do
+    @pdf.repeating_elements(:even) {|p| p.text "This is rendered on even pages" }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 0
+
+    3.times { @pdf.start_new_page }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 2
+  end
+
+  it "should render the element on odd pages with :odd" do
+    @pdf.repeating_elements(:odd) {|p| p.text "This is rendered on odd pages" }
+
+    @pdf.start_new_page
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 1
+
+    2.times { @pdf.start_new_page }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 2
+  end
+
+  it "should render the element on pages within the range with a Range" do
+    @pdf.repeating_elements(2..4) {|p| p.text "This is rendered on page 2 through 4" }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 0
+
+    10.times { @pdf.start_new_page }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 3
+  end
+
+  it "should render the element on pages in the array whith an Array" do
+    @pdf.repeating_elements([2, 4]) {|p| p.text "This is rendered on page 2 and 4" }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 0
+
+    10.times { @pdf.start_new_page }
+
+    strings = PDF::Inspector::Text.analyze(@pdf.render).strings
+    strings.size.should == 2
+  end
+end
+
 describe "When beginning each new page" do

   describe "Background template feature" do