pjleonhardt / ActsAsCSVable

ActsAsCSVable

This plugin allows you to export and import ActiveRecord objects via CSV, along with proving support for responding to the CSV format (via URL).

Repository

git://github.com/pjleonhardt/ActsAsCSVable.git

Installation

Trunk: github.com/pjleonhardt/ActsAsCSVable/tree/master

Project Management

github.com/pjleonhardt/ActsAsCSVable/issues

Usage

Once included as a plugin in your Rails app, you can use the new functionality right away.

You can apply the to_csv method to instances of ActiveRecord objects, or the classes themselves.

People.find_all_by_first_name("Peter").to_csv or People.to_csv (performs a People.find(:all))

You can also use the respond_to method to respond to .csv requests

url /people.csv

  def index
    @people = Person.find(:all)

    respond_to do |wants|
      wants.csv { render :text => @people.to_csv(:columns => [:first_name, :last_name, :date_of_birth]) }
      # or
      wants.csv { render :text => @people.to_csv(:template => :fancy) }
      # or
      wants.csv { render :text => @peope.to_csv } #renders the :default template
    end
  end

  #/people/import
  def import
    file = params[:csv_uplodad]
    template = params[:upload_template]
    projects = Project.from_csv(file, template)

    if projects.all?(&:valid?)
      projects.each(&:save)
    else
      # Options options options...
      # 1) Save valid rows, and re-export invalid rows
      # 2) Save nothing, and tell user which rows were invalid
      # 3) Save nothing and tell them rows are invalid
      # 4) Up to you!
    end
  end

You can also determine which columns (or functions) you want to export. Simply define an export template in your model with an array of the columns you wan’t exported.

There are more detailed examples in the documentation files (inline documentation, run rake doc:plugins for the latest)

Options

There are multiple ways to specify which columns you want to export with the CSV. The first, and default, way is to define an export template in the model that you are exporting. This takes an array of column names. The names of the methods will be used as the Header Row for the CSV and then subsequent rows will call the method on the object. Because of the way this is set up it is possible to specify not just attributes, but any method that returns a string. Alternatively, you may pass a hash instead of an array, where the keys are used for the header row and the values used as the method to be called.

You can even call methods through associations, if needed:

      @properties.to_csv(:columns => {:owner_name => "owner.name", :address => "address"})

• :template. This allows you to be able to specify conditions for use of different columns

     #in your model
      # Exporting
      acts_as_csv_exportable :fancy_naming, [{:first => "first_name"}, {:last => "last_name"}, {:email => "email_address"}, {:address => "mailing_address"}]
      acts_as_csv_exportable :detailed, [:first_name, :last_name, :email_address, :mailing_address, :formatted_date]
      acts_as_csv_exportable :default, [:id, :first_name, :last_name]
  
      # For customized fields
      # You can define a method on the model and use that in your template or columns array
      def formatted_date
        self.date.strftime("%Y/%M/%D")
      end
      acts_as_csv_exportable :formatted_template => [:formatted_date => 'formatted_date' ]
  
      # OR
      # You can use a proc to evaluate a field on the fly for more customization
      acts_as_csv_exportable :fancy_formatted_proc, [:formatted_date => Proc.new {|x| x.date.strftime("%Y/%M/%D")} ]
  
      # Importing
      acts_as_csv_importable :default, [:id, :first_name, :last_name]
      acts_as_csv_importable :new_projects, [:name, :details, :owner_username]
  
      def owner_username=(username)
        self.owner = Users.find_by_username(username)
      end
  

• :columns. This allows you to pass an array of columns into the to_csv method. This is useful if you are dynamically generating which columns you want to export.

   @proposal.to_csv(:columns => ["title", "amount", "proposer.first_name"]). You can also pass this a hash of the form expected in acts_as_csv_exportable.
  

Note: The :columns option take precedence over the :template option if both are specified.

License

This code is provided under the MIT License, which can be found in the LICENSE file