**********
score.ajax
**********
.. _js_ajax:
A small helper for managing AJAX requests.
Quickstart
==========
.. code-block:: html
Details
=======
Return value
------------
The return value of this function depends on the `Content-Type`_ header of the
server response. You can find a good documentation of the
`XMLHttpRequest.response`_ types on MDN.
.. _Content-Type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17
.. _XMLHttpRequest.response: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response
Callback
--------
Internet explorer does not provide promises_, you will either have to use a
polyfill, or use the callback-based API of this module:
.. code-block:: javascript
score.ajax.callback('/api/fruits', function(result) {
for (var i = 0; i < result.length; i++) {
console.log('Initiating self-defense against ' + result[i]);
}
}, function() {
// this is the error callback
alert('Could not load fruits, nothing to defend against!');
});
If you are passing any options, you must provide them *before* the callback:
.. code-block:: javascript
score.ajax.callback('/api/fruits', {headers: {'X-Spam': 'spam!'}}, function(result) {
...
.. _promises: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
Options
-------
You can pass an options object after the URL. The following keys are currently
supported:
* ``method``: An HTTP verb to use (i.e. "POST", "PUT", etc.) Defaults to "GET".
* ``data``: The body of the request. Can be anything accepted by
`XMLHttpRequest.send()`_
* ``headers``: An object mapping HTTP headers to values. These will be sent as
part of the request. Note that you cannot set certain headers (you can find
the `list of forbidden headers`_ on MDN). Also note, that it is also possible
to perform `cross-domain AJAX requests`_, albeit with heavy restrictions.
* ``crossDomain``: By default the `'X-Requested-With': 'XMLHttpRequest'` header
will always be set. Setting this value to `true` will override that
behaviour.
.. _CROSS-domain AJAX requests: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
.. _list of forbidden headers: https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name
.. _XMLHttpRequest.send(): https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/send