maccman/spine — pull request #328 by metaskills (2012-06-15 15:15:07+00:00)
Title: Update Spine.Ajax's Queue To Return Promise Objects.

Original issue #300.

Use jqXHR.done(), jqXHR.fail(), and jqXHR.always() to future-proof for jQuery 1.8's deprecation of jqXHR.success(), jqXHR.error(), and jqXHR.complete() callbacks. This means Spine.JS is now technically jQuery 1.5 and up compatibile.

* Renamed private errorResponse() to failResponse()

* Maintained the "success" and "error" options since these can still be easily supported. However, you could choose to deprecate these and promote the use of the promise objects returned now.

* Maintained the "ajaxSuccess" and "ajaxError" event names. I guess the Singleton versions of these now play a smaller role given the alternative now. That said, I think these may always play a role? Perhaps even update the names to "spine.ajax.done" and "spine.ajax.fail" one day since they follow the proper event namespace conventions of jQuery.

Previously the `Collection` find and all were not using the queue, they are now so this will avoid race conditions too.

The `Spine.Ajax.requests` is gone as well as the practice of using `Spine.Ajax.requests = []` to empty the queue. I have added a `Spine.Ajax.clearQueue()` function that replaces the queue with an empty array per jQuery docs. If we wanted to, we could mirror all promise objects created via `ajaxQueue` in a array at `Spine.Ajax.requests` and call `abort()` on all of them instead via the `clearQueue` implementation. Your call or thoughts welcome.

Added a mirror options check in the private callbacks so that "options.done" can work while deprecating via a comment the "options.success" practice. Likewise, added a "options.fail" to mirror "options.error". If you want to remove the old options keys one day, we can simply change the tests to use the new done/fail keys.

I fixed the indentation of half the "it" examples in ajax.js.

Here are some ideas on places where the docs will need to be changed.

Ajax integration
http://spinejs.com/docs/ajax

* Callbacks - The last paragraph that says "If you need more
control..."
could be removed/changed to

* Custom requests - Could include examples

* Ajax queue - This is both an accessor for the queue and way to put in callbacks.
```
Spine.Ajax.queue ->
$.post("/posts/custom")
```

* Disabling Ajax -
(demo custom requests here too?)
`@ajax().update(params).done(@startDone)`