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 [email protected]:novafabrica/make_exportable.git

Basic Usage

To start using MakeExportable simply add a call to make_exportable 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 to_export 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 to_export 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)

to_export 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,[email protected]\nJoe,Smith,[email protected]\n", "text/csv; charset=utf-8; header=present"]

Then in a controller, you can use the send_data 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 #attribute_export 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 make_exportable 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 create_report 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 exportable?.

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.

GitHub: github.com/novafabrica/make_exportable/tree/master

Bug Reports and Feedback

Bug reports should be submitted at github.com/novafabrica/make_exportable/issues

Other feedback is welcomed at [email protected]

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.