README.md in opal-jquery-0.4.0 vs README.md in opal-jquery-0.4.1

@@ -1,14 +1,17 @@
-# opal-jquery: jQuery Wrapper For Opal
+# opal-jquery: jQuery wrapper for Opal
 
 [![Build Status](http://img.shields.io/travis/opal/opal-jquery/master.svg)](http://travis-ci.org/opal/opal-jquery)
 
 opal-jquery provides DOM access to opal by wrapping jQuery (or zepto)
 and providing a nice ruby syntax for dealing with jQuery instances.
 
 See the Opal website for [documentation](http://opalrb.org/docs/jquery).
 
+
+
+
 ## Installation
 
 Install opal-jquery from RubyGems:
 
 ```
@@ -18,24 +21,30 @@
 Or include it in your Gemfile for Bundler:
 
 ```ruby
 gem 'opal-jquery'
 ```
+
+
+
+
 ## Running Specs
 
 Get the dependencies:
 
     $ bundle install
 
+
 ### Browser
 
 You can run the specs in any web browser, by running the `config.ru` rack file:
 
     $ bundle exec rackup
 
 And then visiting `http://localhost:9292` in any web browser.
 
+
 ### Phantomjs
 
 You will need phantomjs to run the specs outside the browser.  It can
 be downloaded at [http://phantomjs.org/download.html](http://phantomjs.org/download.html)
 
@@ -45,18 +54,23 @@
 
 Run the tests inside a phantom.js runner:
 
     $ bundle exec rake
 
+
 ### Zepto
 
 opal-jquery also supports zepto. To run specs for zepto use the rake task:
 
     $ bundle exec rake zepto
 
+
+
+
 ## Getting Started
 
+
 ### Usage
 
 `opal-jquery` can now be easily added to your opal application sources using a
 standard require:
 
@@ -76,22 +90,27 @@
 > you are compiling assets from. You can alternatively require a zepto instance.
 
 The `#alert` method is provided by `opal-jquery`. If the message displays, then
 `jquery` support should be working.
 
+
 ### How does opal-jquery work
 
 `opal-jquery` provides an `Element` class, whose instances are toll-free
 bridged instances of jquery objects. Just like ruby arrays are just javascript
 arrays, `Element` instances are just jquery objects. This makes interaction
 with jquery plugins much easier.
 
 Also, `Element` will try to bridge with Zepto if it cannot find jQuery loaded,
 making it ideal for mobile applications as well.
 
+
+
+
 ## Interacting with the DOM
 
+
 ### Finding Elements
 
 opal-jquery provides the `Element` class, which can be used to find elements in
 the current document:
 
@@ -128,10 +147,11 @@
 el = Element.find('#header')
 el.find '.foo'
 # => #<Element .... >
 ```
 
+
 ### Running code on document ready
 
 Just like jQuery, opal-jquery requires the document to be ready to
 be able to fully interact with the page. Any top level access should
 use the `ready?` method:
@@ -140,12 +160,21 @@
 Document.ready? do
   alert "document is ready to go!"
 end
 ```
 
-The `Kernel#alert` method is shown above too.
+or the equivilent `Document.ready` promise which is useful when combined with other promises:
 
+```ruby
+Document.ready.then do |ready|
+  alert "Page is ready to use!"
+end
+```
+
+Notice the use of the `Kernel#alert` method.
+
+
 ### Event handling
 
 The `Element#on` method is used to attach event handlers to elements:
 
 ```ruby
@@ -179,10 +208,11 @@
 Document.on :click do |evt|
   puts "clicked on: #{evt.current_target}"
 end
 ```
 
+
 ### CSS styles and classnames
 
 The various jQuery methods are available on `Element` instances:
 
 ```ruby
@@ -214,10 +244,13 @@
 el.css 'color', 'blue'
 el.css 'color'
 # => 'blue'
 ```
 
+
+
+
 ## HTTP/AJAX requests
 
 jQuery's Ajax implementation is also wrapped in the top level HTTP
 class.
 
@@ -258,10 +291,11 @@
 
 The request is actually triggered inside the `HTTP.get` method, but due
 to the async nature of the request, the callback and errback handlers can
 be added anytime before the request returns.
 
+
 ### Handling responses
 
 Web apps deal with JSON responses quite frequently, so there is a useful
 `#json` helper method to get the JSON content from a request:
 
@@ -288,10 +322,31 @@
 request.errback { |response|
   puts "failed with status #{response.status_code}"
 }
 ```
 
+
+### Supplying an XHR method
+
+To supply an XHR callback include a lambda with the `xhr` option:
+
+```ruby
+update_progress = lambda do
+  xhr = `new window.XMLHttpRequest()`
+  update_progress = lambda do |evt|
+    # update your progress here
+  end
+  `xhr.upload.addEventListener("progress", update_progress, false)`
+  xhr
+end
+
+cloud_xfer = HTTP.put "http://my.cloud.storage/location", xhr: update_progress, ... etc ...
+```
+
+
+
+
 ## Usage of JQuery plugins
 Extra plugins used for JQuery aren't available to ruby code by default, you will have to `expose` these functions to opal-jquery.
 
 ```ruby
 Element.expose :cool_plugin
@@ -303,9 +358,10 @@
 Element.expose :cool_plugin
 
 el = Element['.html_element']
 el.cool_plugin({argument: 'value', argument1: 1000}.to_n)
 ```
+
 
 ##  License
 
 (The MIT License)