opal · Dec 6, 2014 · Dec 6, 2014
Showing with 146 additions and 38 deletions.

+1 −0 .gitignore

+1 −0 .yardopts

+144 −38 opal/opal-jquery/http.rb
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ build
 gh-pages
 /.bundle
 .yardoc
+/doc
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1 @@
+opal/**/*.rb
diff --git a/opal/opal-jquery/http.rb b/opal/opal-jquery/http.rb
@@ -3,61 +3,168 @@
 require 'promise'
 require 'opal-jquery/constants'
 
+# {HTTP} is used to perform +XMLHttpRequest+s in ruby. It is a simple wrapper
+# around jQuerys' +$.ajax+ call. +XMLHttpRequest+ is not wrapped directly as
+# jquery provides some cross browser fixes.
+#
+# = Making requests
+#
+# To create a simple request, {HTTP} exposes class level methods to specify
+# the HTTP action you wish to perform. Each action accepts the url for the
+# request, as well as optional arguments passed as a hash:
+#
+#     HTTP.get("/users/1.json")
+#     HTTP.post("/users", payload: data)
+#
+# The supported +HTTP+ actions are:
+#
+# * {HTTP.get}
+# * {HTTP.post}
+# * {HTTP.put}
+# * {HTTP.delete}
+# * {HTTP.patch}
+# * {HTTP.head}
+#
+# = Handling responses
+#
+# Responses can be handled using either a simple block callback, or using a
+# {Promise} returned by the request.
+#
+# == Using a block
+#
+# All HTTP action methods accept a block which can be used as a simple
+# handler for the request. The block will be called for both successful as well
+# as unsuccessful requests.
+#
+#     HTTP.get("/users/1") do |request|
+#       puts "the request has completed!"
+#     end
+#
+# This +request+ object will simply be the instance of the {HTTP} class which
+# wraps the native +XMLHttpRequest+. {HTTP#ok?} can be used to quickly determine
+# if the request was successful.
+#
+#     HTTP.get("/users/1") do |request|
+#       if request.ok?
+#         puts "request was success"
+#       else
+#         puts "something went wrong with request"
+#       end
+#     end
+#
+# The {HTTP} instance will always be the only object passed to the block.
+#
+# == Using a Promise
+#
+# If no block is given to one of the action methods, then a {Promise} is
+# returned instead. See the standard library for more information on Promises.
+#
+#     HTTP.get("/users/1").then do |req|
+#       puts "response ok!"
+#     end.fail do |req|
+#       puts "response was not ok"
+#     end
+#
+# When using a {Promise}, both success and failure handlers will be passed the
+# {HTTP} instance.
+#
+# = Accessing Response Data
+#
+# All data returned from an HTTP request can be accessed via the {HTTP} object
+# passed into the block or promise handlers.
+#
+# * {#ok?} - returns +true+ or +false+, if request was a success (or not).
+# * {#body} - returns the raw text response of the request
+# * {#status_code} - returns the raw {HTTP} status code as integer
+# * {#json} - tries to convert the body response into a JSON object
 class HTTP
   `var $ = #{JQUERY_SELECTOR.to_n}` # cache $ for SPEED
 
-  def self.setup
-    Hash.new(`$.ajaxSetup()`)
-  end
+  # All valid {HTTP} action methods this class accepts.
+  #
+  # @see HTTP.get
+  # @see HTTP.post
+  # @see HTTP.put
+  # @see HTTP.delete
+  # @see HTTP.patch
+  # @see HTTP.head
+  ACTIONS = %w[get post put delete patch head]
 
-  def self.setup= settings
-    `$.ajaxSetup(#{settings.to_n})`
-  end
+  # @!method self.get(url, options = {}, &block)
+  #
+  # Create a {HTTP} +get+ request.
+  #
+  # @example
+  #   HTTP.get("/foo") do |req|
+  #     puts "got data: #{req.data}"
+  #   end
+  #
+  # @param url [String] url for request
+  # @param options [Hash] any request options
+  # @yield [self] optional block to handle response
+  # @return [Promise, nil] optionally returns a promise
 
