Remotipart

Remotipart is a Ruby on Rails gem enabling AJAX file uploads with jQuery in Rails 3.0 and Rails 3.1 remote forms. This gem augments the native Rails jQuery remote form functionality enabling asynchronous file uploads with little to no modification to your application.

Dependencies

Installation

Your app should be using jquery-rails gem v1.0.12 or above.

If you're using an old version of the jquery-rails gem, make sure you have a supported jquery-ujs (rails.js or jquery_ujs.js) version from VERSION_COMPATIBILITY.

1.

Install the Remotipart gem

  • Add this line to your GEMFILE (use the appropriate version from the compatibilty chart if needed)

gem 'remotipart', '~> 1.0'
  • And run

bundle install

Rails 3.1

2.

The necessary js files will automatically be added to the asset pipeline, so add the following to app/assets/javascripts/application.js (right after //= require jquery_ujs):

//= require jquery.remotipart

Rails 3.0

2.

Run the Remotipart install generator to add jquery.iframe-transport.js and jquery.remotipart.js to public/javascripts/

rails g remotipart:install
3.

The necessary js files will be added to your app's javascript :defaults, so make sure the following is in your application layout:

<%= javascript_include_tag :defaults %>

Usage

Example

sample_layout.html.erb

<%= form_for @sample, :html => { :multipart => true }, :remote => true do |f| %>
  <div class="field">
    <%= f.label :file %>
    <%= f.file_field :file %>
  </div>
  <div class="actions">
    <%= f.submit %>
  </div>
<% end %>

sample_controller.rb

def create
  respond_to do |format|
    if @sample.save
      format.js
    end
  end
end

create.js.erb

// Display a Javascript alert
alert('success!');
<% if remotipart_submitted? %>
  alert('submitted via remotipart')
<% else %>
  alert('submitted via native jquery-ujs')
<% end %>

Note on Patches/Pull Requests

If you have a general improvement, optimization, or refactoring, please read this first.

Tests

Because of the nature of AJAX file uploads and certain browser restrictions, we could not simply create unit tests (using qunit or jasmine) to test the file upload functionality of remotipart (since the browsers running those test suites won't allow us to set the target of a file upload input using javascript). So, instead we created a demo Rails app using remotipart with all remotipart functionality tested using RSpec and Capybara.

To run tests:

Clone the remotipart branch of the demo app

git clone -b remotipart git://github.com/JangoSteve/Rails-jQuery-Demo.git

Install the dependencies

bundle install

Run the tests

bundle exec rspec spec/

If you need to test your own changes to remotipart, just update the Gemfile with your own fork/branch of remotipart:

gem 'remotipart', :git => 'git://github.com/MY_FORK/remotipart.git', :branch => 'MY_BRANCH'

Special Thanks

Thank you to Greg Leppert for writing the original version of this gem and providing inspiration for the gem in its current incarnation.

Thank you to Adam Kerr for helping move over to the simpler jQuery 1.6-compatible iframe-transport.js and for helping write the rack middleware, making remotipart even easier to use in Rails.

Copyright

Copyright © 2011 Steve Schwartz, Greg Leppert. See LICENSE for details.