rails_admin_import 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 433bf6ef9b6b129fe87eaefcf77c073074c525ee
-  data.tar.gz: 6aa3d4adba6761d8dd66fa2546013402484a97fd
+  metadata.gz: e8f4b64d5b102c3aaa1a7e40b526a4a44f7b1633
+  data.tar.gz: 188508962de1312370416f325deb729f7f3233e5
 SHA512:
-  metadata.gz: 848291b1ee4367e81937750690f228500d3e3f54d3832b4fea4c9e3261b7f80fe3d6c6540eec54c5d422fcb577f1ca2ed225b980403409f336b31c5f6e3ab634
-  data.tar.gz: 6967a8a96dcd8a63496341bf958700e862b6e2076ec82fd213bd72813e97051d0a48e44ca4eccd0ed790b5196414790504d00108ca7f1b89621b9b84d94fd812
+  metadata.gz: 95db49681fed111f535b241775b64cd7e302f10ade105473fc5e930c194f180dcdfdd6e82b93ee817438d74e97da33edcef91b5c9e0d109099678a43d1900874
+  data.tar.gz: 830926cf365344e76ac1fb5bec2a77b6ab85bf03f318253372f52e152a53fc08da97055a76d1bb599a41382fe0c9cc3175c2c8d892921c747b168617c1cf6f7d

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+# 1.4.0 / 2016-02-26
+
+- Implement row limit (default maximum is 1000 rows). Thanks @codealchemy!
+- Document mapping keys. Thanks @zrisher!
+- Ignore columns with blank headers in CSV files
+
 # 1.3.1 / 2016-02-11
 
 - Bugfix: Create log/import directory when logging config option is enabled. Thanks @yovasx2!

data/README.md

@@ -51,11 +51,93 @@ cannot :import, :all
 can :import, [User, Model1, Model2]
 ```
 
-## File format
+## Usage
+
+Model instances can be both created and updated from import data. Any fields
+can be imported as long as they are allowed by the model's configuration.
+Associated records can be looked up for both singular and plural relationships.
+Both updating existing records and associating records requires the use of
+**mapping keys**.
+
+### Mapping Keys
+
+Every importable class has a mapping key that uniquely identifies its
+instances. The value for this field can then be provided in import data, either
+to update the existing record or to attach it through an association to another
+model. This concept exists because `id`s are often not constant when moving
+records between data stores.
+
+For example, a `User` model may have an `email` field. When uploading a set
+of users where some already exist in our database, we can select "email" as
+our mapping key and then provide that field on each record in our data,
+allowing us to update existing records with matching emails.
+
+Using a csv formatted example:
+```
+Email,First name,Last name
+peter.gibbons@initech.com,Peter,Gibbons
+michael.bolton@initech.com,Michael,Bolton
+```
+would look for existing users with those emails. If one was found, its name
+fields would be updated. Otherwise, a new one would be created.
+
+Similarly, if each user has favorite books, we could set the mapping key
+for `Book` to be `isbn` and then include the isbn for their books within each
+user record. The syntax for this is to use the name of the associated model as
+the field name, no matter what actual mapping key has been selected. So
+a user record would have one or more fields named "Book" that include each
+associated book's ISBN.
+
+Again using a csv formatted example:
+```
+Email, Book, Book, Book
+peter.gibbons@initech.com, 9781119997870, 9780671027032
+michael.bolton@initech.com, 9780446677479
+```
+would look up books with those ISBNs and attach them to those users.
+
+Mapping keys can be selected on the import page. Their defaults can also be
+globally configured in the config file:
+
+```
+RailsAdmin.config do |config|
+  config.model 'User' do
+    import do
+      mapping_key :email
+    end
+  end
+end
+```
+
+Note that a matched record must exist when attaching associated models, or the
+ imported record will fail and be skipped.
+
+Complex associations (`has_one ..., :through` or polymorphic associations)
+need to be dealt with via custom logic called by one of the import hooks
+(see below for more detail on using hooks).  If we wanted to import
+`Service`s and attach them to a `User`, but the user relationship
+existed through an intermediary model called `ServiceProvider`, we could
+provide a `user_email` field in our records and handle the actual
+association with an import hook:
+
+```
+class Service < ActiveRecord::Base
+  belongs_to :service_provider
+  has_one :user, through: :service_provider
+
+  def before_import_save(record)
+    if (email = record[:user_email]) && (user = User.find_by_email(email))
+      self.service_provider = user.service_provider
+    end
+  end
+end
+```
+
+### File format
 
 The format is inferred by the extension (.csv, .json or .xlsx).
 
-### CSV
+#### CSV
 
 The first line must contain attribute names. They will be converted to lowercase and underscored (First Name ==> first_name).
 
@@ -71,11 +153,11 @@ Peter,Gibbons,IT,Management
 Michael,Bolton,IT,
 ```
 
-### JSON
+#### JSON
 
 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.
 
-### XLSX
+#### XLSX
 
 The Microsoft Excel XLM format (XLSX) is supported, but not the old binary Microsoft Excel format (XLS).
 
@@ -87,7 +169,7 @@ The expected rows and columns are the same as for the CSV format (first line con
 
 * __logging__ (default `false`): Save a copy of each imported file to log/import and a detailed import log to log/rails_admin_import.log
 
-* __line_item_limit__ (default `1000`): max number of items that can be imported at one time. TODO: Currently this is suggested but not enforced.
+* __line_item_limit__ (default `1000`): max number of items that can be imported at one time.
 
 * __rollback_on_error__ (default `false`): import records in a transaction and rollback if there is one error. Only for ActiveRecord, not Mongoid.
 
@@ -216,6 +298,10 @@ gem "rails_admin_import", "~> 1.2.0", require: "rails_admin_import/eager_load"
 * 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.
+ 
+## Community-contributed translations
+
+* [Spanish translation](https://gist.github.com/yovasx2/dc0e9512e6c6243f840c) by Giovanni Alberto
 
 ## Run tests
 

data/Rakefile

@@ -12,4 +12,6 @@ RSpec::Core::RakeTask.new(:spec)
 
 task test: :spec
 
-task default: :spec
+task :default do
+  system("bundle exec rake spec")
+end

data/config/locales/import.en.yml

@@ -34,6 +34,7 @@ en:
         create: "Failed to create %{name}: %{error}"
         update: "Failed to update %{name}: %{error}"
         general: "Error during import: %{error}"
+        line_item_limit: "Please limit upload file to %{limit} line items."
         old_import_hook: >
           The import hook %{model}.%{method} should take only 1 argument.
           Data may not imported correctly.

data/lib/rails_admin_import/formats/csv_importer.rb

@@ -61,7 +61,7 @@ module RailsAdminImport
 
       def convert_to_attributes(row)
         row.each_with_object({}) do |(field, value), record|
-          break if field.nil?
+          next if field.blank?
           field = field.to_sym
           if import_model.has_multiple_values?(field)
             field = import_model.pluralize_field(field)

data/lib/rails_admin_import/importer.rb

@@ -16,10 +16,13 @@ module RailsAdminImport
       begin
         init_results
 
-        # TODO: re-implement file size check
-        # if file_check.readlines.size > RailsAdminImport.config.line_item_limit
-        #   return results = { :success => [], :error => ["Please limit upload file to #{RailsAdminImport.config.line_item_limit} line items."] }
-        # end
+
+        if records.count > RailsAdminImport.config.line_item_limit
+          return results = {
+            success: [],
+            error: [I18n.t('admin.import.import_error.line_item_limit', limit: RailsAdminImport.config.line_item_limit)]
+          }
+        end
 
         with_transaction do
           records.each do |record|
@@ -64,7 +67,7 @@ module RailsAdminImport
     def import_record(record)
       if update_lookup && !record.has_key?(update_lookup)
         raise UpdateLookupError, I18n.t("admin.import.missing_update_lookup")
-      end 
+      end
 
       object = find_or_create_object(record, update_lookup)
       action = object.new_record? ? :create : :update
@@ -142,7 +145,7 @@ module RailsAdminImport
              name: result_count,
                action: I18n.t("admin.actions.import.done"))
     end
-    
+
     def perform_model_callback(object, method_name, record)
       if object.respond_to?(method_name)
         # Compatibility: Old import hook took 2 arguments.
@@ -175,7 +178,7 @@ module RailsAdminImport
       model = import_model.model
       object = if update.present?
                  model.where(update => record[update]).first
-               end 
+               end
 
       if object.nil?
         object = model.new(new_attrs)
@@ -221,4 +224,3 @@ module RailsAdminImport
     end
   end
 end
-

data/lib/rails_admin_import/version.rb

@@ -1,3 +1,3 @@
 module RailsAdminImport
-  VERSION = "1.3.1"
+  VERSION = "1.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_admin_import
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Steph Skardal
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-12 00:00:00.000000000 Z
+date: 2016-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -140,4 +140,3 @@ signing_key:
 specification_version: 4
 summary: Import functionality for Rails Admin
 test_files: []
-has_rdoc: