juno-report 0.1.4 → 0.1.6

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Edson Júnior
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+# Juno Report
+
+Cry with Report Generation? Nevermore!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'juno-report'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install juno-report
+
+## Usage
+
+The generating reports is based on a YAML file with all rules, with the fields and their settings, divided by sections.
+
+### Body section
+
+Represents the records which will be iterated to report generating
+
+```yaml
+# example.yml
+body:
+  settings: {posY: 40, height: 25}
+  fields:
+    test_field1: [10]
+    test_field2: [220]
+    test_field3: [430, {column: "Named Test Field 3"}]
+  footer:
+    label_total: [10, {value: "Total"}]
+    totalizer: [220, {behavior: count}]
+    test_field3: [430, {behavior: sum}]
+```
+The [body] section ***must*** have three rules:
+
+* `settings`: Defines some configurations for body, like their height and ypos.
+* `fields`: Describes each field of record to be iterated.
+* `footer`: Drawn at the end of all printed records and calculates fields according behavior parameter.
+
+Each of these rules receives a array, where the first position is an integer representing the field horizontal position and
+the second position is a hash with some configurations.
+
+
+##### Settings
+
+* `height`: Set the of each row at report [Integer].
+* `posY`: Relative vertical position of last row at report [Integer].
+* `groups`: Describes which groups will be printed (More bellow) [Array].
+
+##### Fields
+
+* `size`: Font size of the field [Integer].
+* `align`: Defines the text alignment for each value [left|center|right].
+* `font`: Supports all font type provided by Prawn gem (See more in http://rubydoc.info/gems/prawn/Prawn/Font/AFM).
+* `style`:  Stylistic variations of a font [bold|italic].
+* `value`: Fixed text to be printed [string].
+* `column`: The header are "humanized" automatically, but you can set other value manually [string].
+
+##### Footer
+
+* `behavior`: Specify a function to be performed, sending as parameter the fieldname value [string].
+* `label`: Preppends a text to fieldname value specified [string].
+* `value`: Fixed text to be printed (fieldname value will be ignored) [string].
+
+With theses configurations already is possible generate a basic report, without groups feature.
+For this we need call the generate method on JunoReport module:
+
+```ruby
+# test.rb
+require 'juno-report'
+
+data = [
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 50},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 7},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 10},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 5},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 2},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 4},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 2", :test_field3 => 24}
+]
+
+JunoReport::generate(data, :report => 'example')
+```
+
+The first parameter must be a set of hash or objects which represent the report data. And the second parameter is a hash
+with the report settings, that can be:
+
+* `report`: The source of all rules. Must be a YAML file [string].
+* `type`: Specify if the report will be writed on the disc or returned to the caller such a stream [:file|:stream]
+* `filename`: Defines the report name which will be writed on disc. If not specified, the default name is "report.pdf" [string].
+
+### Page section
+
+You may want to print a title every time that a page is created. You simply insert a [page] section. 
+
+```yaml
+# example.yml
+page:
+  fields:
+    title1: [260, {size: 24, align: center, value: "Test Report"}]
+    subtitle1: [260, {size: 20, posY: 20, align: center, value: "Generated by Juno Report"}]
+body:
+  settings: {posY: 40, height: 25}
+  fields:
+    test_field1: [10]
+    test_field2: [220]
+    test_field3: [430, {column: "Named Test Field 3"}]
+  footer:
+    label_total: [10, {value: "Total"}]
+    totalizer: [220, {behavior: count}]
+    test_field3: [430, {behavior: sum}]
+```
+
+### Groups section
+
+For each item in groups parameter at body section you should create a section with same name. 
+This section represents the header configurations to every time that the group is printed and behaves like [body] section.
+
+```yaml
+# example.yml
+page:
+  fields:
+    title1: [260, {size: 24, align: center, value: "Test Report"}]
+    subtitle1: [260, {size: 20, posY: 20, align: center, value: "Generated by Juno Report"}]
+body:
+  settings: {posY: 40, height: 30, groups: [group_field1, group_field2]}
+  fields:
+    test_field1: [10]
+    test_field2: [220]
+    test_field3: [420, {column: "Named Test Field 3"}]
+  footer:
+    label_total: [10, {value: "Total"}]
+    totalizer1: [220, {behavior: count}]
+    test_field3: [420, {behavior: sum}]
+group_field1:
+  settings: {posY: 30, height: 10}
+  fields:
+    group_field1: [10, size: 25]
+  footer:
+    group_field1: [10, {label: "Total "}]
+    totalizer1: [220, {behavior: count}]
+    test_field3: [420, {behavior: sum}]
+group_field2:
+  settings: {posY: 30, height: 25}
+  fields:
+    group_field2: [10, size: 17]
+  footer:
+    group_field2: [10, {label: "Total "}]
+    totalizer1: [220, {behavior: count}]
+    test_field3: [420, {behavior: sum}]
+```
+
+Every time that a "group field" value changes, the group will be printed.
+
+```ruby
+# test.rb
+require 'juno-report'
+
+data = [
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 1", :test_field3 => 50, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 2', :test_field2 => "Test Value 2", :test_field3 => 16, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 5', :test_field2 => "Test Value 3", :test_field3 => 7, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 3', :test_field2 => "Test Value 9", :test_field3 => 10, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 2'},
+    {:test_field1 => 'Test Value 3', :test_field2 => "Test Value 2", :test_field3 => 4, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 2'},
+    {:test_field1 => 'Test Value 9', :test_field2 => "Test Value 4", :test_field3 => 10, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 2'},
+    {:test_field1 => 'Test Value 7', :test_field2 => "Test Value 5", :test_field3 => 5, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 3'},
+    {:test_field1 => 'Test Value 3', :test_field2 => "Test Value 5", :test_field3 => 2, :group_field1 => 'Group 1', :group_field2 => 'Subgroup 3'},
+    {:test_field1 => 'Test Value 3', :test_field2 => "Test Value 2", :test_field3 => 27, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 3', :test_field2 => "Test Value 5", :test_field3 => 2, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 0', :test_field2 => "Test Value 4", :test_field3 => 13, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 4', :test_field2 => "Test Value 7", :test_field3 => 7, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 1', :test_field2 => "Test Value 3", :test_field3 => 28, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 1'},
+    {:test_field1 => 'Test Value 4', :test_field2 => "Test Value 5", :test_field3 => 4, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 2'},
+    {:test_field1 => 'Test Value 5', :test_field2 => "Test Value 6", :test_field3 => 24, :group_field1 => 'Group 2', :group_field2 => 'Subgroup 2'}
+]
+
+JunoReport::generate(data, :report => 'example', :filename => 'juno-report.pdf')
+```
+
+## Contributors
+
+2. Edson Júnior (http://github.com/ebfjunior)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/juno-report.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require 'juno-report/version'
+
+Gem::Specification.new do |gem|
+    gem.name = "juno-report"
+    gem.version = JunoReport::VERSION
+    gem.platform    = Gem::Platform::RUBY
+    gem.authors = ["Edson Júnior"]
+    gem.email = ["ejunior.batista@gmail.com"]
+    gem.description = "A simple, but efficient, report genarator yaml based"
+    gem.summary = "Juno Reports generates reports with the minimum configuration and effort"
+    gem.homepage = "http://github.com/ebfjunior/juno-report"
+
+    gem.files = `git ls-files`.split("\n")
+    gem.executables = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+    gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
+    gem.require_paths = ["lib"]
+
+    gem.add_dependency "prawml"
+
+    gem.add_development_dependency 'rake'
+    gem.add_development_dependency 'rspec'
+end

data/lib/juno-report.rb

@@ -0,0 +1,33 @@
+require "juno-report/version"
+require "juno-report/pdf"
+require "juno-report/pdf/behaviors"
+require "juno-report/pdf/formatters"
+require "prawml"
+
+module JunoReport
+    autoload :ReportObject, 'juno-report/report_object'
+
+    def self.generate(collection, options)
+        rules = (File.open "#{options[:report]}.yml").read
+
+        defaults = {
+            :page_layout => :portrait
+        }
+
+        pdf = Prawml::PDF.new rules, defaults.merge(options)
+
+        pdf.extend JunoReport::Pdf
+        report  = pdf.generate(collection)
+
+        options[:type] ||= :file
+
+        if options[:type].eql? :file
+            report.render_file (options[:filename] || "report.pdf")
+        elsif options[:type].eql? :stream
+            return report.render
+        else
+            raise "Type options must be :file or :stream."
+        end
+
+    end
+end

data/lib/juno-report/pdf.rb

@@ -0,0 +1,279 @@
+module JunoReport
+    module Pdf
+
+        #Responsible for generate a report, based on rules passed as parameter in Juno::Report::generate.
+        #Juno Reports has support groups, just by especifying them at the rules file.
+        #Receives a collection as parameter, which should be a Array of records of the report.
+        def generate(collection)
+            @defaults = {
+                :style => :normal,
+                :size => 12,
+                :align => :left,
+                :format => false,
+                :font => 'Times-Roman',
+                :type => :text,
+                :color => '000000',
+                :fixed => false
+            }
+
+            get_sections
+            set_pos_y
+
+            @defaults.merge!(@sections[:defaults]) unless @sections[:defaults].nil?
+            
+            collection = [collection] unless collection.is_a?(Array) or collection.is_a?(ActiveRecord::Relation)
+            print_section :page unless @sections[:page].nil?
+            set_pos_y (@sections[:body][:settings][:posY] || 0)
+            @current_groups = {}
+            @footers = {}
+            @count = 0
+
+            unless @sections[:groups].empty?
+                reset_groups_values
+            else
+                draw_columns
+            end
+
+            initialize_footer_values
+            can_print_footer = false
+
+            collection.each do |record|
+                @record = record.is_a?(Hash) ? ReportObject.new(record) : record  #Convert the hash on a Object to futurely extend a module
+
+                headers_to_print, headers_height = calculate_header
+
+                unless headers_to_print.empty?
+                    @count = 0
+                    draw_footer headers_to_print, @sections[:groups] if can_print_footer
+                    if @posY - headers_height < 2*@sections[:body][:settings][:height]
+                        new_page
+                    else
+                        headers_to_print.each  { |group| print_section group, @record, true }
+                        draw_columns
+                    end
+                end
+                can_print_footer = true
+
+                update_footer_values
+                print_section :body, @record
+                @count += 1
+            end
+
+            draw_footer(@sections[:body][:settings][:groups].collect {|group| group.to_sym}, @sections[:groups]) if has_groups?
+            draw_footer [:body], @sections
+
+            @pdf
+        end
+
+        protected
+
+        #Creates a new page, restarting the vertical position of the pointer.
+        #Print the whole header for the current groups and the columns of the report.
+        def new_page
+            @pdf.start_new_page
+            set_pos_y
+            print_section :page unless @sections[:page].nil?
+            set_pos_y (@sections[:body][:settings][:posY] || 0)
+            @current_groups.each do |field, value|
+                print_section field.to_sym, @record, true
+            end
+            draw_columns
+        end
+
+        #Generic function to print a section like :body, :page or the group sections.
+        def print_section(section_name, values = nil, group = false)
+            section = !group ? @sections[section_name] : @sections[:groups][section_name]
+            set_pos_y(section[:settings][:posY] || 0) unless section_name.eql?(:body) || section[:settings].nil?
+            new_page if @posY < 30
+
+            if section_name.eql? :body and @count % 2 != 0
+                @pdf.fill_color "F7F7F7"
+                width = @options[:page_layout] == :portrait ? 530 : 770
+                @pdf.fill_rectangle [0, @posY+(section[:settings][:height]/2)], width, section[:settings][:height]
+            end
+
+            section[:fields].each do |field, settings|
+                symbolize! settings[1] unless settings[1].nil?
+                set_pos_y settings[1][:posY] unless settings[1].nil? || settings[1][:posY].nil?
+                settings = [settings[0], @posY, (@defaults.merge (settings[1] || { }))]
+                settings[2][:style] = settings[2][:style].to_sym
+                set_options settings[2]
+
+                value = set_value values, settings, section_name, field, group                
+                draw_text value, settings
+            end
+            set_pos_y (section[:settings][:height]) unless section[:settings].nil? || section[:settings][:height].nil?
+        end
+
+
+        def set_value(values, settings, section_name, field, group)
+            if group and !values.class.reflect_on_association(section_name).nil?
+                resource = values.send(section_name.to_sym)
+            else
+                resource = values
+            end
+
+            field.to_s.split(".").each do |part|
+                resource = resource.send(part) if !resource.class.reflect_on_association(part).nil?
+            end if settings[2][:value].nil?
+
+            field = field.to_s.split(".").last
+
+            value = settings[2][:value].nil? ? (resource.respond_to?(field) ? resource.send(field) : "") : settings[2][:value]
+
+            unless settings[2][:format].blank?
+                value = JunoReport::Pdf::Formatters.send(settings[2][:format], value)
+            end
+
+            string_cut = settings[2][:cut].nil? ? value : value[0..settings[2][:cut]]
+
+            string_cut
+        end
+
+        #Print a horizontal line with the whole width of the page.
+        def draw_line(y)
+            width = @options[:page_layout] == :portrait ? 530 : 770
+            @pdf.stroke { @pdf.horizontal_line 0, width, :at => y }
+        end
+
+        #Update the pointer vertical position to the specified value or 'zero' if the parameter is nil.
+        #Obs: Prawn pointer is decrescent, in other words, the left-top corner position is (0, 750). For
+        #semantic purposes, we set the same corner as (0, 0).
+        def set_pos_y(posY = nil)
+            height = @options[:page_layout] == :portrait ? 750 : 520
+            @posY = height if @posY.nil?
+            @posY = posY.nil? ? height : @posY - posY
+        end
+
+        #Convert to symbol all hash keys, recursively.
+        def symbolize! hash
+            hash.symbolize_keys!
+            hash.values.select{|v| v.is_a? Hash}.each{|h| symbolize!(h)}
+        end
+
+        #Convert the structure of the rules to facilitate the generating proccess.
+        def get_sections
+            symbolize! @rules
+            raise "[body] section on YAML file is needed to generate the report." if @rules[:body].nil?
+            @sections = {:page => @rules[:page], :body => @rules[:body], :defaults => @rules[:defaults], :groups => {}}
+            @sections[:body][:settings][:groups].each { |group|  @sections[:groups][group.to_sym] = @rules[group.to_sym] } if has_groups?
+        end
+
+        #@current_groups storages the value for all groups. When a value is changed, the header is printed.
+        #This function set nil value for every item in @current_groups if the parameter is not passed. Otherwise,
+        #only the forward groups will be cleaned to avoid conflict problems with others groups.
+        def reset_groups_values current_group = nil
+            groups = @sections[:body][:settings][:groups]
+            groups.each_with_index do |group, idx|
+                @current_groups[group] = nil if current_group.nil? || groups.index(current_group.to_s) <= idx
+            end
+        end
+
+
+        #Calculates the headers which must be printed before print the current record.
+        #The function also returns the current header height to create a new page if the
+        #page remaining space is smaller than (header + a record height)
+        def calculate_header
+            headers = []
+            height = 0
+            @current_groups.each do |field, current_value|
+                identifier_field = @sections[:groups][field.to_sym][:settings][:identifier_field] || nil
+                value = (!@record.class.reflect_on_association(field).nil? and !identifier_field.nil?) ? @record.send(field.to_sym).send(identifier_field) : @record.send(field)
+
+                if value != current_value
+                    reset_groups_values field
+
+                    headers << field.to_sym
+                    height += @sections[:groups][field.to_sym][:settings][:height] + @sections[:groups][field.to_sym][:settings][:posY]
+
+                    @current_groups[field] = value
+                end
+            end unless @current_groups.empty?
+
+            [headers, height]
+        end
+
+        #Create a structure to calculate the footer values for all groups. Appends the footer body to total values too.
+        def initialize_footer_values
+            @sections[:body][:settings][:groups].each do |group|
+                current_footer = {}
+                @sections[:groups][group.to_sym][:footer].each { |field, settings| current_footer[field] = nil } unless @sections[:groups][group.to_sym][:footer].nil?
+                @footers[group.to_sym] = current_footer unless current_footer.empty?
+            end if has_groups?
+            raise "The report must have at least a footer on body section" if @sections[:body][:footer].nil?
+            current_footer = {}
+            @sections[:body][:footer].each { |field, settings| current_footer[field] = nil }
+            @footers[:body] = current_footer unless current_footer.empty?
+        end
+
+        #Call the function that calculates the footer values for all groups and the total body footer, with
+        #different source for each
+        def update_footer_values
+            @sections[:body][:settings][:groups].reverse_each do |group|
+                calculate_footer_values group,  @sections[:groups][group.to_sym][:footer]
+            end if has_groups?
+            calculate_footer_values :body, @sections[:body][:footer]
+        end
+
+        #Returns the values to the group passed as parameter. If :behavior setting is used, so a
+        #function in [lib/pdf/behaviors.rb] calculates the value of current field, else the report
+        #method is called
+        def calculate_footer_values group, source
+            @footers[group.to_sym].each do |field, value|
+                footer_rule = source[field]
+                symbolize! footer_rule[1]
+                unless footer_rule[1][:behavior].nil?
+                    @footers[group.to_sym][field] = JunoReport::Pdf::Behaviors.send footer_rule[1][:behavior].to_sym, value, (@record.respond_to?(field) ? @record.send(field) : nil)
+                else
+                    if footer_rule[1][:value].blank?
+                        value = !@record.class.reflect_on_association(group.to_sym).nil? ? @record.send(group.to_sym).send(field.to_sym) : @record.send(field)
+                    else
+                        value = footer_rule[1][:value]
+                    end
+                    @footers[group.to_sym][field] = footer_rule[1][:label].to_s + value
+                end unless @footers[group.to_sym].nil? || footer_rule[1].nil?
+            end
+        end
+
+        #Print the footers according to the groups and source specified
+        def draw_footer footers_to_print, source
+            footers_to_print.reverse_each do |group|
+                draw_line(@posY + @sections[:body][:settings][:height]/2)
+                source[group][:footer].each do |field, settings|
+                    settings = [settings[0], @posY, (@defaults.merge (settings[1] || { }).symbolize_keys!)]
+                    settings[2][:style] = settings[2][:style].to_sym
+                    set_options settings[2]
+                    draw_text @footers[group][field], settings
+                end
+                draw_line(@posY - @sections[:body][:settings][:height]/4)
+                set_pos_y @sections[:body][:settings][:height]
+
+                reset_footer group
+            end
+        end
+
+        #Resets the footer to next groups
+        def reset_footer(group); @footers[group].each { |field, value| @footers[group][field] = nil }; end
+
+        #Based on the Key names of the :body section at the rules, the function draw columns with
+        #baselines on the top and bottom of the header.
+        def draw_columns
+            @sections[:body][:fields].each do |field, settings|
+                settings = [settings[0], @posY, (@defaults.merge (settings[1] || { }).symbolize_keys!)]
+                settings[2][:style] = settings[2][:style].to_sym
+                set_options settings[2]
+                draw_line(@posY + @sections[:body][:settings][:height]/2)
+                field = settings[2][:column] || field.to_s.split('_').inject('') do |str, part|
+                    str << part.camelize << " "
+                end
+                draw_text field, settings
+            end
+            draw_line(@posY - @sections[:body][:settings][:height]/2)
+            set_pos_y @sections[:body][:settings][:height]
+        end
+
+        def has_groups?
+            !@sections[:body][:settings][:groups].nil?
+        end
+    end
+end