README.md

AJacks

Includes support for xmlHttpRequest, JSONP, CORS, and CommonJS Promises A.

It is also isomorphic allowing you to require('ajacks') in Node.js through the peer dependency xhr2, albeit the original intent of this library is for the browser. For a more thorough solution for Node.js, see mikeal/request.

API

Ajacks('path/to/html', function (resp) {
  qwery('#content').html(resp)
})

Ajacks({
    url: 'path/to/html'
  , method: 'post'
  , data: { foo: 'bar', baz: 100 }
  , success: function (resp) {
      qwery('#content').html(resp)
    }
})

Ajacks({
    url: 'path/to/html'
  , method: 'get'
  , data: [ { name: 'foo', value: 'bar' }, { name: 'baz', value: 100 } ]
  , success: function (resp) {
      qwery('#content').html(resp)
    }
})

Ajacks({
    url: 'path/to/json'
  , type: 'json'
  , method: 'post'
  , error: function (err) { }
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

Ajacks({
    url: 'path/to/json'
  , type: 'json'
  , method: 'post'
  , contentType: 'application/json'
  , headers: {
      'X-My-Custom-Header': 'SomethingImportant'
    }
  , error: function (err) { }
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

// Uses XMLHttpRequest2 credentialled requests (cookies, HTTP basic auth) if supported
Ajacks({
    url: 'path/to/json'
  , type: 'json'
  , method: 'post'
  , contentType: 'application/json'
  , crossOrigin: true
  , withCredentials: true
  , error: function (err) { }
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

Ajacks({
    url: 'path/to/data.jsonp?callback=?'
  , type: 'jsonp'
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

Ajacks({
    url: 'path/to/data.jsonp?foo=bar'
  , type: 'jsonp'
  , jsonpCallback: 'foo'
  , jsonpCallbackName: 'bar'
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

Ajacks({
    url: 'path/to/data.jsonp?foo=bar'
  , type: 'jsonp'
  , jsonpCallback: 'foo'
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
  , complete: function (resp) {
      qwery('#hide-this').hide()
    }
})

Promises

Ajacks({
    url: 'path/to/data.jsonp?foo=bar'
  , type: 'jsonp'
  , jsonpCallback: 'foo'
})
  .then(function (resp) {
    qwery('#content').html(resp.content)
  }, function (err, msg) {
    qwery('#errors').html(msg)
  })
  .always(function (resp) {
    qwery('#hide-this').hide()
  })

Ajacks({
    url: 'path/to/data.jsonp?foo=bar'
  , type: 'jsonp'
  , jsonpCallback: 'foo'
})
  .then(function (resp) {
    qwery('#content').html(resp.content)
  })
  .fail(function (err, msg) {
    qwery('#errors').html(msg)
  })
  .always(function (resp) {
    qwery('#hide-this').hide()
  })

var r = Ajacks({
    url: 'path/to/data.jsonp?foo=bar'
  , type: 'jsonp'
  , jsonpCallback: 'foo'
  , success: function () {
      setTimeout(function () {
        r
          .then(function (resp) {
            qwery('#content').html(resp.content)
          }, function (err) { })
          .always(function (resp) {
             qwery('#hide-this').hide()
          })
      }, 15)
    }
})

Options

• url a fully qualified uri
• method http method (default: GET)
• headers http headers (default: {})
• data entity body for PATCH, POST and PUT requests. Must be a query String or JSON object
• type a string enum. html, xml, json, or jsonp. Default is inferred by resource extension. Eg: .json will set type to json. .xml to xml etc.
• contentType sets the Content-Type of the request. Eg: application/json
• crossOrigin for cross-origin requests for browsers that support this feature.
• success A function called when the request successfully completes
• error A function called when the request fails.
• complete A function called whether the request is a success or failure. Always called when complete.
• jsonpCallback Specify the callback function name for a JSONP request. This value will be used instead of the random (but recommended) name automatically generated by Ajacks.

Security

If you are still requiring support for IE6/IE7, consider including JSON3 in your project. Or simply do the following

<script>
(function () {
  if (!window.JSON) {
    document.write('<scr' + 'ipt src="http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"><\/scr' + 'ipt>')
  }
}());
</script>

Contributing

$ git clone git://github.com/StuDocu/ajacks.git ajacks
$ cd !$
$ npm install

Please keep your local edits to src/ajacks.js. The base ./ajacks.js and ./ajacks.min.js will be built upon releases.

Running Tests

make test

Browser support

• IE6+
• Chrome 1+
• Safari 3+
• Firefox 1+
• Opera

ajaxSetup

Use the request.ajaxSetup to predefine a data filter on all requests. See the example below that demonstrates JSON hijacking prevention:

$.ajaxSetup({
  dataFilter: function (response, type) {
    if (type == 'json') return response.substring('])}while(1);</x>'.length)
    else return response
  }
})

You can also specify headers to be sent on each request:

$.ajaxSetup({
  headers: {
    'X-CSRF-Token': '12abcDEFGHIJkLmN3OPQrS45tUVWxY67zabc8Def'
  }
})

jQuery and Zepto Compatibility

There are some differences between the Ajacks way and the jQuery/Zepto way.

method

jQuery/Zepto use type to specify the request method while Ajacks uses method and reserves type for the response data type.

dataType

When using jQuery/Zepto you use the dataType option to specify the type of data to expect from the server, Ajacks uses type. jQuery also can also take a space-separated list of data types to specify the request, response and response-conversion types but Ajacks uses the type parameter to infer the response type and leaves conversion up to you.

JSONP

Ajacks also takes optional jsonpCallback and jsonpCallbackName options to specify the callback query-string key and the callback function name respectively while jQuery uses jsonp and jsonpCallback for these same options.

But fear not! If you must work the jQuery/Zepto way then Ajacks has a wrapper that will remap these options for you:

Ajacks.compat({
    url: 'path/to/data.jsonp?foo=bar'
  , dataType: 'jsonp'
  , jsonp: 'foo'
  , jsonpCallback: 'bar'
  , success: function (resp) {
      qwery('#content').html(resp.content)
    }
})

**Happy Ajaxing!**