-  attr_reader :body, :error_message, :method, :status_code, :url, :xhr
+  # @!method self.post(url, options = {}, &block)
+  #
+  # Create a {HTTP} +post+ request. Post data can be supplied using the
+  # +payload+ options. Usually this will be a hash which will get serialized
+  # into a native javascript object.
+  #
+  # @example
+  #   HTTP.post("/bar", payload: data) do |req|
+  #     puts "got response"
+  #   end
+  #
+  # @param url [String] url for request
+  # @param options [Hash] optional request options
+  # @yield [self] optional block to yield for response
+  # @return [Promise, nil] returns a {Promise} unless block given
 
-  def self.get(url, opts={}, &block)
-    send(:get, url, opts, &block)
-  end
+  # @!method self.put(url, options = {}, &block)
 
-  def self.post(url, opts={}, &block)
-    send(:post, url, opts, &block)
-  end
+  # @!method self.delete(url, options = {}, &block)
 
-  def self.put(url, opts={}, &block)
-    send(:put, url, opts, &block)
-  end
+  # @!method self.patch(url, options = {}, &block)
+
+  # @!method self.head(url, options = {}, &block)
 
-  def self.delete(url, opts={}, &block)
-    send(:delete, url, opts, &block)
+  ACTIONS.each do |action|
+    define_singleton_method(action) do |url, options = {}, &block|
+      new.send(action, url, options, block)
+    end
+
+    define_method(action) do |url, options = {}, &block|
+      send(action, url, options, block)
+    end
   end
 
-  def self.patch(url, opts={}, &block)
-    send(:patch, url, opts, &block)
+  def self.setup
+    Hash.new(`$.ajaxSetup()`)
   end
 
-  def self.head(url, opts={}, &block)
-    send(:head, url, opts, &block)
+  def self.setup= settings
+    `$.ajaxSetup(#{settings.to_n})`
   end
 
-  def self.send(method, url, options, &block)
-    new(method, url, options, &block).send
+  attr_reader :body, :error_message, :method, :status_code, :url, :xhr
+
+  def initialize
+    @settings = {}
+    @ok = true
   end
 
-  def initialize(method, url, options={}, &handler)
+  def send(method, url, options, block)
     @method   = method
     @url      = url
-    @ok       = true
     @payload  = options.delete :payload
-    @settings = options
-    @handler  = handler
-  end
+    @handler  = block
 
-  def send(payload=@payload)
-    settings = @settings.to_n
+    @settings.update options
+
+    settings, payload = @settings.to_n, @payload
 
     %x{
-      if (typeof(payload) === 'string') {
+      if (typeof(#{payload}) === 'string') {
         #{settings}.data = payload;
       }
       else if (payload != nil) {
@@ -85,17 +192,16 @@ def send(payload=@payload)
   # Parses the http response body through json. If the response is not
   # valid JSON then an error will very likely be thrown.
   #
-  # @example
-  #   # Getting JSON content
+  # @example Getting JSON content
   #   HTTP.get("api.json") do |response|
   #     puts response.json
   #   end
   #
   #   # => {"key" => 1, "bar" => 2, ... }
   #
-  # @return [Object] returns the parsed json
+  # @return [Hash, Array] returns the parsed json
   def json
-    @json || JSON.parse(@body)
+    @json ||= JSON.parse(@body)
   end
 
   # Returns true if the request succeeded, false otherwise.
@@ -108,14 +214,14 @@ def json
   #       alert "Aww :("
   #     end
   #
-  # @return [Boolean] true if request was successful
+  # @return [true, false] true if request was successful
   def ok?
     @ok
   end
 
   # Returns the value of the specified response header.
   #
-  # @param [String] name of the header to get
+  # @param key [String] name of the header to get
   # @return [String] value of the header
   def get_header(key)
     `#@xhr.getResponseHeader(#{key});`
-Original file line number
+Diff line change
@@ @@ -5,3 +5,4 @@ build @@
     gh-pages
     /.bundle
     .yardoc
+    /doc