ruport 1.6.3 → 1.8.0

data/README

@@ -1,114 +0,0 @@
-# -----------------------------------------------------------------
-# Contents:
-# 
-#  + What Ruport Is
-#  + Installation
-#  + Resources
-#  + Hacking
-#
-# = What Ruport Is
-#
-# Ruby Reports (Ruport) is an extensible reporting system.
-# 
-# It aims to be as lightweight as possible while still providing core support
-# for data aggregation and manipulation as well as multi-format rendering 
-# of reports.
-#
-# Ruport provides tools for using a number of data sources, including CSV files,
-# ActiveRecord models, and raw SQL connections via RubyDBI (through ruport-util).
-#
-# Data manipulation is easy as there are standard structures that support
-# record, table, and grouping operations.  These all can be extended to
-# implement custom behavior as needed.
-#
-# For common tasks, Ruport provides formatters for CSV, HTML, PDF, and text-
-# based reports.  However, the real power lies in building custom report
-# controllers and formatters.  The base formatting libraries provide a number 
-# of helper functions that will let you build complex reports while maintaining 
-# a DRY and consistent interface.
-#
-# To get a quick feel for what you can accomplish with Ruport, take a look at
-# a few simple examples provided on our web site.
-#
-# http://rubyreports.org/examples.html
-#
-# Since Ruport's core support is intentionally minimalistic, you may be looking
-# for some higher level support for specific needs such as graphing, invoices,
-# report mailing support, etc.  For this, you may wish to take a look at the
-# ruport-util package, which contains some generally useful tools and libraries
-# to extend Ruport's capabilities.
-#
-# = Installation 
-#
-# To install ruport via rubygems:
-#   
-#   sudo gem install ruport 
-#
-# Check to see if it installed properly:
-#
-#   ruby -rubygems -e "require 'ruport'; puts Ruport::VERSION"
-#
-# If you get an error, please let us know on our mailing list. 
-#
-# Dependencies Details:
-#   
-#  -- formatting
-#
-# Ruport relies on PDF::Writer and FasterCSV for its formatting support.
-# If you want to make use of textile helpers, you'll also need RedCloth.
-#
-#  -- database interaction
-#
-# If you wish to use Ruport to report against a rails project, 
-# a camping project, or do standalone acts_as_reportable reports, you'll need
-# ActiveRecord and the acts_as_reportable gem.
-#
-# If you want to use Ruport::Query for raw SQL support, you'll need to 
-# install ruport-util, RubyDBI and whatever database drivers you might need.
-#
-# = Resources              
-#
-# Our developers have published a free-content book about all things
-# Ruport, including complete coverage of acts_as_reportable and some of 
-# ruport-util's features.  This book serves as the definitive guide to 
-# Ruport, so all users should become acquainted with it:
-# 
-#   http://ruportbook.com
-#
-# The next best way to get help and make suggestions is the Ruport mailing list.
-# This software is on the move, so the list is the most reliable way of getting
-# up to date information.
-#
-#  -  You can sign up and/or view the archives here:
-#     http://groups.google.com/group/ruby-reports                                                   
-#
-# If you are looking to dig a little deeper, there are a couple more resources
-# that may be helpful to you.
-#
-#  -  The latest stable API documentation is available at:
-#     http://api.rubyreports.org
-#
-#  -  Our Trac is at: http://code.rubyreports.org/ruport
-#     You may use the username ruport and password blinky to file tickets.
-#
-# = Hacking
-#
-# If you'd like to contribute code to Ruport, please join our development 
-# mailing list, and let us know what you'd like to do!
-#
-#   http://groups.google.com/group/ruport-dev
-# 
-# It also may be worthwhile to join this list if you plan on running edge
-# versions of Ruport, as this is where we make announcements about major 
-# breakage in trunk. 
-#
-# We are very responsive to contributors, and review every patch we receive
-# fairly quickly.  Most contributors who successfully get a patch or two applied
-# are given write access to the repositories and invited to join Ruport's 
-# development team.  Since we view every user as potential contributor, this
-# approach works well for us.
-#
-# So if you want to help out with Ruport, we'll happy accept your efforts!
-
-
-

data/lib/ruport/formatter/pdf.rb

@@ -1,591 +0,0 @@
-# Ruport : Extensible Reporting System                                
-#
-# formatter/pdf.rb provides text formatting for Ruport.
-#     
-# Created by Gregory Brown, February 2006     
-# Extended by James Healy, Fall 2006
-# Copyright (C) 2006-2007 Gregory Brown / James Healy, All Rights Reserved.  
-#
-# Initially inspired by some ideas and code from Simon Claret,
-# with many improvements from James Healy and Michael Milner over time.
-#
-# This is free software distributed under the same terms as Ruby 1.8
-# See LICENSE and COPYING for details.   
-#
-module Ruport
-   
-  # This class provides PDF output for Ruport's Table, Group, and Grouping
-  # controllers.  It wraps Austin Ziegler's PDF::Writer to provide a higher
-  # level interface and provides a number of helpers designed to make
-  # generating PDF reports much easier.  You will typically want to build
-  # subclasses of this formatter to customize it as needed.
-  #
-  # Many methods forward options to PDF::Writer, so you may wish to consult
-  # its API docs.
-  #
-  # === Rendering Options
-  #     General:
-  #       * paper_size  #=> "LETTER"
-  #       * paper_orientation #=> :portrait
-  #
-  #     Text:
-  #       * text_format (sets options to be passed to add_text by default)  
-  #     
-  #     Table:
-  #       * table_format (a hash that can take any of the options available
-  #           to PDF::SimpleTable)
-  #       * table_format[:maximum_width] #=> 500   
-  #
-  #     Grouping:
-  #       * style (:inline,:justified,:separated,:offset)
-  #
-  class Formatter::PDF < Formatter         
-
-    module PDFWriterProxy #:nodoc:
-      def method_missing(id,*args)
-        super(id,*args)
-      rescue
-        pdf_writer.send(id,*args)
-      end
-    end
-    
-    renders :pdf, :for => [ Controller::Row, Controller::Table,
-                            Controller::Group, Controller::Grouping ]
-    
-    attr_writer :pdf_writer
-
-
-    # If you use this macro in your formatter, Ruport will automatically forward
-    # calls to the underlying PDF::Writer, for any methods that are not wrapped
-    # or redefined.
-    def self.proxy_to_pdf_writer
-      include PDFWriterProxy
-    end
-
-    save_as_binary_file
-
-    def initialize
-      Ruport.quiet do   
-        require "pdf/writer"
-        require "pdf/simpletable"
-      end
-    end
-    
-    # Hook for setting available options using a template. See the template 
-    # documentation for the available options and their format.
-    def apply_template
-      apply_page_format_template(template.page)
-      apply_text_format_template(template.text)
-      apply_table_format_template(template.table)
-      apply_column_format_template(template.column)
-      apply_heading_format_template(template.heading)
-      apply_grouping_format_template(template.grouping)
-    end
-
-    # Returns the current PDF::Writer object or creates a new one if it has not
-    # been set yet.
-    #    
-    def pdf_writer
-      @pdf_writer ||= options.formatter ||
-        ::PDF::Writer.new( :paper => options.paper_size || "LETTER",
-              :orientation => options.paper_orientation || :portrait)
-    end
-
-    # Calls the draw_table method.
-    #
-    def build_table_body
-      draw_table(data)
-    end
-
-    # Appends the results of PDF::Writer#render to output for your 
-    # <tt>pdf_writer</tt> object.
-    #
-    def finalize_table
-      render_pdf unless options.skip_finalize_table
-    end
-    
-    # Generates a header with the group name for Controller::Group.
-    def build_group_header
-      pad(10) { add_text data.name.to_s, :justification => :center }
-    end
-    
-    # Renders the group as a table for Controller::Group.
-    def build_group_body
-      render_table data, options.to_hash.merge(:formatter => pdf_writer)
-    end
-                     
-    # Determines which style to use and renders the main body for
-    # Controller::Grouping.
-    def build_grouping_body 
-      case options.style
-      when :inline
-        render_inline_grouping(options.to_hash.merge(:formatter => pdf_writer,
-            :skip_finalize_table => true))
-      when :justified, :separated
-        render_justified_or_separated_grouping
-      when :offset
-        render_offset_grouping
-      else
-        raise NotImplementedError, "Unknown style"
-      end
-    end
-   
-    # Calls <tt>render_pdf</tt>.
-    def finalize_grouping
-      render_pdf
-    end
-
-    # Call PDF::Writer#text with the given arguments, using
-    # <tt>text_format</tt> defaults, if they are defined.                                       
-    #
-    # Example:
-    #
-    #   options.text_format { :font_size => 14 }
-    #
-    #   add_text("Hello Joe") #renders at 14pt
-    #   add_text("Hello Mike",:font_size => 16) # renders at 16pt
-    def add_text(text, format_opts={})
-      format_opts = options.text_format.merge(format_opts) if options.text_format
-      pdf_writer.text(text, format_opts)
-    end
-
-    # Calls PDF::Writer#render and appends to <tt>output</tt>.
-    def render_pdf
-      output << pdf_writer.render
-    end
-       
-    # - If the image is bigger than the box, it will be scaled down until
-    #   it fits.
-    # - If the image is smaller than the box, it won't be resized.
-    #
-    # options:
-    # - :x: left bound of box
-    # - :y: bottom bound of box
-    # - :width: width of box
-    # - :height: height of box
-    #
-    def center_image_in_box(path, image_opts={}) 
-      x = image_opts[:x]
-      y = image_opts[:y]
-      width = image_opts[:width]
-      height = image_opts[:height]
-      info = ::PDF::Writer::Graphics::ImageInfo.new(File.open(path, "rb"))
-
-      # reduce the size of the image until it fits into the requested box
-      img_width, img_height =
-        fit_image_in_box(info.width,width,info.height,height)
-      
-      # if the image is smaller than the box, calculate the white space buffer
-      x, y = add_white_space(x,y,img_width,width,img_height,height)
-
-      pdf_writer.add_image_from_file(path, x, y, img_width, img_height) 
-    end
-
-    # Draws some text on the canvas, surrounded by a box with rounded corners.
-    #
-    # Yields an OpenStruct which options can be defined on.
-    # 
-    # Example:
-    #
-    #    rounded_text_box(options.text) do |o|
-    #      o.radius = 5
-    #      o.width     = options.width  || 400
-    #      o.height    = options.height || 130
-    #      o.font_size = options.font_size || 12
-    #      o.heading   = options.heading
-    #   
-    #      o.x = pdf_writer.absolute_x_middle - o.width/2
-    #      o.y = 300
-    #    end
-    #
-    def rounded_text_box(text)
-      opts = OpenStruct.new
-      yield(opts)
-      
-      resize_text_to_box(text, opts)
-      
-      pdf_writer.save_state
-      draw_box(opts.x, opts.y, opts.width, opts.height, opts.radius, 
-        opts.fill_color, opts.stroke_color)
-      add_text_with_bottom_border(opts.heading, opts.x, opts.y,
-        opts.width, opts.font_size) if opts.heading
-      pdf_writer.restore_state
-
-      start_position = opts.heading ? opts.y - 20 : opts.y
-      draw_text(text, :y              => start_position,
-                      :left           => opts.x,
-                      :right          => opts.x + opts.width,
-                      :justification  => opts.justification || :center,
-                      :font_size      => opts.font_size)
-      move_cursor_to(opts.y - opts.height)
-    end
-
-    # Adds n to pdf_writer.y, moving the vertical drawing position in the
-    # document.
-    def move_cursor(n) 
-      pdf_writer.y += n
-    end
-    
-    # Moves the cursor to a specific y coordinate in the document.
-    def move_cursor_to(n)
-      pdf_writer.y = n
-    end
-
-    # Moves the vertical drawing position in the document upwards by n.
-    def move_up(n)
-      pdf_writer.y += n
-    end
-
-    def move_down(n)
-      pdf_writer.y -= n
-    end
-    
-    # Adds a specified amount of whitespace above and below the code
-    # in your block.  For example, if you want to surround the top and
-    # bottom of a line of text with 5 pixels of whitespace:
-    #
-    #    pad(5) { add_text "This will be padded top and bottom" }
-    def pad(y,&block)
-      move_cursor(-y)
-      block.call
-      move_cursor(-y)
-    end
-    
-    # Adds a specified amount of whitespace above the code in your block.  
-    # For example, if you want to add a 10 pixel buffer to the top of a
-    # line of text:
-    #
-    #    pad_top(10) { add_text "This will be padded on top" }
-    def pad_top(y,&block)
-      move_cursor(-y)
-      block.call
-    end
-    
-    # Adds a specified amount of whitespace below the code in your block.  
-    # For example, if you want to add a 10 pixel buffer to the bottom of a
-    # line of text:
-    #
-    #    pad_bottom(10) { add_text "This will be padded on bottom" }
-    def pad_bottom(y,&block)
-      block.call
-      move_cursor(-y)
-    end
-    
-    # Draws a PDF::SimpleTable using the given data (usually a Data::Table).
-    # Takes all the options you can set on a PDF::SimpleTable object,
-    # see the PDF::Writer API docs for details, or check our quick reference
-    # at: 
-    # 
-    # http://stonecode.svnrepository.com/ruport/trac.cgi/wiki/PdfWriterQuickRef
-    def draw_table(table_data, format_opts={})
-      m = "PDF Formatter requires column_names to be defined"
-      raise FormatterError, m if table_data.column_names.empty?
-      
-      table_data.rename_columns { |c| c.to_s } 
-            
-      if options.table_format
-        format_opts =
-          Marshal.load(Marshal.dump(options.table_format.merge(format_opts))) 
-      end  
-        
-      old = pdf_writer.font_size
-      
-      ::PDF::SimpleTable.new do |table|          
-        table.maximum_width = 500
-        table.column_order  = table_data.column_names
-        table.data = table_data
-        table.data = [{}] if table.data.empty?                                                 
-        apply_pdf_table_column_opts(table,table_data,format_opts)
-
-        format_opts.each {|k,v| table.send("#{k}=", v) }  
-        table.render_on(pdf_writer)
-      end                                              
-      
-      pdf_writer.font_size = old
-    end
-        
-    # This module provides tools to simplify some common drawing operations.
-    # It is included by default in the PDF formatter.
-    #
-    module DrawingHelpers
-      
-      # Draws a horizontal line from x1 to x2
-      def horizontal_line(x1,x2)
-        pdf_writer.line(x1,cursor,x2,cursor)
-        pdf_writer.stroke
-      end 
-      
-      # Draws a horizontal line from left_boundary to right_boundary
-      def horizontal_rule
-        horizontal_line(left_boundary,right_boundary)                                            
-      end                                            
-      
-      alias_method :hr, :horizontal_rule
-                    
-      # Draws a vertical line at x from y1 to y2
-      def vertical_line_at(x,y1,y2)
-        pdf_writer.line(x,y1,x,y2)
-        pdf_writer.stroke 
-      end
-    
-      # Alias for PDF::Writer#absolute_left_margin
-      def left_boundary
-        pdf_writer.absolute_left_margin
-      end
-      
-      # Alias for PDF::Writer#absolute_right_margin
-      def right_boundary
-        pdf_writer.absolute_right_margin
-      end
-      
-      # Alias for PDF::Writer#absolute_top_margin
-      def top_boundary
-        pdf_writer.absolute_top_margin
-      end
-      
-      # Alias for PDF::Writer#absolute_bottom_margin
-      def bottom_boundary
-        pdf_writer.absolute_bottom_margin
-      end
-      
-      # Alias for PDF::Writer#y
-      def cursor
-        pdf_writer.y
-      end
-      
-      # Draws text at an absolute location, defined by
-      # :y, :x1|:left, :x2|:right
-      # 
-      # All options to add_text are also supported.
-      def draw_text(text,text_opts)
-        ypos = cursor
-        move_cursor_to(text_opts[:y]) if text_opts[:y]
-        add_text(text,
-          text_opts.merge(:absolute_left => text_opts[:x1] || text_opts[:left],
-          :absolute_right => text_opts[:x2] || text_opts[:right]))
-        move_cursor_to(ypos)
-      end
-      
-      # Draws text at an absolute location, defined by
-      # :y, :x1|:left
-      #
-      # The x position defaults to the left margin and the
-      # y position defaults to the current cursor location.
-      # 
-      # Uses PDF::Writer#add_text, so it will ignore any options not supported
-      # by that method.
-      def draw_text!(text,text_opts)
-        ypos = cursor
-        pdf_writer.add_text(text_opts[:x1] || text_opts[:left] || left_boundary,
-          text_opts[:y] || ypos,
-          text,
-          text_opts[:font_size],
-          text_opts[:angle] || 0)
-        move_cursor_to(ypos)
-      end   
-      
-      def finalize
-        render_pdf
-      end
-    end   
-
-    include DrawingHelpers
-    
-    private
-    
-    def apply_pdf_table_column_opts(table,table_data,format_opts)
-      column_opts = format_opts.delete(:column_options)
-
-      if column_opts
-        heading_opts = column_opts.delete(:heading)
-        if column_opts[:justification]
-          heading_opts ||= {}
-          heading_opts = {
-            :justification => column_opts[:justification]
-          }.merge(heading_opts)
-        end
-        specific = get_specific_column_options(table_data.column_names,
-                                               column_opts)
-        columns = table_data.column_names.inject({}) { |s,c|
-          s.merge( c => ::PDF::SimpleTable::Column.new(c) { |col|
-            col.heading = create_heading(heading_opts) 
-            column_opts.each { |k,v| col.send("#{k}=",v) }
-            # use the specific column names now
-            specific[c].each { |k,v| col.send("#{k}=",v) }
-          })
-        }
-        table.columns = columns
-      end
-    end
-
-    def get_specific_column_options(column_names,column_opts)
-      column_names.inject({}) do |s,c|
-        opts = column_opts.delete(c) || {}
-        if opts[:heading]
-          opts = opts.merge(:heading => create_heading(opts[:heading]))
-        end
-        s.merge(c => opts)
-      end
-    end
-    
-    def create_heading(heading_opts)
-      heading_opts ||= {}
-      ::PDF::SimpleTable::Column::Heading.new {|head|
-        heading_opts.each {|k,v| head.send("#{k}=",v) }
-      }
-    end
-    
-    def grouping_columns
-      data.data.to_a[0][1].column_names.dup.unshift(data.grouped_by)
-    end
-    
-    def table_with_grouped_by_column
-      Ruport::Data::Table.new(:column_names => grouping_columns)
-    end
-    
-    def render_justified_or_separated_grouping
-      table = table_with_grouped_by_column
-      data.each do |name,group|
-        group.each_with_index do |r,i|
-          if i == 0
-            table << { data.grouped_by => "<b>#{name}</b>" }.merge(r.to_hash)
-          else
-            table << r
-          end
-        end
-        table << [" "] if options.style == :separated
-      end
-      render_table table, options.to_hash.merge(:formatter => pdf_writer)
-    end
-    
-    def render_offset_grouping
-      table = table_with_grouped_by_column
-      data.each do |name,group|
-        table << ["<b>#{name}</b>"]
-        group.each {|r| table << r }
-      end
-      render_table table, options.to_hash.merge(:formatter => pdf_writer)
-    end
-    
-    def image_fits_in_box?(img_width,box_width,img_height,box_height)
-      !(img_width > box_width || img_height > box_height)
-    end
-    
-    def fit_image_in_box(img_width,box_width,img_height,box_height)
-      img_ratio = img_height.to_f / img_width.to_f
-      until image_fits_in_box?(img_width,box_width,img_height,box_height)
-        img_width -= 1
-        img_height = img_width * img_ratio
-      end
-      return img_width, img_height
-    end
-
-    def add_white_space(x,y,img_width,box_width,img_height,box_height)
-      if img_width < box_width
-        white_space = box_width - img_width
-        x = x + (white_space / 2)
-      end
-      if img_height < box_height
-        white_space = box_height - img_height
-        y = y + (white_space / 2)
-      end
-      return x, y
-    end
-    
-    def resize_text_to_box(text,opts)
-      loop do
-        sz = pdf_writer.text_width(text, opts.font_size)
-        opts.x + sz > opts.x + opts.width or break
-        opts.font_size -= 1
-      end
-    end
-    
-    def draw_box(x,y,width,height,radius,fill_color=nil,stroke_color=nil)
-      pdf_writer.fill_color(fill_color || Color::RGB::White)
-      pdf_writer.stroke_color(stroke_color || Color::RGB::Black)
-      pdf_writer.rounded_rectangle(x, y, width, height, radius).fill_stroke
-    end
-    
-    def add_text_with_bottom_border(text,x,y,width,font_size)
-      pdf_writer.line( x, y - 20, 
-                       x + width, y - 20).stroke
-      pdf_writer.fill_color(Color::RGB::Black)
-      move_cursor_to(y - 3)
-      add_text("<b>#{text}</b>",
-        :absolute_left => x, :absolute_right => x + width,
-        :justification => :center, :font_size => font_size)
-    end
-    
-    def apply_page_format_template(t)
-      t = (t || {}).merge(options.page_format || {})
-      options.paper_size ||= t[:size]
-      options.paper_orientation ||= t[:layout]
-    end
-    
-    def apply_text_format_template(t)
-      t = (t || {}).merge(options.text_format || {})
-      options.text_format = t unless t.empty?
-    end
-
-    def apply_table_format_template(t)
-      t = (t || {}).merge(options.table_format || {})
-      options.table_format = t unless t.empty?
-    end
-    
-    def apply_column_format_template(t)
-      t = (t || {}).merge(options.column_format || {})
-      column_opts = {}
-      column_opts.merge!(:justification => t[:alignment]) if t[:alignment]
-      column_opts.merge!(:width => t[:width]) if t[:width]
-      unless column_opts.empty?
-        if options.table_format
-          if options.table_format[:column_options]
-            options.table_format[:column_options] =
-              column_opts.merge(options.table_format[:column_options])
-          else
-            options.table_format.merge!(:column_options => column_opts)
-          end
-        else
-          options.table_format = { :column_options => column_opts }
-        end
-      end
-    end
-    
-    def apply_heading_format_template(t)
-      t = (t || {}).merge(options.heading_format || {})
-      heading_opts = {}
-      heading_opts.merge!(:justification => t[:alignment]) if t[:alignment]
-      heading_opts.merge!(:bold => t[:bold]) unless t[:bold].nil?
-      heading_opts.merge!(:title => t[:title]) if t[:title]
-      unless heading_opts.empty?
-        if options.table_format
-          if options.table_format[:column_options]
-            if options.table_format[:column_options][:heading]
-              options.table_format[:column_options][:heading] =
-                heading_opts.merge(
-                  options.table_format[:column_options][:heading]
-                )
-            else
-              options.table_format[:column_options].merge!(
-                :heading => heading_opts
-              )
-            end
-          else
-            options.table_format.merge!(
-              :column_options => { :heading => heading_opts }
-            )
-          end
-        else
-          options.table_format = {
-            :column_options => { :heading => heading_opts }
-          }
-        end
-      end
-    end
-    
-    def apply_grouping_format_template(t)
-      t = (t || {}).merge(options.grouping_format || {})
-      options.style ||= t[:style]
-    end
-  end
-end