Map Fields - A Rails plugin to ease the importing of CSV files
I've just released a plugin, map-fieilds, that eases the importing of CSV files.
When importing CSV files for a project, I wanted to add flexibility for the users so that they could import their CSV files in a looser format and then map their format to the format I needed.
map-fieilds will intercept calls to a method and show an intermediate screen where the user can map their columns to the expected columns.
How to install
sudo gem install map-fields
In your environment.rb file:
config.gem 'map-fields', :version => '~> 0.1.0', :lib => 'map_fields'
If you prefer, it can be installed as a plugin:
script/plugin install git://github.com/internuity/map-fields.git
Using it in your controller
lists_controller.rb:
class ListsController < AppliactionController
map_fields :create,
['Title', 'First name', 'Last name'],
:file_field => :file,
:params => [:list]
def index
@lists = List.find(:all)
end
def new
@list = List.new
end
def create
@list = List.new(params[:list])
if fields_mapped?
mapped_fields.each do |row|
@list.contact.create(:title => row[0],
:first_name => row[1],
:last_name => row[2])
end
flash[:notice] = 'Contact list created'
redirect_to :action => :index
else
render
end
rescue MapFields::InconsistentStateError
flash[:error] = 'Please try again'
redirect_to :action => :new
rescue MapFields::MissingFileContentsError
flash[:error] = 'Please upload a file'
redirect_to :action => :new
end
end
Explanation
Setup map-fields
Setup map-fields at the top of the controller.
map_fields accepts three parameters
- The first is the method to intercept, in this case :create
- The second is an array of expected CSV fields. The order of the fields in this array is the order they will be available in the row object when finally reading the CSV file.
- Lastly, a hash of options.
:file_field is the field that contains the import file. This is :file by default
:params is an array of parameters you want preserved. If you have a form based around a model, you just need to put the model name here and all the sub-fields will be preserved.
So, if you have a form with list[:name] etc, use :params => [:list]
Create your new view with a file field
You can now setup your new view as normal with an included file field
Handle the mapping in your create action
The create action now has to perform two functions, the mapping and then the final creating.
You can call the fields_mapped? method to see if the mapping has been performed and if not, render the mapping view.
There is a mapping partial which you can use so your view is as easy as:
#create.html.erb
<%= render :partial => 'map_fields/map_fields' %>
and it produces the following:
When the fields have been mapped, you can iterate through them with:
mapped_fields.each do |row|
# row.number returns the number of the row in the original CSV file
# row[0] is the first mapped field, in this case Title
# row[1] is the second mapped field, in this case First name
# row[2] is the third mapped field etc...
end
Two errors can be raised:
- MapFields::InconsistentStateError is raised when map-fields is unable to determine whether a file is being uploaded or mapped. It can be experienced through a combination of using the back button and refreshes but is seldom experienced.
- MapFields::MissingFileContentsError is raised when no file has been uploaded
Please feel free to ask any questions in the comments and raise issues on the GitHub page.
Comments
Have your say