Rails Admin Import
Plugin functionality to add generic import to Rails Admin from CSV and JSON files
This Readme is for version 1.0. If you are still using version 0.1.x, see this branch
- First, add to Gemfile:
gem "rails_admin_import", "~> 1.0.0"
- Define configuration in
RailsAdmin.config do |config| # REQUIRED: # Include the import action # See https://github.com/sferik/rails_admin/wiki/Actions config.actions do all import end # Optional: # Configure global RailsAdminImport options config.configure_with(:import) do |config| config.logging = true end # Optional: # Configure model-specific options using standard RailsAdmin DSL # See https://github.com/sferik/rails_admin/wiki/Railsadmin-DSL config.model 'User' do import do include_all_fields exclude_fields :secret_token end end end
- If you are using CanCanCan for authorization, add to ability.rb to specify which models can be imported:
can :import, [User, Model1, Model2]
The first line must contain attribute names. They will be converted to lowercase and underscored (First Name ==> first_name).
For "many" associations, you may include multiple columns with the same header in the CSV file.
The repeated header may be singular or plural. For example, for a "children" association, you may have multiple "child" columns or multiple "children" column, each containing one lookup value for an associated record. Blank values are ignored.
First name,Last name,Team,Team Peter,Gibbons,IT,Management Michael,Bolton,IT,
The file must be an array or an object with a root key the same name as the plural model name, i.e. the default Rails JSON output format with include_root_in_json on or off.
Global configuration options
false): Save a copy of each imported file to log/import and a detailed import log to log/rails_admin_import.log
1000): max number of items that can be imported at one time. TODO: Currently this is suggested but not enforced.
false): import records in a transaction and rollback if there is one error. Only for ActiveRecord, not Mongoid.
nil): a lambda to convert each CSV header text string to a model attribute name. The default header converter converts to lowercase and replaces spaces with underscores.
Use standard RailsAdmin DSL to add or remove fields.
- To change the default attribute that will be used to find associations on import, set
mapping_key(default attribute is
RailsAdmin.config do |config| config.model 'Ball' do import do mapping_key :color end end end
- To include a specific list of fields:
RailsAdmin.config do |config| config.model 'User' do import do field :first_name field :last_name field :email end end end
- To exclude specific fields:
RailsAdmin.config do |config| config.model 'User' do import do include_all_fields exclude_fields :secret_token end end end
- To add extra fields that will be set as attributes on the model and that will be passed to the import hook methods:
RailsAdmin.config do |config| config.model 'User' do import do include_all_fields fields :special_import_token end end end
Define instance methods on your models to be hooked into the import process, if special/additional processing is required on the data:
# some model class User < ActiveRecord::Base def before_import_save(record) # Your custom special sauce end def after_import_save(record) # Your custom special sauce end end
For example, you could
Set an attribute on a Devise User model to skip checking for a password when importing a new model.
Download a file based on a URL from the import file and set a Paperclip file attribute on the model.
ORM: ActiveRecord and Mongoid
The gem is tested to work with ActiveRecord and Mongoid.
Support for Mongoid is early, so if you can suggest improvements (especially around importing embedded models), open an issue.
Move global config to
Move the field definitions to
config.model 'User' do; import do; // ...in
No need to mount RailsAdminImport in
config/routes.rb(RailsAdmin must still be mounted).
Update model import hooks to take 1 hash argument instead of 2 arrays with values and headers.
Support for importing file attributes was removed since I couldn't understand how it works. It should be possible to reimplement it yourself using post import hooks. Open an issue to discuss how to put back support for importing files into the gem.
Clone the repository to your machine
The structure of the tests is taken from the Rails Admin gem.
Original author: Steph Skardal
Maintainer (since May 2015): Julien Vanier
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
Copyright (c) 2015 End Point, Steph Skardal and contributors. See LICENSE.txt for further details.