Class: HTTP

Inherits:
Object
  • Object
show all
Defined in:
lib/opal/jquery/http.rb

Overview

HTTP is used to perform a XMLHttpRequest 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:

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. #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

Constant Summary collapse

ACTIONS =

All valid HTTP action methods this class accepts.

See Also:

%w[get post put delete patch head]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ HTTP 



151
152
153
154
 
# File 'lib/opal/jquery/http.rb', line 151

def initialize
  @settings = {}
  @ok = true
end

Instance Attribute Details

#body ⇒ Object (readonly)

Returns the value of attribute body.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def body
  @body
end

#error_message ⇒ Object (readonly)

Returns the value of attribute error_message.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def error_message
  @error_message
end

#method ⇒ Object (readonly)

Returns the value of attribute method.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def method
  @method
end

#status_code ⇒ Object (readonly)

Returns the value of attribute status_code.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def status_code
  @status_code
end

#url ⇒ Object (readonly)

Returns the value of attribute url.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def url
  @url
end

#xhr ⇒ Object (readonly)

Returns the value of attribute xhr.



149
150
151
 
# File 'lib/opal/jquery/http.rb', line 149

def xhr
  @xhr
end

Class Method Details

.delete(url, options = {}, &block) ⇒ Object 




# File 'lib/opal/jquery/http.rb', line 125

.get(url, options = {}) {|self| ... } ⇒ Promise?

Create a HTTP get request.

Examples:

HTTP.get("/foo") do |req|
  puts "got data: #{req.data}"
end

Yields:

  • (self) —

    optional block to handle response




# File 'lib/opal/jquery/http.rb', line 93

.head(url, options = {}, &block) ⇒ Object 



131
132
133
134
135
136
137
138
139
 
# File 'lib/opal/jquery/http.rb', line 131

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

.patch(url, options = {}, &block) ⇒ Object 




# File 'lib/opal/jquery/http.rb', line 127

.post(url, options = {}) {|self| ... } ⇒ Promise?

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.

Examples:

HTTP.post("/bar", payload: data) do |req|
  puts "got response"
end

Yields:

  • (self) —

    optional block to yield for response




# File 'lib/opal/jquery/http.rb', line 107

.put(url, options = {}, &block) ⇒ Object 




# File 'lib/opal/jquery/http.rb', line 123

.setup ⇒ Object 



141
142
143
 
# File 'lib/opal/jquery/http.rb', line 141

def self.setup
  Hash.new(`$.ajaxSetup()`)
end

.setup=(settings) ⇒ Object 



145
146
147
 
# File 'lib/opal/jquery/http.rb', line 145

def self.setup= settings
  `$.ajaxSetup(#{settings.to_n})`
end

Instance Method Details

#get_header(key) ⇒ String?

Returns the value of the specified response header.



227
228
229
230
231
232
 
# File 'lib/opal/jquery/http.rb', line 227

def get_header(key)
  %x{
    var value = #@xhr.getResponseHeader(#{key});
    return (value === null) ? nil : value;
  }
end

#json ⇒ Hash, Array

Parses the http response body through json. If the response is not valid JSON then an error will very likely be thrown.

Examples:

Getting JSON content

HTTP.get("api.json") do |response|
  puts response.json
end

# => {"key" => 1, "bar" => 2, ... }



203
204
205
 
# File 'lib/opal/jquery/http.rb', line 203

def json
  @json ||= JSON.parse(@body)
end

#ok? ⇒ true, false

Returns true if the request succeeded, false otherwise.

Examples:

HTTP.get("/some/url") do |response|
  if response.ok?
    alert "Yay!"
  else
    alert "Aww :("
  end



218
219
220
 
# File 'lib/opal/jquery/http.rb', line 218

def ok?
  @ok
end

#send(method, url, options, block) ⇒ Object 



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/opal/jquery/http.rb', line 156

def send(method, url, options, block)
  @method   = method
  @url      = url
  @payload  = options.delete :payload
  @handler  = block

  @settings.update options

  settings, payload = @settings.to_n, @payload

  %x{
    if (typeof(#{payload}) === 'string') {
      #{settings}.data = payload;
    }
    else if (payload != nil) {
      settings.data = payload.$to_json();
      settings.contentType = 'application/json';
    }

    settings.url  = #@url;
    settings.type = #{@method.upcase};

    settings.success = function(data, status, xhr) {
      return #{ succeed `data`, `status`, `xhr` };
    };

    settings.error = function(xhr, status, error) {
      return #{ fail `xhr`, `status`, `error` };
    };

    $.ajax(settings);
  }

  @handler ? self : promise
end