csv_importable 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e0aed6e505dbece1acd37592260ff5348f95a69
-  data.tar.gz: ee33de362f185bb1bf670712e0da5fbf5d22de69
+  metadata.gz: d03b574a8314c2eb5c192a7dcb2437cd93a6bf8b
+  data.tar.gz: c24aa7a22db05556ebe510e137d52cbd981ba4dc
 SHA512:
-  metadata.gz: c8fa7d45452b176b052ab5d925fb82c51c23b72c1ead2fc6cd05d19db1bb6cd9461cc60bfd0798017061c98dda3a1332b55d8c8120e4757164850c353a81b48f
-  data.tar.gz: 6b4e66526a3a0c84b632ee276c64d250821efc73a77cb67d377a78d597c489fe561b816e4ad642a41b75ff69e5edfd864b37c06eb5f598101a1745ac181b536b
+  metadata.gz: 59e81c752e193230d82568b113a084dfe97452a4d5d326c71cd6ed85f2afcb3cc1eb3d1be459690c8ba0a13269babe430d62ee2322b5d8cb36a2f315ac0a6e6e
+  data.tar.gz: 28a2c42b3545a1613adb6e41efade75bc9ea0267cdea9ca5f0154617b61800035cac9f2455a604fe4ecab1b8bfd695b9b2b0670a5d8ec594504804d10983b48c

data/README.md

@@ -1,6 +1,26 @@
 # CSV Importable
 
-Intelligently parse CSVs and display errors to your users.
+While it may seem simple on the surface, allowing a user to upload a CSV for inserting or updating multiple records at a time can actually be quite difficult. Here are a few of the tasks involved:
+
+- For big files, put the import on a background job
+    - store CSV for background processing
+    - send email when complete
+    - store status to keep the user informed on progress
+    - store errors to show the user what went wrong if the import fails
+- For each row in the CSV, do the following:
+  - Parse the data (for example, extracting a date field)
+  - Find or create objects and their relationships
+  - Record any errors that occur to show the user
+- If any errors occur during the process, rollback all transactions, show the user the errors, and allow the user to try again
+
+While this process is certainly complicated, it is consistent enough to justify the existence of a gem.
+
+The goal of the CSV Importable gem is to allow you to focus on what is unique about your import process: how the data from the CSV should impact your database.
+
+## Example Rails App
+
+- Code: https://github.com/LaunchPadLab/example_csv_import
+- Demo: https://example-csv-import.herokuapp.com/
 
 ## Installation
 
@@ -44,6 +64,8 @@ class Import < ApplicationRecord
   has_attached_file :file
   validates_attachment :file, content_type: { content_type: ['text/csv']}, message: "is not in CSV format"
 
+  validates :file, presence: true
+
   ## for background processing
   ## note - this code is for Delayed Jobs,
   ## you may need to implement something different
@@ -54,7 +76,7 @@ class Import < ApplicationRecord
   def read_file
     # needs to return StringIO of file
     # for paperclip, use:
-    # Paperclip.io_adapters.for(file).read
+    Paperclip.io_adapters.for(file).read
   end
 
   def after_async_complete
@@ -90,10 +112,10 @@ The only method that you need to define here is the `row_importer_class`, which
 
 ### Create RowImporter Class
 
-The `RowImporter` class handles the logic surrounding how one row in the CSV should be imported and added to the database. You need only (1) inherit from `CSVImportable::CSVImporter` and (2) implement the `import_row` method.
+The `RowImporter` class handles the logic surrounding how one row in the CSV should be imported and added to the database. You need only (1) inherit from `CSVImportable::RowImporter` and (2) implement the `import_row` method.
 
 ```ruby
-class UserRowImporter < CSVImportable::CSVImporter
+class UserRowImporter < CSVImportable::RowImporter
   def import_row
     user = User.create(
       email: pull_string('email', required: true),
@@ -106,19 +128,19 @@ class UserRowImporter < CSVImportable::CSVImporter
 end
 ```
 
-See that `pull_string` method? See the Parsers section below for more information on how to take advantage of them.
+See that `pull_string` method? Check out the Parsers section below for more information on how to take advantage of default and custom parsers.
 
 ### Creating an Import UI for your users
 
-Let's say you want to create a UI for your users to upload a CSV of users for your new `UserImport`.
+Let's say you want to create a UI for your users to upload a CSV for your new `UserImport`.
 
-Routes:
+**Routes:**
 
 ```ruby
-resources :user_imports, only: [:new, :create, :index]
+resources :user_imports
 ```
 
-Controller (app/controllers/user_imports_controller.rb):
+**Controller (app/controllers/user_imports_controller.rb):**
 
 ```ruby
 class UserImportsController < ApplicationController
@@ -127,22 +149,53 @@ class UserImportsController < ApplicationController
   end
 
   def create
-    @import = UserImport.new(params[:user_import])
+    @import = UserImport.new(user_import_params)
+    process_import
+  end
 
-    if @import.import!
-      redirect_to :back, notice: "The file is being imported."
-    else
-      render :new
-    end
+  def edit
+    @import = UserImport.find(params[:id])
+  end
+
+  def update
+    @import = UserImport.find(params[:id])
+    @import.attributes = user_import_params
+    process_import
   end
 
   def index
     @imports = UserImport.all
   end
+
+  private
+
+    def process_import
+      if @import.import!
+        return redirect_to user_imports_path, notice: "The file is being imported."
+      else
+        return redirect_to edit_user_import_path(@import)
+      end
+    end
+
+    def user_import_params
+      params.require(:user_import).permit(:file)
+    end
 end
 ```
 
