tn_pdf 0.0.2 → 0.0.8

data/lib/tn_pdf/table.rb

@@ -1,28 +1,51 @@
 require 'tn_pdf/table_column'
-require 'prawn'
 
 module TnPDF
+  # A representation {Report}'s table. It's an abstraction above a Prawn
+  # table that that 'defaultizes' a commonly used structure - a table that is a
+  # {#collection} of elements displayed as {#rows}, on which each of the {#columns}
+  # is a property of an object.
+  #
+  # Through {Table::Column}, it also provides many configurable
+  # column 'types', such as currency and float, to ease the pain of formatting
+  # the table on a consistent manner.
+  #
+  # Above that, it also provides a very useful feature that Prawn misses:
+  # column spanning (although currently only on footers).
+  #
+  # == Table footers
+  #
+  # Table footers are special rows that are often used to make a summary of
+  # the table data.
+  #
+  # The main differences between a footer row and a ordinary row are:
+  # [Column spanning]
+  #   Normal row's cells can't span across multiple columns,
+  #   while a footer cell can.
+  # [Calculation]
+  #   In a normal row, the cells' values are automatically
+  #   calculated using the provided method, while in a footer
+  #   row the displayed value should be directly passed.
+  # [Scope]
+  #   A footer row acts in the scope of the whole collection, while
+  #   a normal row represents a single object.
+  # [Format]
+  #   Footer rows can be formatted in a differente manner, through
+  #   the use of the +table_footer_*+ properties on {Configuration}
   class Table
     attr_accessor *Configuration.table_properties_names
 
-    def initialize
+    def initialize(document)
       Configuration.table_properties_names.each do |property|
         send("#{property}=", Configuration["table_#{property}"])
       end
+      @document = document
     end
 
-    def columns_hash
-      columns_hash = ActiveSupport::OrderedHash.new
-      columns.inject(columns_hash) do |hash, column|
-        hash[column.header] = column.to_proc
-        hash
-      end
-    end
-
-    def columns_headers
-      columns.map(&:header)
-    end
-
+    # The collection of objects to be represented by the table.
+    # @return [Array]
+    # @raise [ArgumentError] If the passed value isn't an Array
+    attr_accessor :collection
     def collection
       @collection ||= Array.new
     end
@@ -32,13 +55,48 @@ module TnPDF
       @collection = collection
     end
 
+    # The columns already set on this table. Despite of being first provided
+    # as Arrays, the members of this collection are instances of {Column}.
+    # @return [Array]
+    attr_reader :columns
+    def columns(type = :all)
+      @columns ||= []
+      if type == :all
+        @columns
+      else
+        @columns.select { |c| c.column_width_type == type }
+      end
+    end
+
+    # Adds a column to the table. The argument should be a {Column}, or an
+    # argument that {Column#initialize} accepts.
+    # @param [Column] (see Column#initialize)
     def add_column(column)
       unless column.kind_of? Column
         column = Column.new(column)
       end
+      column.index = columns.count
+      column.max_width = document_width
       columns << column
     end
 
+    def remove_column(column)
+      if column.kind_of? Column
+        columns.delete(column)
+      elsif column.kind_of? Fixnum
+        columns.delete_at(column)
+      else
+        raise ArgumentError, "Unrecognized argument '#{column.inspect}'"
+      end
+    end
+
+    def reset_columns
+      @columns = []
+    end
+
+    # The already computed rows of the table. Needs {#columns} and
+    # {#collection} to be already set to return something meaningful.
+    # @return [Array] An array containing the rows to be rendered.
     def rows
       collection.map do |object|
         columns.map do |column|
@@ -47,45 +105,239 @@ module TnPDF
       end
     end
 
-    def render(document, max_height)
-      table = document.make_table([columns_headers]+rows) do |table|
-        table.header = self.multipage_headers
-        table.cells.borders = [] unless self.borders
-        table.row_colors = [self.odd_row_color, self.even_row_color]
-        table.row(0).background_color = self.header_color
+    def render(max_height)
+      x_pos = x_pos_on(document, document_width)
+
+      initialize_generated_widths
+      total_width = self.column_widths.sum
 
