sa-ajax

Ajax Implementation

An AMD compatible cross-browser, cross-domain Ajax implementation.

Run npm install to resolve dependencies.

Design Goals

• Must support IE 8/9.
• Must be able to load resources cross-domain.
• Must support text, json, and jsonp.
• Must be as lightweight as possible, ~4KB minified.

Use this library if you need to support IE8 (cross-domain) and want robust error handling by convention. Requires server-side code to respond following the convention for overriding the response status code and error messages see the server implementation notes.

Documentation

See the api documentation.

Test

Map the domain xdomain.socialal.ly in /etc/hosts:

127.0.0.1     xdomain.socialal.ly

And configure a reverse proxy, an example for nginx is available as xdomain.socialal.ly.conf.

Then run the tests in a browser:

1. npm start - Start the mock server.
2. Visit http://localhost:9080

Note that IE8 is not supported by chai so in order to test you need to visit:

http://localhost:9080/standalone.html

Minify

To create a minified version of the library run npm run minify.

Server Implementation

The server must at a minimum send the appropriate headers for CORS support, see server.js for example headers.

In addition, in order to support the XDomainRequest object for IE 8/9 the server must process requests that do not contain a Content-Type header and the client must know the type of data the server responds with.

To support error handling for instances when the http status code is not available the server should reply with a packet that contains code and error properties.

A successful 2xx response may be returned as:

{code: 202, message: "Request accepted"}

Whereas for an error the server could reply with:

{code: 400, error: {message: "Bad request"}}

The fields used for extracting status codes and error messages are configurable using the status and error options.

Browser Compatibility

Full Support

Full support is deemed to be browsers that can make cross domain requests and access the response headers:

• Chrome 18+
• Safari 6+
• Firefox 21+
• Opera 12+
• Internet Explorer 10+

Partial Support

• Chrome 14-17 and Safari 5/5.1 do not respect the Access-Control-Expose-Headers response header so assertions fail on the response headers.
• Firefox 4-20 do not expose cross domain response headers using getAllResponseHeaders().
• Internet Explorer 8/9 have many restrictions see XDomainRequest.

XDomainRequest (IE 8/9)

• Only GET and POST methods are allowed.
• Response headers are not available to browsers using the XDomainRequest object.
• The async option is ignored for XDomainRequest instances.
• Authentication credentials may not be used with XDomainRequest.
• XDomainRequest cannot set request headers, specifically no Content-Type header may be set.
• The response status code is not exposed by XDomainRequest.
• Requests must use the same protocol (http:// or https://) as the top-level window.

See XDomainRequest Limitations for more information.

Known Issues

• IE10 does not send cookies when withCredential=true IE Bug #759587

Appendix

Simple Headers

When a browser does not support exposing response headers only the following simple headers are accessible:

• Cache-Control
• Content-Language
• Content-Type
• Expires
• Last-Modified
• Pragma

Related Links

• XMLHttpRequest2
• XMLHttpRequest - Mozilla
• CORS
• XDomainRequest
• XDomainRequest Limitations
• XDomainRequest Quirks

License

MIT