make_exportable 1.0.0

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+gem 'rails'
+
+group :development do
+  gem 'jeweler'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'sqlite3-ruby', :require => 'sqlite3'
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Nova Fabrica, Inc.
+
+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.rdoc

@@ -0,0 +1,187 @@
+=MakeExportable
+
+MakeExportable is a Rails gem/plugin to assist in exporting application data in a variety of formats. Filter and limit the data exported using ActiveRecord. Export returned values from instance methods as easily as database columns.
+
+
+==Supported Formats 
+
+* CSV: Comma-separated values
+* TSV: Tab-separated values
+* XLS: Excel Spreadsheet
+* JSON: JavaScript Object Notation
+* XML: Extensible markup language
+* HTML: Hypertext markup language
+	
+	
+==Installation
+  
+* gem - sudo gem install make_exportable
+* plugin - script/plugin install git@github.com:novafabrica/make_exportable.git
+
+
+==Basic Usage
+
+To start using MakeExportable simply add a call to <em>make_exportable</em> in any class you want to use for exporting data.
+
+  class Customer < ActiveRecord::Base
+    make_exportable 
+  end
+
+To export data you simply call the class method <em>to_export</em> and specify your desired format (see supported formats above).
+
+  Customer.to_export("csv")
+
+You can select the columns you want to return using the :only and :except options.  The default is to export all columns.
+
+  Customer.to_export("csv", :only => [:first_name, :last_name, :email])
+  Customer.to_export("csv", :except => [:hashed_password, :salt])
+  
+You can change the result set by passing in an array of :scopes to call, you can pass in finder options (such as :conditions, :order, :limit, :offset, etc.), or you can call <em>to_export</em> on a class that has already been scoped using named scopes.
+
+  Customer.to_export(:xls, :scopes => ["approved", "sorted"])
+  Customer.to_export(:xls, :conditions => {:approved => true}, :order => "first_name ASC", :limit => 50)
+  Customer.visible.where(:approved => true).to_export(:xls)
+
+<em>to_export</em> returns an array of the data in the specified format and the corresponding mime-type.  This is done to make sending files easy.
+
+  ["First Name,Last Name,Email\nJohn,Doe,x@x.com\nJoe,Smith,y@y.com\n", "text/csv; charset=utf-8; header=present"]
+
+Then in a controller, you can use the <em>send_data</em> method to send the export as a downloadable file to the user's browser.
+
+  class CustomerController < ApplicationController
+
+    def export
+      # Export the data
+      options = {:only => [:first_name, :last_name, :city, :country, :email]}
+      export_data, data_type = Customer.visible.to_export('csv', options)
+
+      # Send data to user as file
+      send_data(export_data, { :type => data_type, :disposition => 'attachment', :filename => "customer_export.csv" })
+    end
+
+  end
+
+
+==Attributes and Methods
+
+MakeExportable doesn't just export attributes that have database columns. It can also export data returned from methods.
+
+  class Customer < ActiveRecord::Base
+    make_exportable 
+    
+    def full_name
+      "#{first_name} #{last_name}"
+    end
+    
+    def last_purchase
+      last_order = orders.order('created_at ASC').last
+      return last_order ? last_order.created_at : ''
+    end
+  end
+
+  Customer.to_export("csv", :only => [:full_name, :email, :last_purchase])
+
+If you want an attribute to be handled differently whenever it is exported, you can define a method with the syntax <em>#{attribute}_export</em> which will be called when exporting instead of the regular attribute.
+
+  class Customer < ActiveRecord::Base
+    make_exportable 
+
+    def visible_export
+      visible ? 'Visible' : 'Not Visible'
+    end
+    
+    def updated_at_export
+      updated_at.to_s(:long)
+    end
+  end
+
+
+==Setting Export Defaults
+
+If you have a general columns, scopes, and conditions you will be calling in multiple methods you can attach them to the <em>make_exportable</em> method as defaults when including it into your class.
+
+* :only and :except - specify columns or methods to export (defaults to all columns)
+* :as - specify formats to allow for exporting (defaults to all formats)
+* :scopes - specify scopes to be called on the class before exporting
+
+These are defaults which can still be overridden when you perform an export.
+
+  class Customer < ActiveRecord::Base
+    make_exportable :as => [:csv, :tsv], :only => [:first_name, :last_name, :email], :scopes => ['visible', 'recent']
+  end
+
+  class User < ActiveRecord::Base
+    make_exportable :except => [:hashed_password, :salt]
+  end
+
+
+==Magic Methods
+
+MakeExportable also allows you to export to a format using a dynamic name.  Each export format gets two "magic methods".
+
+  to_#{format}_export
+  create_#{format}_report
+
+In both cases "format" represents the lowercase abbreviation for the export format (e.g. "to_csv_export", "create_csv_report"). Then the options hash becomes the first argument instead of the second.
+
+  Customer.to_csv_export(:conditions => {:visible => true}, :order => "last_name ASC")
+  Customer.visible.to_csv_export(:only => [:username, :email])
+
+
+==Reports From Other Data
+
+If you just have some data you want to export in the right format, MakeExportable exposes the <em>create_report</em> method to use your own data set.
+
+  Customer.create_report("csv", [row1_array, row2_array, row3_array], {:headers => headers_array})
+
+Just pass in the format and an ordered array of rows for the data set.  You can also pass in an array of headers as :headers in the options hash.  Remember the row size and the header size need to be the same. 
+
+
+==Which Classes and Formats Can Be Exported
+
+MakeExportable keeps a hash of classes that have been enabled as being exportable. The keys of this hash provide an easy reference if you need to know which classes are supported.  You can also query a class directly using <em>exportable?</em>.
+
+  MakeExportable.exportable_classes
+  # => {"Customer" => Customer, "Product" => Product, "Order" => Order}
+  MakeExportable.exportable_classes.keys
+  # => ["Customer", "Product", "Order"]
+  MakeExportable.exportable_classes.include?("Customer")
+  # => true
+  Customer.exportable?
+  # => true
+  LineItem.exportable?
+  # => false
+
+Note that this list will only include classes which have been loaded.  In production mode that will be all classes, but development mode lazy-loads classes as they are needed.  If you need a full list, you can ask Rails to load all classes so they will all "register" themselves with MakeExportable.
+
+  if Rails.env == 'development'
+    Rails::Initializer.run(:load_application_classes)
+  end
+
+MakeExportable also maintains a hash of the available export formats.  The keys of this hash are an array of symbols for all supported formats.
+
+  MakeExportable.exportable_formats
+  # => { :csv => MakeExportable::CSV, :xls => MakeExportable::Excel, :html => MakeExportable::HTML, :json => MakeExportable::JSON, :tsv => MakeExportable::TSV, :xml => MakeExportable::XML }
+  MakeExportable.exportable_formats.keys
+  # => [:csv, :xls, :html, :json, :tsv, :xml]
+
+
+==Info
+  
+Author: Kevin Skoglund & Matthew Bergman, Nova Fabrica, Inc.
+
+License: Copyright 2010 by Kevin Skoglund. released under the attached MIT-LICENSE. 
+
+GitHub: http://github.com/novafabrica/make_exportable/tree/master
+
+
+==Bug Reports and Feedback
+
+Bug reports should be submitted at https://github.com/novafabrica/make_exportable/issues
+
+Other feedback is welcomed at info@novafabrica.com
+
+
+==Warranty
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

data/Rakefile

@@ -0,0 +1,50 @@
+begin
+  # Rspec 1.3.0
+  require 'spec/rake/spectask'
+  desc 'Default: run specs'
+  task :default => :spec
+  Spec::Rake::SpecTask.new do |t|
+    t.spec_files = FileList["spec/**/*_spec.rb"]
+  end
+
+  Spec::Rake::SpecTask.new('rcov') do |t|
+    t.spec_files = FileList["spec/**/*_spec.rb"]
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+  
+rescue LoadError
+  # Rspec 2.0
+  require 'rspec/core/rake_task'
+
+  desc 'Default: run specs'
+  task :default => :spec  
+  Rspec::Core::RakeTask.new do |t|
+    t.pattern = "spec/**/*_spec.rb"
+  end
+  
+  Rspec::Core::RakeTask.new('rcov') do |t|
+    t.pattern = "spec/**/*_spec.rb"
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+
+rescue LoadError
+  puts "Rspec not available. Install it with: gem install rspec"  
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "make_exportable"
+    gemspec.summary = "Makes any Rails model easily exportable"
+    gemspec.description = "MakeExportable is a Rails gem/plugin to assist in exporting application data as CSV, TSV, JSON, HTML, XML or Excel. Filter and limit the data exported using ActiveRecord. Export returned values from instance methods as easily as database columns."
+    gemspec.email = "kevin@novafabrica.com"
+    gemspec.homepage = "http://github.com/novafabrica/make_exportable"
+    gemspec.authors = ["Kevin Skoglund", "Matthew Bergman"]
+    gemspec.files =  FileList["[A-Z]*", "{generators,lib,spec,rails}/**/*"] - FileList["**/*.log"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/make_exportable.rb

@@ -0,0 +1,19 @@
+require "active_record"
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'make_exportable'))
+
+require 'core'
+require 'errors'
+require 'exportable_format'
+require 'make_exportable_helper'
+
+Dir.foreach(File.join(File.dirname(__FILE__), 'make_exportable', 'exportable_formats')) do |file|
+  next unless File.extname(file) == '.rb'
+  require File.join('exportable_formats', File.basename(file, '.rb'))
+end
+
+$LOAD_PATH.shift
+
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.send :include, MakeExportable
+end

