active_importer 0.1.1 → 0.2.0

data/README.md

@@ -80,12 +80,16 @@ class EmployeeImporter < ActiveImporter::Base
 
   attr_reader :row_count
 
-  column 'First name', :first_name
-  column 'Last name', :last_name
+  column 'First name'
+  column 'Last name'
   column 'Department', :department do |department_name|
     Department.find_by(name: department_name)
   end
 
+  on :row_processing do
+    model.full_name = [row['First name'], row['Last name']].join(' ')
+  end
+
   on :import_started do
     @row_count = 0
   end
@@ -117,6 +121,8 @@ The supported events are:
   event is fired by an importer, none of its other events are ever fired.
 - **import_started:** Fired once at the beginning of the data processing,
   before the first row is processed.
+- **row_processing:** Fired while the row is being processed to be imported
+  into a model instance.
 - **row_processed:** Fired once for each row that has been processed,
   regardless of whether it resulted in success or error.
 - **row_success:** Fired once for each row that was imported successfully into
@@ -132,6 +138,37 @@ all the importer attributes and instance variables.  Error-related events
 (`:import_failed` and `:row_error`) pass to the blocks the instance of the
 exception that provoked the error condition.
 
+Additionally, all the `row_*` events have access to the `row` and `model`
+variables, which reference the spreadsheet row being processed, and the model
+object where the row data is being stored, respectively.  This feature is
+specifically useful for the `:row_processing` event handler, which is triggered
+while a row is being processed, and before the corresponding data model is
+saved.  This allows to define any complex data-import logic that cannot be
+expressed in terms of mapping a column to a data field.
+
+### Selecting the model instance to import into
+
+By default, the importer will attempt to generate a new model instance per row
+processed.  The importer can be instructed to update records instead, if they
+already exist, instead of always attempting to generate a new one.
+
+```ruby
+class EmployeeImporter
+  imports Employee
+
+  fetch_model do
+    Employee.where(first_name: row['First name'], last_name: row['Last name']).first_or_initialize
+  end
+
+  # ...
+end
+```
+
+The code above specifies that, for each row, the importer should attempt to
+find an existing model for the employee with the first and last name in the row
+being processed.  If this record exist, the row data will be used to update the
+given model instance.  Otherwise, a new employee record will be created.
+
 ## Contributing
 
 1. Fork it

data/lib/active_importer/base.rb

@@ -26,6 +26,14 @@ module ActiveImporter
       self.class.model_class
     end
 
+    def self.fetch_model(&block)
+      @fetch_model_block = block
+    end
+
+    def self.fetch_model_block
+      @fetch_model_block
+    end
+
     def self.column(title, field = nil, &block)
       title = title.strip
       if columns[title]
@@ -45,6 +53,7 @@ module ActiveImporter
     EVENTS = [
       :row_success,
       :row_error,
+      :row_processing,
       :row_processed,
       :import_started,
       :import_finished,
@@ -77,6 +86,7 @@ module ActiveImporter
 
     class << self
       private :fire_event
+      private :fetch_model_block
     end
 
     #
@@ -104,8 +114,16 @@ module ActiveImporter
       fire_event :import_failed, e
     end
 
+    def fetch_model_block
+      self.class.send(:fetch_model_block)
+    end
+
     def fetch_model
-      model_class.new
+      if fetch_model_block
+        self.instance_exec(&fetch_model_block)
+      else
+        model_class.new
+      end
     end
 
     def import
@@ -131,9 +149,6 @@ module ActiveImporter
       row_errors.count
     end
 
-    def hook
-    end
-
     private
 
     def columns
@@ -142,7 +157,7 @@ module ActiveImporter
 
     def find_header_index
       (1..@book.last_row).each do |index|
-        row = @book.row(index).map(&:strip)
+        row = @book.row(index).map { |cell| cell.to_s.strip }
         return index if columns.keys.all? { |item| row.include?(item) }
       end
       return nil
@@ -182,7 +197,7 @@ module ActiveImporter
         value = self.instance_exec(value, &transform) if transform
         model[field_name] = value
       end
-      hook
+      fire_event :row_processing
     end
 
     def row_to_hash(row)

data/lib/active_importer/version.rb

@@ -1,3 +1,3 @@
 module ActiveImporter
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/active_importer/base_spec.rb

@@ -14,6 +14,7 @@ describe ActiveImporter::Base do
 
   before do
     expect(Roo::Spreadsheet).to receive(:open).and_return { Spreadsheet.new(spreadsheet_data) }
+    EmployeeImporter.instance_variable_set(:@fetch_model_block, nil)
   end
 
   it 'imports all data from the spreadsheet into the model' do
@@ -88,7 +89,7 @@ describe ActiveImporter::Base do
     let(:spreadsheet_data) do
       [
         [],
-        ['List of employees', '', 'Company Name'],
+        ['List of employees', '', nil, 'Company Name'],
         ['Ordered by', 'Birth Date'],
         ['Name', 'Department', 'Birth Date', 'Manager'],
         ['John Doe', 'IT', '2013-10-25'],
@@ -102,19 +103,17 @@ describe ActiveImporter::Base do
   end
 
   describe '.fetch_model' do
-    let(:model) { Employee.new }
-
     it 'controls what model instance is loaded for each given row' do
-      expect(EmployeeImporter).to receive(:new).once.and_return(importer)
-      expect(importer).to receive(:fetch_model).twice.and_return(model)
+      model = Employee.new
+      EmployeeImporter.fetch_model { model }
       expect { EmployeeImporter.import('/dummy/file') }.to change(Employee, :count).by(1)
     end
   end
 
-  describe '.hook' do
+  describe 'row_processing event' do
     it 'allows the importer to modify the model for each row' do
       expect(EmployeeImporter).to receive(:new).once.and_return(importer)
-      expect(importer).to receive(:hook).twice
+      expect(importer).to receive(:row_processing).twice
       EmployeeImporter.import('/dummy/file')
     end
   end

data/spec/stubs/data_model.rb

@@ -1,8 +1,7 @@
 class DataModel
-  @@count = 0
 
   def self.count
-    @@count
+    @count ||= 0
   end
 
   attr_reader :errors
@@ -25,7 +24,7 @@ class DataModel
 
   def save
     if valid?
-      @@count += 1 if @new_record
+      self.class.send(:increment_count) if @new_record
       @new_record = false
       true
     else
@@ -43,10 +42,21 @@ class DataModel
 
   def valid?
     validate
-    @errors.empty?
+    errors.empty?
   end
 
   def validate
     # ...
   end
+
+  private
+
+  def self.increment_count
+    count
+    @count += 1
+  end
+
+  class << self
+    private :increment_count
+  end
 end

data/spec/stubs/employee.rb

@@ -5,7 +5,7 @@ class Employee < DataModel
   attr_accessor :name, :birth_date, :department, :department_id
 
   def validate
-    @errors << 'Invalid name' if name == 'Invalid'
+    errors << 'Invalid name' if name == 'Invalid'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_importer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-08 00:00:00.000000000 Z
+date: 2013-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roo
@@ -112,7 +112,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -839045621640734141
+      hash: -1076262899309802271
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -121,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -839045621640734141
+      hash: -1076262899309802271
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23