Project

importer

0.01
Repository is archived
No commit activity in last 3 years
No release in over 3 years
Define new objects or modifications of existing ones in external file (xml, csv, etc) and import them to your application. Importer will not only import all the objects but also will give you detailed summary of the import process.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 0.1.6
 Project Readme

importer¶ ↑

Importer is a tool to help you with importing objects to your database from various sources.

Repository: github.com/szajbus/importer

Docs: rdoc.info/projects/szajbus/importer

Main features:¶ ↑

  • can import from XML and CSV formats, but it’s possible to add custom parsers

  • reports how many new objects got imported, how many objects was modified and how many objects were invalid

  • includes ActiveRecord, DataMapper and MongoMapper adapters

Installation¶ ↑

Install the gem

gem install importer

To use with Ruby < 1.9

gem install importer -v "~> 0.4.0"

Add to your model

# ActiveRecord
class Product < ActiveRecord::Base
  include Importer
end

# MongoMapper
class Product
  include MongoMapper::Document
  include Importer
end

# DataMapper
class Product
  include DataMapper::Resource
  include Importer
end

And start importing

Product.import(path_to_xml_or_csv_file)

This will parse the file and import all products there are defined in it. This will return import summary which will tell you how many products were created, modified or invalid. Exact information about each product (detected attributes and errors) will be available in summary too.

Customization¶ ↑

You can create your own parser to import from sources other than XML or CSV files. Check the implementation of one of existing parsers to find out how to write your own. Then just pass parser class to import method:

Product.import(path_to_file, :parser => CustomParserClass)

You can also create your custom versions of Import and ImportedObject classes. A possible alternative version could be ActiveRecord Import and ImportedObject models that would save import summary to database for later inspection. Check the rdocs for these classes for more information. You force the importer to use a custom Import class with:

Product.import(path_to_file, :import => CustomImportClass)

Updating objects¶ ↑

Importer is smart enough to figure out whether it has to create a new object or just update existing one during import. By default it’s tries to find existing object by detected id attribute. If the object is found Importer updates it, otherwise a new object is created. You can change the way how existing objects are searched for by overriding your model’s find_on_import class method.

class Product < ActiveRecord::Base
  include Importer

  def find_on_import(import, attributes)
    find_by_name(attributes["custom_attribute"])
  end
end

Building objects¶ ↑

The default way to build new objects or update existing ones is to merge their attributes with detected ones. To provide custom building logic override your model’s merge_attributes_on_import instance method.

def merge_attributes_on_import(import, attributes)
  self.attributes  = attributes
  self.imported_at = Time.now
end

Note on Patches/Pull Requests¶ ↑

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Disclaimer¶ ↑

Importer gem/plugin was extracted from an actual Ruby on Rails application. It probably lacks some features or needs some polishing. Feel free to contribute.

The gem is still under development, backward compatibility can not be guaranteed (at least until it reaches 1.0 stable version).

Copyright © 2010 Michal Szajbe. See LICENSE for details.