data/lib/make_exportable/core.rb

@@ -0,0 +1,309 @@
+module MakeExportable #:nodoc:
+
+  # Inventory of the exportable classes
+  mattr_accessor :exportable_classes
+  @@exportable_classes = {}
+
+  # Inventory of the exportable formats
+  mattr_accessor :exportable_formats
+  @@exportable_formats = {}
+
+  def self.included(target)
+    target.extend(ActiveRecordBaseMethods)
+  end
+
+  module ActiveRecordBaseMethods
+
+    # <tt>exportable?</tt> returns false for all ActiveRecord classes
+    # until <tt>make_exportable</tt> has been called on them.
+    def exportable?(format=nil)
+      return false
+    end
+
+    protected
+
+    # <tt>make_exportable</tt> is an ActiveRecord method that, when called, add 
+    # methods to a particular class to make exporting data from that class easier.
+    #
+    # Example:
+    #
+    #   class Customer < ActiveRecord::Base
+    #     make_exportable
+    #   end
+    #   Customer.to_export(:csv)
+    #
+    # An optional hash of options can be passed as an argument to establish the default 
+    # export parameters.
+    #
+    # These options include:
+    # * :only and :except - specify columns or methods to export (defaults to all columns)
+    # * :as - specify formats to allow for exporting (defaults to all formats)
+    # * :scopes - specify scopes to be called on the class before exporting
+    # * find options - for Rails 2.3 and earlier compatibility, standard find options 
+    #     are supported (:conditions, :order, :limit, :offset, etc.). These will be deprecated 
+    #     and removed in future versions.
+    #
+    # Examples:
+    #
+    #   class Customer < ActiveRecord::Base
+    #     make_exportable :only => [:id, :username, :full_name]
+    #   end
+    #
+    #   class Customer < ActiveRecord::Base
+    #     make_exportable :except => [:id, :password], :scopes => [:new_signups, :with_referals], 
+    #                     :as => [:csv, :tsv, :xls]
+    #   end
+    #
+    #   class Customer < ActiveRecord::Base
+    #     make_exportable :conditions => {:active => true}, :order => 'last_name ASC, first_name ASC',
+    #                     :as => [:json, :html, :xml]
+    #   end
+    #
+    def make_exportable(options={})
+      # register the class as exportable
+      MakeExportable.exportable_classes[self.class_name] = self
+
+      # remove any invalid options
+      valid_options = [:as, :only, :except, :scopes, :conditions, :order, :include,
+                       :group, :having, :limit, :offset, :joins]
+      options.slice!(*valid_options)
+
+      # Determine the exportable formats, default to all registered formats
+      options[:formats] = MakeExportable.exportable_formats.keys
+      if format_options = options.delete(:as)
+        options[:formats] = options[:formats] & Array.wrap(format_options).map(&:to_sym)
+      end
+      # Handle case when :as option was sent, but with no valid formats
+      if options[:formats].blank?
+        valid_formats = MakeExportable.exportable_formats.keys.map {|f| ":#{f}"}
+        raise MakeExportable::FormatNotFound.new("No valid export formats. Use: #{valid_formats.join(', ')}") 
+      end
+
+      # Determine the exportable columns, default to all columns and then
+      # remove columns using the :only and :except options
+      options[:columns] = column_names.map(&:to_sym)
+      if only_options = options.delete(:only)
+        options[:columns] = Array.wrap(only_options).map(&:to_sym)
+      end
+      if except_options = options.delete(:except)
+        options[:columns] = options[:columns] - Array.wrap(except_options).map(&:to_sym)
+      end
+
+      options[:scopes] ||= []
+
+      # exportable options will be :formats, :columns, :scopes & find options
+      write_inheritable_attribute :exportable_options, options
+      class_inheritable_reader :exportable_options
+
+      extend MakeExportable::ClassMethods
+      include MakeExportable::InstanceMethods
+
+    end
+
+  end
+
+  module ClassMethods
+
+    # <tt>exportable?<?tt> returns true if the class has called "make_exportable".
+    # This is overriding the default :exportable? in ActiveRecord::Base which 
+    # always returns false.
+    # If a format is passed as an argument, returns true only if the format is 
+    # allowed for this class.
+    def exportable?(format=nil)
+      return exportable_options[:formats].include?(format.to_sym) if format
+      return true
+    end
+
+    # <tt>to_export</tt> exports records from a class. It can be called 
+    # directly on an ActiveRecord class, but it can also be called on an ActiveRelation scope.
+    # It takes two arguments: a format (required) and a hash of options (optional).
+    #
+    # The options include:
+    # * :only and :except - specify columns or methods to export
+    # * :scopes - specify scopes to be called on the class before exporting
+    # * find options - for Rails 2.3 and earlier compatibility, standard find options 
+    #     are supported (:conditions, :order, :limit, :offset, etc.). These will be deprecated 
+    #     and removed in future versions.
+    # * :headers - supply an array of custom headers for the columns of exported attributes, 
+    #     the sizes of the header array and the exported columns must be equal.
+    #   
+    # Examples:
+    #
+    #   User.to_export(:xml, :only => [:first_name, :last_name, :username], 
+    #      :order => 'users.last_name ASC')
+    #
+    #   User.visible.sorted_by_username.to_export('csv', 
+    #      :only => [:first_name, :last_name, :username])
+    #
+    def to_export(format, options={})
+      export_data = get_export_data(options)
+      # remove the auto-headers from the export_data (i.e. the first row)
+      auto_headers = export_data.shift
+      # Use auto-headers unless given alternates or false (use no headers)
+      options[:headers] = auto_headers unless !options[:headers].blank? || options[:headers] === false
+      export_string = create_report(format, export_data, :headers => options[:headers])
+      return export_string
+    end
+    
+    # <tt>get_export_data</tt> finds records for export using a combination of the default 
+    # export options and the argument options, and returns an array of arrays representing 
+    # the rows and columns of the export data. The first item ("row") in the array will be 
+    # an array of strings to be used as column headers.
+    # Valid options include :only, :except, :scopes and the standard find options. 
+    # See <tt>to_export</tt> for more details on the options.
+    #
+    # Example:
+    # 
+    #   User.get_export_data(:only => [:first_name, :last_name, :username])
+    #   # => [['first_name', 'last_name', 'username'], ['John', 'Doe', 'johndoe'], ['Joe', 'Smith', 'jsmith']] }
+    #
+    def get_export_data(options={})
+      column_options = options.slice(:only, :except)
+      records     = find_export_data(options)
+      export_data = map_export_data(records, column_options)
+      return export_data
+    end
+
+    # <tt>create_report</tt> creates a report from a set of data. It takes three arguments: 
+    # a format, the data set to use for the report, and an optional hash of options. 
+    # The only meaningful option is :headers which sets the strings to be used as column 
+    # headers for the data set. The value of :headers can be:
+    # * true - headers are the first row in the data set
+    # * false - headers are not in the data set and should not be added
+    # * array of strings to use for the column headers
+    # 
+    # The length of the headers must match the length of each row in the data set.
+    def create_report(format, data_set, options={})
+      if options[:headers] === true
+        options[:headers] = data_set.shift
+      end
+      
+      validate_export_format(format)
+      validate_export_data_lengths(data_set, options[:headers])
+      
+      format_class = MakeExportable.exportable_formats[format.to_sym]
+      formater = format_class.new(data_set, options[:headers])
+      return formater.generate, formater.mime_type
+    end
+
+    private
+
+      # <tt>method_missing</tt> allows the class to accept dynamically named methods 
+      # such as: SomeClass.to_xls_export(), SomeClass.create_csv_report()
+      def method_missing(method_id, *arguments)
+        possible_formats = MakeExportable.exportable_formats.keys.map(&:to_s).join('|')
+        if match = /^create_(#{possible_formats})_report$/.match(method_id.to_s)
+          format = match.captures.first
+          self.create_report(format, *arguments)
+        elsif match = /^to_(#{possible_formats})_export$/.match(method_id.to_s)
+          format = match.captures.first
+          self.to_export(format, *arguments)
+        else
+          super
+        end
+      end
+
+      # <tt>find_export_data</tt> finds all objects of a given
+      # class using a combination of the default export options and the options passed in.
+      # Valid options include :scopes and the standard find options. It returns a collection of 
+      # objects matching the find criteria.
+      # See <tt>to_export</tt> for more details on the options.
+      def find_export_data(options={})
+        
+        # merge with defaults then pull out the supported find and scope options
+        merged_options = options.reverse_merge(exportable_options)
+        find_options  = merged_options.slice(:conditions, :order, :include, :group, :having, :limit, :offset, :joins)
+        scope_options = merged_options.slice(:scopes)
+
+        # apply scopes and then find options
+        collection = self
+        scope_options[:scopes].each do |scope|
+          collection = collection.send(scope)
+        end
+        # For Rails 2.3 compatibility
+        if ActiveRecord::VERSION::MAJOR < 3
+          collection = collection.find(:all, find_options)
+        else
+          # they should not be sending find options anymore, so we don't support them
+          collection = collection.all
+        end
+        return collection
+      end
+
+      # <tt>map_export_data</tt> takes a collection and outputs an array of arrays representing 
+      # the rows and columns of the export data. The first item ("row") in the array will be 
+      # an array of strings to be used as column headers.
+      # Valid options include :only and :except.
+      # See <tt>to_export</tt> for more details on the options.
+      # 
+      #   User.map_export_data(User.visible, :only => [:first_name, :last_name, :username])
+      #   # => [['first_name', 'last_name', 'username'], ['John', 'Doe', 'johndoe'], ...]
+      #
+      def map_export_data(collection, options={})
+        # Use :only and :except options or else use class defaults for columns.
+        if !options[:only].blank?
+          options[:columns] = Array.wrap(options[:only]).map(&:to_sym)
+        elsif !options[:except].blank?
+          options[:columns] = column_names.map(&:to_sym) - Array.wrap(options[:except]).map(&:to_sym)
+        else
+          options[:columns] = exportable_options[:columns]
+        end
+        if options[:columns].empty?
+          raise MakeExportable::ExportFault.new("You are not exporting anything")
+        end
+        # TODO: Go ahead and humanize/titleize the column names here
+        headers = options[:columns].map(&:to_s)
+        rows = collection.map do |item|
+          options[:columns].map {|col| item.export_attribute(col) }
+        end
+        return rows.unshift(headers)
+      end
+
+      # <tt>validate_export_format</tt> ensures that the requested export format is valid.
+      def validate_export_format(format)
+        unless MakeExportable.exportable_formats.keys.include?(format.to_sym)
+          raise MakeExportable::FormatNotFound.new("#{format} is not a supported format.")
+        end
+        unless exportable_options[:formats].include?(format.to_sym)
+          raise MakeExportable::FormatNotFound.new("#{format} format is not allowed on this class.")
+        end
+      end
+
+      # <tt>validate_export_data_lengths</tt> ensures that the headers and all data rows are of the 
+      # same size. (This is an important data integrity check if you are using NoSQL.)
+      def validate_export_data_lengths(data_set, data_headers=nil)
+        row_length = !data_headers.blank? ? data_headers.size : data_set[0].size
+        if data_set.any? {|row| row_length != row.size }
+          raise MakeExportable::ExportFault.new("Headers and all rows in the data set must be the same size.")
+        end
+      end
+
+  end
+
+  module InstanceMethods
+
+    # <tt>export_attribute</tt> returns the export value of an attribute or method.
+    # By default, this is simply the value of the attribute or method itself, 
+    # but the value can be permanently overridden with another value by defining 
+    # a method called "#{attribute}_export". The alternate method will *always* 
+    # be called in place of the original one. At a minimum, this is useful 
+    # when a date should be formatted when exporting or when booleans should  
+    # always export as "Yes"/"No".  But it can do more, performing any amount of 
+    # processing or additional queries, as long as in the end it returns a value 
+    # for the export to use.
+    # Sending an attribute name that does not exist will return an empty string.
+    def export_attribute(attribute)
+      begin
+        if self.respond_to?("#{attribute}_export")
+          return self.send("#{attribute}_export").to_s
+        else
+          return self.send(attribute).to_s
+        end
+      rescue
+        return ""
+      end
+    end
+
+  end
+
+end