1 | ic-ajax
|
2 | =======
|
3 |
|
4 | [![Build Status](https://travis-ci.org/instructure/ic-ajax.png)](https://travis-ci.org/instructure/ic-ajax)
|
5 |
|
6 | Ember-friendly `jQuery.ajax` wrapper.
|
7 |
|
8 | - returns RSVP promises
|
9 | - makes apps more testable (resolves promises with `Ember.run`)
|
10 | - makes testing ajax simpler with fixture support
|
11 |
|
12 | Installation
|
13 | ------------
|
14 |
|
15 | `bower install ic-ajax`
|
16 |
|
17 | ... or ...
|
18 |
|
19 | `npm install ic-ajax`
|
20 |
|
21 | Module Support
|
22 | --------------
|
23 |
|
24 | Note the `dist` directory has multiple module formats, use whatever
|
25 | works best for you.
|
26 |
|
27 | - AMD
|
28 |
|
29 | `define(['ic-ajax'], function(ajax) {});`
|
30 |
|
31 | - Node.JS (CJS)
|
32 |
|
33 | `var ajax = require('ic-ajax')`
|
34 |
|
35 | - Globals
|
36 |
|
37 | `var ajax = ic.ajax;`
|
38 |
|
39 | All instructure canvas stuff lives on the `ic` global.
|
40 |
|
41 | API
|
42 | ---
|
43 |
|
44 | This lib simply wraps `jQuery.ajax` with two exceptions:
|
45 |
|
46 | - success and error callbacks are not supported
|
47 | - does not resolve three arguments like $.ajax (real promises only
|
48 | resolve a single value). `request` only resolves the response data
|
49 | from the request, while `raw` resolves an object with the three
|
50 | "arguments" as keys if you need them.
|
51 |
|
52 | Other than that, use `request` exactly like `$.ajax`.
|
53 |
|
54 | ```js
|
55 | var ajax = ic.ajax;
|
56 |
|
57 | App.ApplicationRoute = Ember.Route.extend({
|
58 | model: function() {
|
59 | return ajax.request('/foo');
|
60 | }
|
61 | }
|
62 |
|
63 | // if you need access to the jqXHR or textStatus, use raw
|
64 | ajax.raw('/foo').then(function(result) {
|
65 | // result.response
|
66 | // result.textStatus
|
67 | // result.jqXHR
|
68 | });
|
69 | ```
|
70 |
|
71 | Simplified Testing
|
72 | ------------------
|
73 |
|
74 | Adding fixtures with `defineFixture` tells ic-ajax to resolve the promise
|
75 | with the fixture matching a url instead of making a request. This allows
|
76 | you to test your app without creating fake servers with sinon, etc.
|
77 |
|
78 | Example:
|
79 |
|
80 | ```js
|
81 | ic.ajax.defineFixture('api/v1/courses', {
|
82 | response: [{name: 'basket weaving'}],
|
83 | jqXHR: {},
|
84 | textStatus: 'success'
|
85 | });
|
86 |
|
87 | ic.ajax.request('api/v1/courses').then(function(result) {
|
88 | deepEqual(result, ic.ajax.lookupFixture('api/v1/courses').response);
|
89 | });
|
90 | ```
|
91 |
|
92 | To test failure paths, set the `textStatus` to anything but `success`.
|
93 |
|
94 | Contributing
|
95 | ------------
|
96 |
|
97 | Install dependencies and run tests with the following:
|
98 |
|
99 | ```sh
|
100 | npm install
|
101 | npm test
|
102 | ```
|
103 |
|
104 | Special Thanks
|
105 | --------------
|
106 |
|
107 | Inspired by [discourse ajax][1].
|
108 |
|
109 | License and Copyright
|
110 | ---------------------
|
111 |
|
112 | MIT Style license
|
113 |
|
114 | (c) 2014 Instructure, Inc.
|
115 |
|
116 |
|
117 | [1]:https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/mixins/ajax.js#L19
|
118 |
|