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

Returns a new instance of HTTP.



153
154
155
156
 
# File 'lib/opal/jquery/http.rb', line 153

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

Instance Attribute Details

#body ⇒ Object (readonly)

Returns the value of attribute body.



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

def body
  @body
end

#error_message ⇒ Object (readonly)

Returns the value of attribute error_message.



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

def error_message
  @error_message
end

#method ⇒ Object (readonly)

Returns the value of attribute method.



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

def method
  @method
end

#status_code ⇒ Object (readonly)

Returns the value of attribute status_code.



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

def status_code
  @status_code
end

#url ⇒ Object (readonly)

Returns the value of attribute url.



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

def url
  @url
end

#xhr ⇒ Object (readonly)

Returns the value of attribute xhr.



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

def xhr
  @xhr
end

Class Method Details

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




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

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

Create a HTTP get request.

Examples:

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

Parameters:

  • url (String) —

    url for request

  • options (Hash) (defaults to: {}) —

    any request options

Yields:

  • (self) —

    optional block to handle response

Returns:

  • (Promise, nil) —

    optionally returns a promise




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

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



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

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 129

.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

Parameters:

  • url (String) —

    url for request

  • options (Hash) (defaults to: {}) —

    optional request options

Yields:

  • (self) —

    optional block to yield for response

Returns:

  • (Promise, nil) —

    returns a Promise unless block given




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

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




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

.setup ⇒ Object 



143
144
145
 
# File 'lib/opal/jquery/http.rb', line 143

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

.setup=(settings) ⇒ Object 



147
148
149
 
# File 'lib/opal/jquery/http.rb', line 147

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

Instance Method Details

#get_header(key) ⇒ String?

Returns the value of the specified response header.

Parameters:

  • key (String) —

    name of the header to get

Returns:

  • (String) —

    value of the header

  • (nil) —

    if the header +key+ was not in the response



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

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

#inspect ⇒ Object 



236
237
238
 
# File 'lib/opal/jquery/http.rb', line 236

def inspect
  "#<HTTP @url=#{@url} @method=#{@method}>"
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, ... }

Returns:

  • (Hash, Array) —

    returns the parsed json



205
206
207
 
# File 'lib/opal/jquery/http.rb', line 205

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

Returns:

  • (true, false) —

    true if request was successful



220
221
222
 
# File 'lib/opal/jquery/http.rb', line 220

def ok?
  @ok
end

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



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
191
192
 
# File 'lib/opal/jquery/http.rb', line 158

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

  %x{
    if (typeof(payload) === 'string' || settings.processData === false) {
      settings.data = payload;
    }
    else if (payload != null) {
      settings.data = JSON.stringify(payload);
      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