better-xhr
Better abstraction for XMLHttpRequest
The goal for the project is to create simple to use, lightweight and Promise-based implementation for working with AJAX.
API
XHR.get("/test/url").then(function(response) {
// do something with response
});
XHR.post("/test/modify/url", {data: {a: "b"}}).then(successCallback, errorCallback);
// or general method
XHR(method, url, config).then(success, fail);Global XHR function returns a Promise object. Check out the article HTML5Rocks article for details on it's API.
Installing
Use bower to download the library with all required dependencies.
bower install better-xhr
This will clone the latest version of the better-xhr into the bower_components directory at the root of your project.
Then just append the following scripts on your page:
<script src="bower_components/better-xhr/dist/better-xhr.js"></script>NOTE: for browsers that don't have a Promise yet, include a polyfill.
Configuration
You can modify XMLHttpRequest settings via properties of the config object.
| Property | Type | Description |
|---|---|---|
data |
Object or String
|
Specifies data that you want to send in AJAX request. An object value is serialized via query string algorithm. For GET requests data argument is appended directly to the request URL.For non- GET requests it will be passed into the XMLHttpRequest#send call.Adds "Content-Type" header with value "application/x-www-form-urlencoded" for non-GET requests |
json |
Object or String
|
Specifies JSON data for AJAX request. An object value is serialized via JSON.stringify. Adds "Content-Type" header with value "application/json"
|
headers |
Object |
Specifies extra HTTP headers for request. You can drop any default header via setting it to null
|
cacheBurst |
String |
Cache bursting parameter. Allows to specify name of the extra dummy argument that disables caching. Default value: "_"
|
timeout |
Number |
The argument specifies request timeout in miliseconds. Default value: 15000
|
charset |
String |
Specifies character encoding. Default value: "UTF-8"
|
emulateHTTP |
String |
Truthy value specifies name of the extra URL parameter to emulate additional HTTP methods for older servers. Also triggers setting of the X-HTTP-Method-Override header to the appropriate value before sending an AJAX request. |
mimeType |
String |
Used to specify returned data type and to override value of the Content-Type header which is used by default to understand how to parse response.Has several shortcuts: json, text. |
Method serialize
The plugin introduces static method XHR.serialize. This method can be used to collect a form data for AJAX requests. Returned object is a key/value map of form elements. For example
<form id="myform" action="/some-url">
<input type="text" name="user" value="user1">
<select name="gender">
<option value="m" selected>Male</option>
<option value="f">Female</option>
</select>
</form>can be serialized like below:
XHR.serialize(document.getElementById("myform"));
// => {user: "user1", "gender": "m"}Defaults
XHR.defaults object contains all predefined default values. You can modify them on demand. For example:
// set default timeout to 10 seconds
XHR.defaults.timeout = 10000;
// add custom header for each request
XHR.defaults.headers["Authorization"] = "Basic Zm9vOmJhcg==";Browser support
Desktop
- Chrome
- Safari 6.0+
- Firefox 16+
- Internet Explorer 8+
- Opera 12.10+
Mobile
- iOS Safari 6+
- Android 2.3+
- Chrome for Android
NOTE: for IE8-9 cross-domain requests are not supported because of limited capabilities of legacy XDomainRequest object.
