remotipart 0.4.2 → 1.0

data/History.rdoc

@@ -1,6 +1,13 @@
 = History
 
-=== 0.4.2 / 2011-26-08
+=== 1.0 / 2011-08-26
+
+* New Features
+  * New dependency on simpler jquery.iframe-transport.js (no more form.js)
+  * New Rack middleware, making `remotipart_response` block obsolete in js.erb responses
+  * Better support for all requested ajax data-types
+
+=== 0.4.2 / 2011-08-26
 
 * Minor Enhancements
   * Updated to jquery.form.js v2.84

data/README.rdoc

@@ -1,9 +1,10 @@
 = Remotipart
 
-Remotipart is a Ruby on Rails gem enabling remote multipart forms (AJAX style file uploads) with jQuery.
-This gem augments the native Rails jQuery remote form function enabling asynchronous file uploads with little to no modification to your application.
+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.
 
-{View Homepage and Demos}[http://www.alfajango.com/blog/remotipart-rails-gem/]
+* {Homepage and Demos}[http://www.alfajango.com/blog/remotipart-rails-gem/]
+* {How AJAX File Uploads Work}[http://www.alfajango.com/blog/ajax-file-uploads-with-the-iframe-method/]
 
 == Dependencies
 
@@ -12,24 +13,33 @@ This gem augments the native Rails jQuery remote form function enabling asynchro
 
 == Installation
 
-<b>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.</b>
+<b>Your app should be using jquery-rails gem v1.0.12 or above.</b>
+
+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}[https://github.com/JangoSteve/remotipart/blob/master/VERSION_COMPATIBILITY.rdoc].
 
 [1.]
   Install the Remotipart gem
 
-  * Add this line to your GEMFILE (add the correct version from previous section if needed)
+  * Add this line to your GEMFILE (use the appropriate version from the compatibilty chart if needed)
 
-   gem 'remotipart', '~> 0.4'
+   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 <tt>//= require jquery_ujs</tt>):
+
+   //= require jquery.remotipart
+
 === Rails 3.0
 
 [2.]
-  Run the Remotipart install generator to add jquery.form.js and jquery.remotipart.js to public/javascripts/
+  Run the Remotipart install generator to add jquery.iframe-transport.js and jquery.remotipart.js to public/javascripts/
 
    rails g remotipart:install
 
@@ -38,28 +48,12 @@ make sure you have a supported jquery-ujs (rails.js or jquery_ujs.js) version fr
 
    <%= javascript_include_tag :defaults %>
 
-=== 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 <tt>//= require jquery_ujs</tt>):
-
-   //= require jquery.form
-   //= require jquery.remotipart
-
 == Usage
 
 * For multipart / forms with file inputs, set your form_for to remote as you would for a normal ajax form:
    :remote => true
 * When Javascript is enabled in the user's browser, the form, including the file, will be submitted asynchronously to your controller with:
    :format == 'js'
-* In the JS response template for your controller action, wrap all of your response code in one remotipart_response block:
-   <%= remotipart_response do %> All Javascript response code goes here <% end %>
-* The options available to the text_area_tag[http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-text_area_tag] can be passed to remotipart_response for further control over the response. For instance:
-   <%= remotipart_response({:escape => false}) do %> All Javascript response code goes here <% end %>
-* Anything inside the +remotipart_response+ block will be rendered normally, unless the request actually did come from a remotipart-submitted form. So <tt>js.erb</tt> responses can be shared between remotipart and non-remotipart forms.
-    <%= remotipart_response do %>
-      // do stuff here
-    <% end %>
 * If you need to determine if a particular request was made via a remotipart-enabled form...
   * from your Rails controller or view:
 
@@ -93,14 +87,12 @@ sample_controller.rb
   end
 
 create.js.erb
-  <%= remotipart_response do %>
-    // Display a Javascript alert
-    alert('success!');
-    <% if remotipart_submitted? %>
-      alert('submitted via remotipart')
-    <% else %>
-      alert('submitted via native jquery-ujs')
-    <% end %>
+  // 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
@@ -115,6 +107,36 @@ create.js.erb
   (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.
 
+== 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.
+
+* {Demo Rails App with Tests}[https://github.com/JangoSteve/Rails-jQuery-Demo/tree/remotipart]
+  * {Tests}[https://github.com/JangoSteve/Rails-jQuery-Demo/blob/remotipart/spec/integration/comments_spec.rb]
+
+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}[https://github.com/ajrkerr] 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 (c) 2011 Greg Leppert, Steve Schwartz. See LICENSE for details.
+Copyright (c) 2011 {Steve Schwartz}[https://github.com/JangoSteve], {Greg Leppert}[https://github.com/leppert]. See LICENSE for details.

data/lib/generators/remotipart/install/install_generator.rb

@@ -4,12 +4,12 @@ module Remotipart
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
 
-      desc "This generator installs Form.js #{Remotipart::Rails::FORMJS_VERSION} and Remotipart #{Remotipart::Rails::VERSION}"
+      desc "This generator installs IframeTransport.js #{Remotipart::Rails::IFRAMETRANSPORT_VERSION} and Remotipart #{Remotipart::Rails::VERSION}"
       source_root File.expand_path('../../../../../vendor/assets/javascripts', __FILE__)
 
-      def install_formjs
-        say_status "copying", "Form.js #{Remotipart::Rails::FORMJS_VERSION}", :green
-        copy_file "jquery.form.js", "public/javascripts/jquery.form.js"
+      def install_iframe_transport
+        say_status "copying", "IframeTransport.js #{Remotipart::Rails::IFRAMETRANSPORT_VERSION}", :green
+        copy_file "jquery.iframe-transport.js", "public/javascripts/jquery.iframe-transport.js"
       end
 
       def install_remotipart

data/lib/remotipart/middleware.rb

@@ -0,0 +1,33 @@
+module Remotipart
+
+  # A middleware to look for our form parameters and 
+  # encourage Rails to respond with the requested format
+  class Middleware
+    def initialize app
+      @app = app
+    end
+
+    def call env
+      # For some reason, in Rails 3.0, `env['rack.request.form_hash']`
+      # isn't populated unless we manually initialize a new Rack::Request
+      # and call the `POST` method on it
+      if ::Rails.version < "3.1"
+        Rack::Request.new(env).POST
+      end
+      params = env['rack.request.form_hash']
+
+      # This was using an iframe transport, and is therefore an XHR
+      # This is required if we're going to override the http_accept
+      if params and params['X-Requested-With'] == 'IFrame'
+        env['HTTP_X_REQUESTED_WITH'] = 'xmlhttprequest'
+      end
+
+      # Override the accepted format, because it isn't what we really want
+      if params and params['X-Http-Accept']
+        env['HTTP_ACCEPT'] = params['X-Http-Accept']
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/remotipart/rails/engine.rb

@@ -10,6 +10,11 @@ module Remotipart
 
       initializer "remotipart.controller_helper" do
         ActionController::Base.send :include, RequestHelper
+        ActionController::Base.send :include, RenderOverrides
+      end
+
+      initializer "remotipart.include_middelware" do
+        config.app_middleware.insert_after ActionDispatch::ParamsParser, Middleware
       end
     end
 

data/lib/remotipart/rails/railtie.rb

@@ -5,7 +5,7 @@ module Remotipart
     class Railtie < ::Rails::Railtie
       config.before_configuration do
         # Files to be added to :defaults
-        FILES = ['jquery.form', 'jquery.remotipart']
+        FILES = ['jquery.iframe-transport', 'jquery.remotipart']
 
         # Figure out where rails.js (aka jquery_ujs.js if install by jquery-rails gem) is
         # in the :defaults array
@@ -29,6 +29,11 @@ module Remotipart
 
       initializer "remotipart.controller_helper" do
         ActionController::Base.send :include, RequestHelper
+        ActionController::Base.send :include, RenderOverrides
+      end
+
+      initializer "remotipart.include_middelware" do
+        config.app_middleware.insert_after ActionDispatch::ParamsParser, Middleware
       end
     end
 

data/lib/remotipart/rails/version.rb

@@ -1,6 +1,6 @@
 module Remotipart
   module Rails
-    VERSION = "0.4.2"
-    FORMJS_VERSION = "2.84"
+    VERSION = "1.0"
+    IFRAMETRANSPORT_VERSION = "07.05.2011"
   end
 end

data/lib/remotipart/render_overrides.rb

@@ -0,0 +1,15 @@
+module Remotipart
+
+  #Responder used to automagically wrap any non-xml replies in a text-area
+  # as expected by iframe-transport
+  module RenderOverrides
+    def render *args
+      super
+      if remotipart_submitted?
+        response.body = %{<textarea data-type=\"#{content_type}\">#{response.body}</textarea>}
+        response.content_type = Mime::HTML
+      end
+      response_body
+    end
+  end
+end

data/lib/remotipart/request_helper.rb

@@ -3,6 +3,7 @@ module Remotipart
     def remotipart_submitted?
       params[:remotipart_submitted] ? true : false
     end
+    
     alias :remotipart_requested? :remotipart_submitted?
   end
 end

data/lib/remotipart/view_helper.rb

@@ -1,13 +1,9 @@
 module Remotipart
   module ViewHelper
+    #No longer used
+    #Retrained to prevent issues while updating
     def remotipart_response(options = {}, &block)
-      content = with_output_buffer(&block)
-      if remotipart_submitted?
-        response.content_type = Mime::HTML
-        text_area_tag('remotipart_response', String.new(content), options)
-      else
-        content
-      end
+      with_output_buffer(&block)
     end
   end
 end

data/lib/remotipart.rb

@@ -1,3 +1,5 @@
 require 'remotipart/view_helper'
 require 'remotipart/request_helper'
+require 'remotipart/render_overrides'
+require 'remotipart/middleware'
 require 'remotipart/rails' if defined?(Rails)

data/remotipart.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{remotipart}
-  s.version = "0.4.2"
+  s.version = "1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Greg Leppert", "Steve Schwartz"]
@@ -28,16 +28,18 @@ Gem::Specification.new do |s|
      "VERSION_COMPATIBILITY.rdoc",
      "lib/generators/remotipart/install/install_generator.rb",
      "lib/remotipart.rb",
+     "lib/remotipart/middleware.rb",
      "lib/remotipart/rails.rb",
      "lib/remotipart/rails/engine.rb",
      "lib/remotipart/rails/railtie.rb",
      "lib/remotipart/rails/version.rb",
+     "lib/remotipart/render_overrides.rb",
      "lib/remotipart/request_helper.rb",
      "lib/remotipart/view_helper.rb",
      "remotipart.gemspec",
      "test/helper.rb",
      "test/test_remotipart.rb",
-     "vendor/assets/javascripts/jquery.form.js",
+     "vendor/assets/javascripts/jquery.iframe-transport.js",
      "vendor/assets/javascripts/jquery.remotipart.js"
   ]
   s.homepage = %q{http://www.alfajango.com/blog/remotipart-rails-gem/}

data/vendor/assets/javascripts/jquery.iframe-transport.js

@@ -0,0 +1,233 @@
+// This [jQuery](http://jquery.com/) plugin implements an `<iframe>`
+// [transport](http://api.jquery.com/extending-ajax/#Transports) so that
+// `$.ajax()` calls support the uploading of files using standard HTML file
+// input fields. This is done by switching the exchange from `XMLHttpRequest` to
+// a hidden `iframe` element containing a form that is submitted.
+
+// The [source for the plugin](http://github.com/cmlenz/jquery-iframe-transport)
+// is available on [Github](http://github.com/) and dual licensed under the MIT
+// or GPL Version 2 licenses.
+
+// ## Usage
+
+// To use this plugin, you simply add a `iframe` option with the value `true`
+// to the Ajax settings an `$.ajax()` call, and specify the file fields to
+// include in the submssion using the `files` option, which can be a selector,
+// jQuery object, or a list of DOM elements containing one or more
+// `<input type="file">` elements:
+
+//     $("#myform").submit(function() {
+//         $.ajax(this.action, {
+//             files: $(":file", this),
+//             iframe: true
+//         }).complete(function(data) {
+//             console.log(data);
+//         });
+//     });
+
+// The plugin will construct a hidden `<iframe>` element containing a copy of
+// the form the file field belongs to, will disable any form fields not
+// explicitly included, submit that form, and process the response.
+
+// If you want to include other form fields in the form submission, include them
+// in the `data` option, and set the `processData` option to `false`:
+
+//     $("#myform").submit(function() {
+//         $.ajax(this.action, {
+//             data: $(":text", this).serializeArray(),
+//             files: $(":file", this),
+//             iframe: true,
+//             processData: false
+//         }).complete(function(data) {
+//             console.log(data);
+//         });
+//     });
+
+// ### The Server Side
+
+// If the response is not HTML or XML, you (unfortunately) need to apply some
+// trickery on the server side. To send back a JSON payload, send back an HTML
+// `<textarea>` element with a `data-type` attribute that contains the MIME
+// type, and put the actual payload in the textarea:
+
+//     <textarea data-type="application/json">
+//       {"ok": true, "message": "Thanks so much"}
+//     </textarea>
+
+// The iframe transport plugin will detect this and attempt to apply the same
+// conversions that jQuery applies to regular responses. That means for the
+// example above you should get a Javascript object as the `data` parameter of
+// the `complete` callback, with the properties `ok: true` and
+// `message: "Thanks so much"`.
+
+// ### Compatibility
+
+// This plugin has primarily been tested on Safari 5, Firefox 4, and Internet
+// Explorer all the way back to version 6. While I haven't found any issues with
+// it so far, I'm fairly sure it still doesn't work around all the quirks in all
+// different browsers. But the code is still pretty simple overall, so you
+// should be able to fix it and contribute a patch :)
+
+// ## Annotated Source
+
+(function($, undefined) {
+
+  // Register a prefilter that checks whether the `iframe` option is set, and
+  // switches to the iframe transport if it is `true`.
+  $.ajaxPrefilter(function(options, origOptions, jqXHR) {
+    if (options.iframe) {
+      return "iframe";
+    }
+  });
+
+  // Register an iframe transport, independent of requested data type. It will
+  // only activate when the "files" option has been set to a non-empty list of
+  // enabled file inputs.
+  $.ajaxTransport("iframe", function(options, origOptions, jqXHR) {
+    var form = null,
+        iframe = null,
+        origAction = null,
+        origTarget = null,
+        origEnctype = null,
+        addedFields = [],
+        disabledFields = [],
+        files = $(options.files).filter(":file:enabled");
+
+    // This function gets called after a successful submission or an abortion
+    // and should revert all changes made to the page to enable the
+    // submission via this transport.
+    function cleanUp() {
+      $(addedFields).each(function() {
+        this.remove();
+      });
+      $(disabledFields).each(function() {
+        this.disabled = false;
+      });
+      form.attr("action", origAction || "")
+          .attr("target", origTarget || "")
+          .attr("enctype", origEnctype || "");
+      iframe.attr("src", "javascript:false;").remove();
+    }
+
+    // Remove "iframe" from the data types list so that further processing is
+    // based on the content type returned by the server, without attempting an
+    // (unsupported) conversion from "iframe" to the actual type.
+    options.dataTypes.shift();
+    
+    if (files.length) {
+      // Determine the form the file fields belong to, and make sure they all
+      // actually belong to the same form.
+      files.each(function() {
+        if (form !== null && this.form !== form) {
+          jQuery.error("All file fields must belong to the same form");
+        }
+        form = this.form;
+      });
+      form = $(form);
+
+      // Store the original form attributes that we'll be replacing temporarily.
+      origAction = form.attr("action");
+      origTarget = form.attr("target");
+      origEnctype = form.attr("enctype");
+
+      // We need to disable all other inputs in the form so that they don't get
+      // included in the submitted data unexpectedly.
+      form.find(":input:not(:submit)").each(function() {
+        if (!this.disabled && (this.type != "file" || files.index(this) < 0)) {
+          this.disabled = true;
+          disabledFields.push(this);
+        }
+      });
+
+      // If there is any additional data specified via the `data` option,
+      // we add it as hidden fields to the form. This (currently) requires
+      // the `processData` option to be set to false so that the data doesn't
+      // get serialized to a string.
+      if (typeof(options.data) === "string" && options.data.length > 0) {
+        jQuery.error("data must not be serialized");
+      }
+      $.each(options.data || {}, function(name, value) {
+        if ($.isPlainObject(value)) {
+          name = value.name;
+          value = value.value;
+        }
+        addedFields.push($("<input type='hidden'>").attr("name", name)
+          .attr("value", value).appendTo(form));
+      });
+
+      // Add a hidden `X-Requested-With` field with the value `IFrame` to the
+      // field, to help server-side code to determine that the upload happened
+      // through this transport.
+      addedFields.push($("<input type='hidden' name='X-Requested-With'>")
+        .attr("value", "IFrame").appendTo(form));
+
+      // Borrowed straight from the JQuery source
+      // Provides a way of specifying the accepted data type similar to HTTP_ACCEPTS
+      accepts = options.dataTypes[ 0 ] && options.accepts[ options.dataTypes[0] ] ?
+        options.accepts[ options.dataTypes[0] ] + ( options.dataTypes[ 0 ] !== "*" ? ", */*; q=0.01" : "" ) :
+        options.accepts[ "*" ]
+
+      addedFields.push($("<input type='hidden' name='X-Http-Accept'>")
+        .attr("value", accepts).appendTo(form));
+
+      return {
+
+        // The `send` function is called by jQuery when the request should be
+        // sent.
+        send: function(headers, completeCallback) {
+          iframe = $("<iframe src='javascript:false;' name='iframe-" + $.now()
+            + "' style='display:none'></iframe>");
+          
+          // The first load event gets fired after the iframe has been injected
+          // into the DOM, and is used to prepare the actual submission.
+          iframe.bind("load", function() {
+
+            // The second load event gets fired when the response to the form
+            // submission is received. The implementation detects whether the
+            // actual payload is embedded in a `<textarea>` element, and
+            // prepares the required conversions to be made in that case.
+            iframe.unbind("load").bind("load", function() {
+              
+              var doc = this.contentWindow ? this.contentWindow.document :
+                (this.contentDocument ? this.contentDocument : this.document),
+                root = doc.documentElement ? doc.documentElement : doc.body,
+                textarea = root.getElementsByTagName("textarea")[0],
+                type = textarea ? textarea.getAttribute("data-type") : null;
+              
+              var status = 200,
+                statusText = "OK",
+                responses = { text: type ? textarea.value : root ? root.innerHTML : null },
+                headers = "Content-Type: " + (type || "text/html")
+
+              completeCallback(status, statusText, responses, headers);
+
+              setTimeout(cleanUp, 50);
+            });
+            
+            // Now that the load handler has been set up, reconfigure and
+            // submit the form.
+            form.attr("action", options.url)
+              .attr("target", iframe.attr("name"))
+              .attr("enctype", "multipart/form-data")
+              .get(0).submit();
+          });
+
+          // After everything has been set up correctly, the iframe gets
+          // injected into the DOM so that the submission can be initiated.
+          iframe.insertAfter(form);
+        },
+
+        // The `abort` function is called by jQuery when the request should be
+        // aborted.
+        abort: function() {
+          if (iframe !== null) {
+            iframe.unbind("load").attr("src", "javascript:false;");
+            cleanUp();
+          }
+        }
+
+      };
+    }
+  });
+
+})(jQuery);