make_exportable

=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 [e-mail]: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,[e-mail]\nJoe,Smith,[e-mail]\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.

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 [e-mail]

==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.