-New view (app/views/user_imports/new.html.erb):
+**New view (app/views/user_imports/new.html.erb):**
+
+```erb
+<%= render 'form' %>
+```
+
+**Edit view (app/views/user_imports/edit.html.erb):**
+
+```erb
+<%= render 'form' %>
+```
+
+**Form partial (app/views/user_imports/_form.html.erb):**
 
 ```erb
 <%= form_for @import, html: { multipart: true } do |f| %>
@@ -159,7 +212,7 @@ New view (app/views/user_imports/new.html.erb):
 <% end %>
 ```
 
-Index view (app/views/user_imports/index.html.erb):
+**Index view (app/views/user_imports/index.html.erb):**
 
 ```erb
 <ul>
@@ -180,6 +233,42 @@ Index view (app/views/user_imports/index.html.erb):
 </ul>
 ```
 
+## Send an email once background job finishes
+
+If the user uploads a large file that exceeds your `big_file_threshold`, you can send an email to the user when it is complete.
+
+**app/models/import.rb**
+
+```ruby
+def async_complete
+  SiteMailer.import_complete(self).deliver_later
+end
+```
+
+**app/mailers/site_mailer.rb**
+
+```ruby
+def import_complete(import)
+  @import = import
+  email = 'ryan@example.com' # this could be import.user.email for example
+  mail(to: email, subject: 'Your Import is Complete')
+end
+```
+
+**app/views/site_mailer/import_complete.html.erb**
+
+```erb
+<div>
+  <p>Your import finished processing.</p>
+  <p>Status: <span class="<%= @import.status %>"><%= @import.display_status %><span></p>
+  <% if @import.failed? %>
+    <p>Please review your errors here: <%= link_to 'See Errors', import_url(@import.id) %></p>
+  <% else %>
+    <p>You can review your import here: <%= link_to 'Review Import', import_url(@import.id) %></p>
+  <% end %>
+</div>
+```
+
 ## Advanced Usage
 
 ### Parsers
@@ -193,9 +282,9 @@ If the parser fails to coerce the data properly, it will add an error message to
 - pull_date
 - pull_float
 - pull_integer
-- pull_select (e.g. `pull_select('my_boolean_column', options: ['Yes', 'No'])`)
+- pull_select (e.g. `pull_select('color', options: ['Red', 'Green', 'Blue'])`)
 
-Basic syntax: `pull_string(column_key, args)` where `column_key` is the CSV header string for the column and `args` is a hash with the following defaults: `{ required: false }`
+Basic syntax: `pull_string(column_key, args)` where `column_key` is the CSV header string for the column and `args` is a hash with the following defaults: `{ required: false, row: row }`
 
 
 #### Custom Parsers
@@ -208,7 +297,7 @@ You can build a custom parser by creating a class that inherits from `CSVImporta
 For example:
 
 ```ruby
-class TypeParser::CustomDateTypeParser < CSVImportable::TypeParser
+class CustomDateTypeParser < CSVImportable::TypeParser
   def parse_val
     Date.strptime(value, '%m-%d-%Y')
   end
@@ -219,7 +308,7 @@ class TypeParser::CustomDateTypeParser < CSVImportable::TypeParser
 end
 ```
 
-Now, in your `RowImporter` class you can call: `TypeParser::CustomDateTypeParser.new('my_date_field')` to return a date object when the data is in the right format. If the parser fails to parse the field, it will add the correct error message for your user to review and resolve.
+Now, in your `RowImporter` class you can call: `CustomDateTypeParser.new('my_date_field', row: row)` to return a date object when the data is in the right format. If the parser fails to parse the field, it will add the correct error message for your user to review and resolve.
 
 #### Ignoring Parsers
 
@@ -286,7 +375,12 @@ ActiveAdmin.register Import do
       end
     end
 
-    f.inputs "Details" do
+    panel "1. Download Template CSV" do
+      # link to template file that should be in public/
+      link_to 'Download Template CSV', '/example.csv'
+    end
+
+    f.inputs "2. Import CSV" do
       f.input :file, :as => :file, :hint => f.object.file_file_name
     end
     f.actions
@@ -300,17 +394,19 @@ ActiveAdmin.register Import do
 
     def create
       @import = Import.new(params[:import])
+      return render :new unless @import.save
 
       if @import.import!
         process_success
       else
-        return render :new
+        return redirect_to edit_admin_import_path(@import)
       end
     end
 
     def update
       @import = Import.find(params[:id])
       @import.attributes = params[:import] || {}
+      return render :edit unless @import.save
 
       if @import.import!
         process_success

data/lib/csv_importable/type_parser/select_type_parser.rb

@@ -8,7 +8,10 @@ module CSVImportable
 
     def parse_val
       val = value.downcase
-      raise unless options.include?(val)
+      opts = options.map do |option|
+        option.downcase if option.respond_to?(:downcase)
+      end
+      raise unless opts.include?(val)
       val
     end
 

data/lib/csv_importable/version.rb

@@ -1,3 +1,3 @@
 module CsvImportable
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: csv_importable
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ryan Francis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-12 00:00:00.000000000 Z
+date: 2017-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler