thousand_island 0.0.1

data/lib/thousand_island/template.rb

@@ -0,0 +1,280 @@
+module ThousandIsland
+  # The Template class is where you can define elements that may be common to
+  # all (or some) documents within your application. It is likely that a common
+  # style will be required, so defining it in a Template and then using that
+  # Template subclass in any custom Builders DRYs up your pdf generation, as
+  # well as allowing for easy restyling across the whole application.
+  #
+  # Typically, the Template subclass would define the settings for the PrawnDocument,
+  # as well as the settings for the header and footer. See the Docs below for the
+  # <code>settings</code> method for the defaults. Add your own or override any
+  # existing settings in the <code>settings</code> method. Any options passed into
+  # the constructor as a Hash will be merged with these settings, and the defaults.
+  #
+  # Content for the header and footer will be defined in the methods
+  # <code>header_content</code> and <code>footer_content</code>. These methods are
+  # passed as a block when the pdf is rendered. Any standard Prawn methods may be
+  # used (including bounding boxes or any other layout tools). In addition, any
+  # of the styles from the <code>StyleSheet</code> can be applied as helper methods.
+  # For instance, the default style sheet has a <code>h1_style</code> method that
+  # returns a  ThousandIsland::StyleHash, so in your code you can use:
+  #   h1 "My Document Header"
+  # and Prawn will render the text in the style set in the <code>h1_style</code>
+  # ThousandIsland::StyleHash.
+  #
+  # In addition to the supplied style methods, you can create a custom method:
+  #   def magic_style
+  #     ThousandIsland::StyleHash.new({
+  #       size: 15
+  #       style: bold
+  #     })
+  #   end
+  # As long as the method ends in the word "_style" and returns a Hash, you magically
+  # get to do this:
+  #   magic "My magic text is bold and size 15!!"
+  # The method may return a standard Hash, but it is safer to return a
+  # ThousandIsland::StyleHash, as this dynamically duplicates a few keys to accommodate
+  # using the style in normal Prawn text methods as well as formatted text boxes, which
+  # use a slightly different convention. You don't have to worry about that if you use
+  # the ThousandIsland::StyleHash.
+  #
+  # Alternatively, your method could do this:
+  #   def magic_style
+  #     h1_style.merge({
+  #       size: 15
+  #       style: bold
+  #     })
+  #   end
+  #
+  # The following is an example of a custom template that subclasses
+  # ThousandIsland::Template -
+  #
+  #   class MyTemplate < ThousandIsland::Template
+  #     include MyCustomStyleSheet # optional
+  #
+  #     # settings here are merged with and override the defaults
+  #     def settings
+  #       {
+  #         header: {
+  #           height: 55,
+  #           render:true,
+  #           repeated: true
+  #         },
+  #         footer: {
+  #           render:true,
+  #           height: 9,
+  #           numbering_string: 'Page <page> of <total>',
+  #           repeated: true
+  #         }
+  #       }
+  #     end
+  #
+  #     def header_content
+  #       pdf.image "#{pdf_images_path}/company_logo.png", height: 30  # Standard Prawn syntax
+  #     end
+  #
+  #     def footer_content
+  #       footer "www.mycompanyurl.com"  # Using the magic method we get from the footer_style
+  #     end
+  #
+  #     def pdf_images_path
+  #       "#{Rails.root}/app/assets/pdf_images"  # This is entirely up to you
+  #     end
+  #   end
+  #
+  # Nb.
+  # The Footer is a three column layout, with the numbering on the right column
+  # and the content defined here in the middle. More flexibility will be added
+  # in a later version.
+  #
+  # Optional:
+  #
+  # Add a <code>body_content</code> method to add content before whatever the
+  # Builder defines in it's method of the same name.
+  #
+  class Template
+    include ThousandIsland::StyleSheet
+
+    attr_reader :pdf, :pdf_options
+
+    def initialize(options={})
+      setup_document_options(options)
+      setup_prawn_document
+      calculate_bounds
+    end
+
+    # Override in inheriting class to override defaults. The default settings
+    # are:
+    #   page_size: 'A4',
+    #   page_layout: :portrait,
+    #   left_margin: 54,
+    #   right_margin: 54,
+    #   header: {
+    #     render: true,
+    #     height: 33,
+    #     bottom_padding: 20,
+    #     repeated: true
+    #   },
+    #   footer: {
+    #     render: true,
+    #     height: 33,
+    #     top_padding: 20,
+    #     repeated: true,
+    #     number_pages: true,
+    #     numbering_string: '<page>',
+    #     numbering_options: {
+    #       align: :right,
+    #       start_count_at: 1,
+    #     }
+    # The settings in the hash will be merged with the default settings. Any Prawn
+    # setting <i>should</i> be valid at the top level of the hash.
+    # The styles used in the Header and Footer are determined by the default styles in the
+    # StyleSheet, but can be overridden in your Template class or by building your own StyleSheet
+    def settings
+      {}
+    end
+
+    def draw_body(&block)
+      body_obj.draw do
+        body_content if respond_to? :body_content
+        yield if block_given?
+      end
+    end
+
+    def draw_header
+      header_obj.draw do
+        header_content if respond_to? :header_content
+        yield if block_given?
+      end if render_header?
+    end
+
+    def draw_footer(&block)
+      footer_obj.draw do
+        yield if block_given?
+        footer_content &block if respond_to? :footer_content
+      end if render_footer?
+    end
+
+  private
+
+    def render_header?
+      pdf_options[:header][:render]
+    end
+
+    def render_footer?
+      pdf_options[:footer][:render]
+    end
+
+
+
+    def calculate_bounds
+      pdf_options[:body][:top] = body_start
+      pdf_options[:body][:height] = body_height
+    end
+
+    def body_start
+      @body_start ||= pdf.bounds.height - header_space
+    end
+
+    def body_height
+      @body_height ||= body_start - footer_space
+    end
+
+    def header_space
+      return (pdf_options[:header][:height] + pdf_options[:header][:bottom_padding]) if pdf_options[:header][:render]
+      0
+    end
+
+    def footer_space
+      return (pdf_options[:footer][:height] + pdf_options[:footer][:top_padding]) if pdf_options[:footer][:render]
+      0
+    end
+
+
+    def setup_prawn_document
+      @pdf = Prawn::Document.new(pdf_options)
+    end
+
+    def setup_document_options(options={})
+      @pdf_options = deep_merger.merge_options(options, settings, defaults, component_defaults)
+    end
+
+
+    def component_defaults
+      components = {
+          footer: footer_klass.defaults,
+          header: header_klass.defaults,
+          body: body_klass.defaults,
+      }
+      components[:footer][:style] = footer_style
+      components
+    end
+
+    def header_klass
+      Components::Header
+    end
+
+    def header_obj
+      @header ||= header_klass.new(pdf, pdf_options[:header])
+    end
+
+    def footer_klass
+      Components::Footer
+    end
+
+    def footer_obj
+      @footer ||= footer_klass.new(pdf, pdf_options[:footer])
+    end
+
+    def body_klass
+      Components::Body
+    end
+
+    def body_obj
+      @body ||= body_klass.new(pdf, pdf_options[:body])
+    end
+
+
+
+    def deep_merger
+      @deep_merger ||= Utilities::DeepMerge
+    end
+
+    # Called by method missing when a style is supplied with text, ie: h1 'Header'
+    def render_with_style(style, output)
+      style_values = send("#{style}_style")
+      pdf.text output, style_values
+    end
+
+    def defaults
+      {
+        page_size: 'A4',
+        page_layout: :portrait,
+        left_margin: 54,
+        right_margin: 54,
+        header: {
+          render: true,
+        },
+        footer: {
+          render: true,
+        },
+        body: {},
+      }
+    end
+
+    #Respond to methods that relate to the style_sheet known styles
+    def method_missing(method_name, *arguments, &block)
+      style_method = "#{method_name}_style"
+      if respond_to?(style_method)
+        render_with_style(method_name, arguments[0])
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, *)
+      available_styles.include?(method_name) || super
+    end
+
+  end
+end

data/lib/thousand_island/utilities/style_hash.rb

@@ -0,0 +1,20 @@
+module ThousandIsland
+  # A subclass of Hash, automatically adds keys that mirror other keys to allow
+  # for a couple of small differences in the Prawn options hashes:
+  #     :font_style = :style
+  #     :styles = :style and puts it into an Array
+  class StyleHash < Hash
+    def initialize(style={})
+      super()
+      self.merge!(style)
+    end
+
+    def [](key)
+      return self[:size] if key == :font_size
+      return [self[:style]] if key == :styles
+      super
+    end
+
+  end
+
+end

data/lib/thousand_island/utilities/utilities.rb

@@ -0,0 +1,58 @@
+module ThousandIsland
+  module Utilities
+
+    module DeepMerge
+
+      #Take a number of hashes and merge them into one, respecting
+      # the structure and nesting according to the pdf options hash.
+      # Hashes work in order of precedence, the first in the array
+      # overrides, the second, etc.
+      #
+      # @param hashes [*Hash] A number of hashes to merge, in the order of precedence
+      #
+      # @return [Hash] the merged values
+      def self.merge_options(*hashes)
+        hashes.reverse!
+        merged = {}
+        footer = merge_footer(*hashes)
+        header = merge_header(*hashes)
+        body = merge_body(*hashes)
+        hashes.each do |h|
+          merged.merge!(h)
+        end
+        merged[:footer] = footer
+        merged[:header] = header
+        merged[:body] = body
+        merged
+      end
+
+      def self.merge_footer(*hashes)
+        keys = [:numbering_options, :style]
+        merge_for_key_and_nested_keys(:footer, keys, *hashes)
+      end
+
+      def self.merge_header(*hashes)
+        merge_for_key_and_nested_keys(:header, [], *hashes)
+      end
+
+      def self.merge_body(*hashes)
+        merge_for_key_and_nested_keys(:body, [], *hashes)
+      end
+
+      def self.merge_for_key_and_nested_keys(key, keys, *hashes)
+        temp = {}
+        merged = {}
+        hashes.each do |h|
+          keys.each do |k|
+            temp[k] = {} unless temp.has_key? k
+            temp[k].merge!(h[key][k]) if h[key] && h[key][k]
+          end
+          merged.merge!(h[key]) if h[key]
+        end
+        merged.merge(temp)
+      end
+
+    end
+
+  end
+end

data/lib/thousand_island/version.rb

@@ -0,0 +1,3 @@
+module ThousandIsland
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require "codeclimate-test-reporter"
+CodeClimate::TestReporter.start
+
+require 'thousand_island'
+
+RSpec.configure do |config|
+  if config.files_to_run.one?
+    config.default_formatter = 'doc'
+  end
+  config.order = :random
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_doubled_constant_names = true
+  end
+end

data/spec/thousand_island/builder_spec.rb

@@ -0,0 +1,106 @@
+module ThousandIsland
+  describe Builder do
+
+    context 'template' do
+
+      it 'raises with no template' do
+        klass = described_class.dup
+        builder = klass.new
+        expect{ builder.build }.to raise_error(TemplateRequiredError)
+      end
+
+      it 'method instantiates a new instance of the template_class' do
+        klass = described_class.dup
+        template = double(:template)
+        allow(template).to receive(:available_styles) {[]}
+        expect(template).to receive(:new).with({}) { template }
+        expect(template).to receive(:pdf) {}
+        klass.uses_template(template)
+        klass.new.send(:template)
+      end
+    end
+
+    context 'with instance' do
+
+      describe 'content method is called when it' do
+        let(:template) { ThousandIsland::Template.new }
+        let(:klass) { described_class.dup }
+        let(:builder) { klass.new }
+
+        before :each do
+          allow(builder).to receive(:template) { template }
+          # klass.send(:define_method, :header_content, ->{})
+          # klass.send(:define_method, :body_content, ->{})
+          # klass.send(:define_method, :footer_content, ->{})
+        end
+        context 'exists' do
+
+          it 'header_content' do
+            # allow(builder).to receive(:header_content)
+            expect(builder).to receive(:header_content)
+            builder.send(:draw_header)
+          end
+          it 'body_content' do
+            expect(builder).to receive(:body_content)
+            builder.send(:draw_body)
+          end
+          it 'footer_content' do
+            expect(builder).to receive(:footer_content)
+            builder.send(:draw_footer)
+          end
+        end
+        context 'does not exist' do
+          it 'header_content' do
+            expect(builder).to_not respond_to(:header_content)
+          end
+          it 'body_content' do
+            expect(builder).to_not respond_to(:body_content)
+          end
+          it 'footer_content' do
+            expect(builder).to_not respond_to(:footer_content)
+          end
+        end
+      end
+
+      context 'calls template method' do
+        let(:template) { ThousandIsland::Template.new }
+        let(:pdf) { instance_double('Prawn::Document') }
+        let(:klass) { described_class.dup }
+        let(:builder) { klass.new }
+
+        before :each do
+          allow(template).to receive(:draw_body) { template }
+          allow(template).to receive(:draw_header) { template }
+          allow(template).to receive(:draw_footer) { template }
+          allow(template).to receive(:available_styles) { [:h1] }
+          allow(pdf).to receive(:render)
+          allow(builder).to receive(:template) { template }
+          allow(builder).to receive(:pdf) { pdf }
+        end
+
+        it '#draw_body' do
+          expect(template).to receive(:draw_body)
+          builder.build
+        end
+
+        it '#header' do
+          expect(template).to receive(:draw_header)
+          builder.build
+        end
+
+        it '#draw_footer' do
+          expect(template).to receive(:draw_footer)
+          builder.build
+        end
+
+        describe 'style methods' do
+          it 'h1' do
+            allow(template).to receive(:h1)
+            expect(template).to receive(:available_styles)
+            builder.h1 'text'
+          end
+        end
+      end
+    end
+  end
+end