Repository files navigation

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.

• CSV: Comma-separated values

• TSV: Tab-separated values

• XLS: Excel Spreadsheet

• JSON: JavaScript Object Notation

• XML: Extensible markup language

• HTML: Hypertext markup language

• gem - sudo gem install make_exportable

• plugin - script/plugin install git@github.com:novafabrica/make_exportable.git

To start using MakeExportable simply add a call tomake_exportable in any class you want to use for exporting data.

classCustomer<ActiveRecord::Basemake_exportableend

To export data you simply call the class methodto_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 callto_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,x@x.com\nJoe,Smith,y@y.com\n","text/csv; charset=utf-8; header=present"]

Then in a controller, you can use thesend_data method to send the export as a downloadable file to the user’s browser.

classCustomerController<ApplicationControllerdefexport# Export the dataoptions = {:only=> [:first_name,:last_name,:city,:country,:email]}export_data,data_type =Customer.visible.to_export('csv',options)# Send data to user as filesend_data(export_data, {:type=>data_type,:disposition=>'attachment',:filename=>"customer_export.csv" })endend

MakeExportable doesn’t just export attributes that have database columns. It can also export data returned from methods.

classCustomer<ActiveRecord::Basemake_exportabledeffull_name"#{first_name} #{last_name}"enddeflast_purchaselast_order =orders.order('created_at ASC').lastreturnlast_order?last_order.created_at:''endendCustomer.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.

classCustomer<ActiveRecord::Basemake_exportabledefvisible_exportvisible?'Visible':'Not Visible'enddefupdated_at_exportupdated_at.to_s(:long)endend

If you have a general columns, scopes, and conditions you will be calling in multiple methods you can attach them to themake_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.

classCustomer<ActiveRecord::Basemake_exportable:as=> [:csv,:tsv],:only=> [:first_name,:last_name,:email],:scopes=> ['visible','recent']endclassUser<ActiveRecord::Basemake_exportable:except=> [:hashed_password,:salt]end

MakeExportable also allows you to export to a format using a dynamic name. Each export format gets two “magic methods”.

to_#{format}_exportcreate_#{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])

If you just have some data you want to export in the right format, MakeExportable exposes thecreate_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.

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 usingexportable?.

MakeExportable.exportable_classes# => {"Customer" => Customer, "Product" => Product, "Order" => Order}MakeExportable.exportable_classes.keys# => ["Customer", "Product", "Order"]MakeExportable.exportable_classes.include?("Customer")# => trueCustomer.exportable?# => trueLineItem.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.

ifRails.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]

Author: Kevin Skoglund & Matthew Bergman, Nova Fabrica, Inc.

License: Copyright 2010 by Kevin Skoglund. released under the attached MIT-LICENSE.

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

Bug reports should be submitted atgithub.com/novafabrica/make_exportable/issues

Other feedback is welcomed at info@novafabrica.com

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.