-        columns.each_with_index do |column, index|
-          style = column.style.reject { |k, v| [:format, :decimal].include? k }
-          table.columns(index).style(style)
-        end
-      end
-      x_pos = x_pos_on(document, table.width)
       document.bounding_box([x_pos, document.cursor],
-                            :width => table.width,
+                            :width => total_width,
                             :height => max_height) do
-        table.draw
+
+        table_data  = [[header_table]]
+        table_data += minitables
+        table_data += footer_tables
+
+        document.text *([text_before].flatten)
+        document.font_size self.font_size
+
+        document.table(table_data, :column_widths => [total_width],
+                                   :width => total_width) do |table|
+
+          table.header = self.multipage_headers
+          stylize_table(table)
+        end
+
+        document.text *([text_after].flatten)
       end
     end
 
-    def columns
-      @columns ||= []
+    # Adds a footer row to the table.
+    #
+    # The argument to this method should be an Array (or a block that returns
+    # an Array) in which each member is a cell in the format:
+    #   [content, colspan, style]
+    # where:
+    # [*content*]
+    #   Is the content of the cell. May be a label, a sum of some values
+    #   from the collection etc.
+    # [*colspan*]
+    #   A number representing how many columns of the table this cell is going
+    #   to span across. Be warned that the sum of all the colspans on a given
+    #   footer row should always match the number of columns in the table, or
+    #   an exception will be raised.
+    # [*style*]
+    #   The formatting style of the cell. Refer to {Column#style Column#style}
+    #   for details.
+    # @example
+    #   # On a table that has 2 columns
+    #   table.add_footer [
+    #     ["Total", 1, :text],
+    #     [12345,   1, :number]
+    #   ]
+    # @example
+    #   # On a table that has 3 columns
+    #   table.add_footer do |collection|
+    #     calculation = collection.map(&:value).sum
+    #     [
+    #       ["Calculation", 1, :text],
+    #       [calculation,   2, :number]
+    #     ]
+    #   end
+    def add_footer(row=nil, &block)
+      unless block_given? or row.kind_of? Array
+        raise ArgumentError, "No block or array was passed"
+      end
+
+      row = block.call(collection) if block_given?
+
+      # [content, colspan, style]
+      row = row.map do |field|
+        field[2] ||= :text
+        content = Column.format_value(field[0],
+                                      Column.style_for(field[2]))
+
+        OpenStruct.new(:content => content,
+                       :colspan => field[1],
+                       :style   => Column.prawn_style_for(field[2]) )
+      end
+
+      row.inject(0) do |first_column, field|
+        final_column = first_column+field.colspan-1
+        field.colspan_range = (first_column..final_column)
+        final_column+1
+      end
+
+      total_colspan = row.map(&:colspan).inject(:+)
+      unless total_colspan == columns.length
+        raise ArgumentError,
+          "Total colspan value '#{total_colspan}' differs from the "+
+          "table's columns number '#{columns.length}'"
+      end
+
+      footer_rows << row
+    end
+
+    def row_color(row_number)
+      row_number % 2 == 0 ?
+        self.even_row_color:
+        self.odd_row_color
+    end
+
+    def column_widths(type = :all)
+      selected_columns = columns(type)
+      selected_columns.sort_by(&:index).map(&:width)
     end
 
     private
 
+    def columns_headers
+      columns.map(&:header)
+    end
+
     def x_pos_on(document, table_width)
       case align
-        when :left
-          0
-        when :center
-          (document.bounds.right - table_width)/2.0
-        when :right
-          document.bounds.right - table_width
-        else
-          0
+      when :left
+        0
+      when :center
+        (document.bounds.right - table_width)/2.0
+      when :right
+        document.bounds.right - table_width
+      else
+        0
+      end
+    end
+
+    def document
+      @document
+    end
+
+    def prawn_table
+      if @prev_headers != columns_headers or
+         @prev_rows != rows
+
+        @prawn_table = nil
+        @prev_headers = columns_headers
+        @prev_rows    = rows
+      end
+
+      @prawn_table ||= begin
+        document.make_table([columns_headers]+rows) do |table|
+          document.font_size = self.font_size
+          stylize_table(table)
+        end
       end
     end
 
+    def minitables
+      row_number = 0 # I hate this as much as you do
+      rows.map do |row|
+        minitable = document.make_table([row],
+                                       :column_widths => column_widths) do |table|
+          columns.each_with_index do |column, index|
+            table.columns(index).style(column.prawn_style)
+          end
+          table.rows(0..-1).size = self.font_size
+          row_number += 1
+          stylize_table(table)
+          table.cells.background_color = self.row_color(row_number)
+        end
+        [minitable]
+      end
+    end
+
+    def header_table
+      document.make_table([columns_headers],
+                          :column_widths => column_widths) do |table|
+        header_row = table.row(0)
+        header_row.background_color = self.header_color
+        header_row.font_style = self.header_font_style
+        header_row.size = self.header_font_size
+        header_row.font = self.header_font
+        header_row.align = :center
+
+        stylize_table(table)
+      end
+    end
+
+    def stylize_table(table)
+      table.cells.borders = borders || []
+    end
+
+    def footer_rows
+      @footer_rows ||= []
+    end
+
+    def footer_tables
+      footer_rows.map do |row|
+        [footer_table_for(row)]
+      end
+    end
+
+    def footer_table_for(row)
+      row_array     = [row.map(&:content)]
+      footer_column_widths = row.map do |field|
+        column_widths[field.colspan_range].inject(:+)
+      end
+
+      document.make_table(row_array,
+                          :column_widths => footer_column_widths) do |table|
+
+        footer_row = table.row(0)
+        footer_row.background_color = self.footer_color
+        footer_row.font_style = self.footer_font_style
+        footer_row.size = self.footer_font_size
+        footer_row.font = self.footer_font
+
+        row.each_with_index do |field, index|
+          table.columns(index).style(field.style)
+        end
+        stylize_table(table)
+      end
+    end
+
+    def initialize_generated_widths
+      columns(:generated).each do |column|
+        index = column.index
+        column.width = prawn_table.columns(index).width
+      end
+      generated_widths_sum = column_widths(:generated).sum
+
+      fixed_widths_sum = column_widths(:fixed).sum
+      percentage_widths_sum = column_widths(:percentage).sum
+      remaining_space = document_width - percentage_widths_sum - fixed_widths_sum
+
+      columns(:generated).each do |column|
+        width = column.width
+        column.width = (width/generated_widths_sum)*remaining_space
+        column.column_width_type = :fixed
+      end
+    end
+
+    def document_width
+      document.bounds.width
+    end
   end
 
 end

data/lib/tn_pdf/table_column.rb

@@ -1,49 +1,130 @@
 module TnPDF
   class Table
-
+    # Represents a column of a table. Typically not used directly, but through
+    # {Table#add_column Table#add_column} and friends.
     class Column
-      attr_reader :header, :proc, :collection, :style
+      # Is a String that contains the column header
+      # @return [String]
+      attr_reader :header
+
+      # Is an object that responds to to_proc, typically a Symbol or a Proc.
+      # It represents the procedure used to extract the information from the
+      # object.
+      # @example
+      #   column.proc = :full_name
+      # @example
+      #   myProc = Proc.new do |person|
+      #     "#{person.id} - #{person.name}"
+      #   end
+      #   column.proc = myProc
+      # @return [#to_proc]
+      attr_reader :proc
+
+      # Defines how the formatting of the result will occur. Typically used
+      # for formatting currencies, numbers etc, but can be anything defined
+      # on {Configuration}, the {TnPDF::Configuration.load_from YAML Configuration file}
+      # or a Hash that contains (at least) the :format key.
+      # It defaults to the :text style.
+      # @example
+      #   column.style = :currency
+      # @example
+      #   column.style = { :format  => "%.2f",
+      #                    :decimal => ",",
+      #                    :align   => :right }
+      # @return [Symbol, Hash]
+      attr_reader :style
+
+      # Defines the (visual) width of the column. May be defined in PDF
+      # points (1/72 inch), a String "in" the cm or mm units, or a String
+      # representing a percentage.
+      #
+      # It is important to note that, in the case of a percentage-based
+      # column, it represents a percentage of the *page* on which the table
+      # will be rendered, not of the table.
+      # @example
+      #   width = 1234.45
+      # @example
+      #   width = "1.5cm"
+      # @example
+      #   width = "14mm"
+      # @example
+      #   width = "20%"
+      # @return [Double, String]
+      attr_accessor :width
 
       alias_method :to_proc, :proc
+
+      attr_accessor :column_width_type
+      # Creates a new Column
+      #
+      # The parameter has to be an Array in the form:
+      #   [header, procedure, style, width]
+      # where:
+      # [{#header header} (required)]
+      #   {include:#header}
+      # [{#proc procedure} (required)]
+      #   {include:#proc}
+      # [{#style style} (optional)]
+      #   {include:#style}
+      # [{#width width} (optional)]
+      #   {include:#width}
+      # @example
+      #   Column.new [ "Full name", :full_name ]
+      # @example
+      #   sum = Proc.new { |obj| obj.value_a + obj.value_b }
+      #   Column.new [ "Sum", sum, :number, "15%" ]
       def initialize(arguments)
         raise ArgumentError unless valid_column_args?(arguments)
         @header = arguments[0].to_s
         @proc   = arguments[1].to_proc
-        @style = style_for(arguments[2])
-      end
-
-      def values_for(collection)
-        collection.map do |object|
-          value_for(object)
+        @style  = Column.style_for(arguments[2])
+        @width  = Configuration.perform_conversions arguments[3]
+        if @width.nil?
+          column_width_type = :generated
         end
       end
 
       def value_for(object)
         value = @proc.call(object)
-        method = if value.respond_to?(:strftime)
-                   value.method(:strftime)
-                 elsif value.respond_to?(:sprintf)
-                   value.method(:sprintf)
-                 else
-                   method(:sprintf)
-                 end
-        string = method.arity == 1 ?
-                   method.call(style[:format]) :
-                   method.call(style[:format], value)
+        Column.format_value(value, style)
+      end
 
-        string.gsub!(".", style[:decimal]) if style[:decimal]
-        return string
-      rescue TypeError
-        puts "WARNING: Bad format '#{style[:format]}' for value '#{value}'"
-        return value.to_s
+      def prawn_style
+        style.reject { |k, v| [:format, :decimal].include? k }
+      end
+
+      def width
+        if column_width_type == :percentage
+          unless max_width
+            raise ArgumentError, "Maximum width should be set for percentage-based widths!"
+          end
+          match = @width.scan(/(\d+\.?\d*)%/)
+
+          number = match[0][0].to_f/100.0
+          number*max_width
+        else
+          @width
+        end
+      end
+
+      def column_width_type
+        @column_width_type ||=
+          if @width.kind_of? String
+              (@width =~ /(\d+\.?\d*)%/) ? :percentage : :fixed
+          elsif @width.kind_of? Numeric
+            :fixed
+          else
+            :generated
+          end
       end
 
+      attr_accessor :index, :max_width
       private
 
       def valid_column_args?(column_args)
         validity  = true
         validity &= column_args.kind_of? Array
-        validity &= column_args.count == 2 || column_args.count == 3
+        validity &= (2..4).include? column_args.count
         validity &= column_args[0].respond_to?(:to_s)
         validity &= column_args[1].respond_to?(:to_proc)
       rescue NoMethodError
@@ -52,7 +133,7 @@ module TnPDF
         return validity
       end
 
-      def style_for(type)
+      def self.style_for(type)
         if type.nil?
           {:format => "%s"}
         elsif type.kind_of? Symbol
@@ -61,6 +142,34 @@ module TnPDF
           type
         end
       end
+
+      def self.prawn_style_for(type)
+        style_for(type).reject { |k, v| [:format, :decimal].include? k }
+      end
+
+      def self.format_value(value, style)
+        formatting_method = formatting_method_for(value)
+        string = formatting_method.call(style[:format])
+
+        string.gsub!(".", style[:decimal]) if style[:decimal]
+        return string
+      rescue TypeError, ArgumentError
+        puts "WARNING: Bad format '#{style[:format]}' for value '#{value.inspect}'"
+        return value.to_s
+      end
+
+      def self.formatting_method_for(value)
+        if value.respond_to?(:strftime)
+          lambda { |format| value.strftime(format) }
+        elsif value.respond_to?(:sprintf)
+          lambda { |format| value.sprintf(format) }
+        elsif value.nil?
+          lambda { |_| "" }
+        else
+          lambda { |format| sprintf(format, value) }
+        end
+      end
+      private_class_method :formatting_method_for
     end
 
   end

data/lib/tn_pdf/version.rb

@@ -1,3 +1,3 @@
 module TnPDF
-  VERSION = "0.0.2"
+  VERSION = "0.0.8"
 end

data/lib/tn_pdf.rb

@@ -1,7 +1,10 @@
 require 'rubygems'
-require 'active_support' # Because of to_options!
 require 'prawn'
 require 'prawn/measurement_extensions'
+require 'ostruct'
+require 'backports'
+
+load 'prawn/table_fix.rb'
 
 require 'tn_pdf/configuration'
 require 'tn_pdf/report'

data/spec/tn_pdf/box_spec.rb

@@ -19,17 +19,17 @@ module TnPDF
 
         it "accepts extra text options to prawn by passing hashes" do
           document = Prawn::Document.new
-          box = Box.new( :text => {:text => "text", :font => "DejaVu Sans"} )
+          box = Box.new( :text => {:text => "text", :font => "Courier"} )
 
-          document.should_receive(:text).with("text", hash_including(:font => "DejaVu Sans") )
+          document.should_receive(:text).with("text", hash_including(:font => "Courier") )
           box.render(document, [0,0], 100)
         end
 
         it "accepts extra image options to prawn by passing hashes" do
           document = Prawn::Document.new
-          box = Box.new( :image => {:path => "image.jpg", :width => 1.cm } )
+          box = Box.new( :image => {:file => "./image.jpg", :width => 1.cm } )
 
-          document.should_receive(:image).with("image.jpg", hash_including(:width => 1.cm) )
+          document.should_receive(:image).with("./image.jpg", hash_including(:width => 1.cm) )
           box.render(document, [0,0], 100)
         end
       end

data/spec/tn_pdf/table_spec.rb

@@ -5,7 +5,10 @@ module TnPDF
     const_set("Column",EmptyClass) unless const_defined?("Column")
   end
 
+
   describe Table do
+    let(:subject)  { Table.new(stub('Document')) }
+
     describe "#columns_hash" do
       it "is a kind of Hash" do
         subject.columns_hash.should be_kind_of(Hash)
@@ -71,30 +74,31 @@ module TnPDF
 
     describe "#rows" do
       it "returns the values of the objects for each column" do
-        subject = Table.new # Just to be explicit
+        subject = Table.new(stub('Document')) # Just to be explicit
         subject.add_column( ["String", :to_s] )
         subject.add_column( ["Integer", :to_i] )
         subject.add_column( ["Doubled", Proc.new { |x| x*2 } ] )
 
         subject.collection = [1, 2, 3]
-        subject.rows.should == [ ["1", 1, 2],
-                                 ["2", 2, 4],
-                                 ["3", 3, 6] ]
+        subject.rows.should == [ ["1", "1", "2"],
+                                 ["2", "2", "4"],
+                                 ["3", "3", "6"] ]
       end
     end
 
     describe "#render" do
-      let(:document) do
-         mock("Prawn::Document").as_null_object
-      end
-
       let(:table) do
         mock("Prawn::Table").as_null_object
       end
 
+      let(:document) do
+        mock("Prawn::Document").as_null_object
+      end
+
       it "instantiates a Prawn::Table instance" do
         document.should_receive(:make_table).and_return(table)
-        subject.render(document, 0)
+        subject = Table.new(document)
+        subject.render(0)
       end
     end
   end

data/tn_pdf.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "tn_pdf"
 
   s.add_dependency('prawn', '~> 0.11.1')
-  s.add_dependency('activesupport')
+  s.add_dependency('backports')
 
   s.add_development_dependency('rspec', '~> 2.6.0')