Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
23 additions
and
53 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,63 +1,33 @@ | ||
| # jQuery.continutions | ||
| # jquery.continuations | ||
|
|
||
| ## Overview | ||
| ## First things first | ||
| The first thing you need to know is what an Ajax Continuation actually is. [You can read about them here](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Continuation-object). | ||
|
|
||
| jQuery.continuations provides a standarized way of processing Ajax responses via [the Continuation object](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Continuation-object). The idea is that for most cases, | ||
| your server side code will be generated responses that are similar in structure and you want to build a conventional approach to processing those requests. | ||
| ## Now, let's talk about the pipeline | ||
| The continuation objects are processed by what we call our "pipeline" of policies. It tends to make more sense if you read about the pipeline before the policies themselves. [You can read all about that here](https://github.com/DarthFubuMVC/jquery-continuations/wiki/The-Continuation-Pipeline). | ||
|
|
||
| ## How it works | ||
| ## Cool, now what's a policy? | ||
| Their structure is simple but they're extremely powerful. [Go here to find out why](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Continuation-policy). | ||
|
|
||
| jQuery.continuations hooks into jQuery via the $.ajaxSetup method and provides a global success callback. The callback that is registered kicks off the | ||
| $.continuations.process pipeline. | ||
| ## How do I make my own? | ||
| See [Creating a custom policy](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Creating-a-custom-policy) | ||
|
|
||
| ## Processing pipeline | ||
| ## USEFUL (more advanced) topics | ||
| A few other things that you should know about jquery.continuations: | ||
| * [correlatedSubmit does a lot of work for you](https://github.com/DarthFubuMVC/jquery-continuations/wiki/correlatedSubmit) | ||
| * [You can specify custom properties](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Using-custom-properties) | ||
|
|
||
| The processing pipeline is orchestrated through [continuation policies](https://github.com/DarthFubuMVC/jquery-continuations/wiki/Continuation-policy). jQuery.continuations comes with several policies that are registered by default: | ||
| ### Additional Reading | ||
|
|
||
| **errorPolicy** | ||
| Some links for more information on jquery.continuations: | ||
|
|
||
| (_Matches when the error collection is not empty_) | ||
| * http://lostechies.com/josharnold/2012/01/06/our-ajax-conventions-the-ajaxcontinuation/ | ||
| * http://lostechies.com/josharnold/2012/01/06/our-ajax-conventionsclientside-continuations/ | ||
| * http://lostechies.com/josharnold/2012/01/07/our-ajax-conventionsrequest-correlation/ | ||
| * http://lostechies.com/josharnold/2012/01/08/our-ajax-conventionsvalidation/ | ||
|
|
||
| Publishes 'ContinuationError' topic through amplifyjs | ||
| ### Dependencies | ||
|
|
||
| **refreshPolicy** | ||
|
|
||
| (_Matches when the refresh property is true_) | ||
|
|
||
| Simply refreshes the page | ||
|
|
||
| **navigatePolicy** | ||
|
|
||
| (_Matches when the url property is not empty_) | ||
|
|
||
| Navigates the window to the specified url | ||
|
|
||
| **payloadPolicy** | ||
|
|
||
| (_Matches when the following properties exist: payload, topic_) | ||
|
|
||
| Publishes the specified topic and payload through amplifyjs | ||
|
|
||
| ## Request Correlation | ||
|
|
||
| Before each request is initiated, a custom header is appended (X-Correlation-Id). This value originates from one of two sources: 1) randomly assigned for a request 2) the id of the form responsible for the request. | ||
|
|
||
| > Note: It's up to your web framework to handle setting the header into its response. | ||
| Assuming that you are sending the header back down through your response, jquery.continuations handles it from there by doing two things: | ||
|
|
||
| **The AjaxCompleted topic** | ||
|
|
||
| This topic is published through the jquery.continuations event aggregator facade (we use amplify). The message that is published contains a correlationId property with the appropriate value. | ||
|
|
||
| **The continuation processing pipeline** | ||
|
|
||
| Before the continuation is processed, the correlationId property is set. | ||
|
|
||
| > jQuery.continuations also integrates with jquery.form by providing a correlatedSubmit method to any form ($('#myForm').correlatedSubmit()) | ||
| ## Custom Policies | ||
|
|
||
| An example of how to register a custom policy: | ||
|
|
||
| > $.continuations.applyPolicy({ custom policy... }) | ||
| * jquery.continuations.js a dependency on jQuery (>= 1.6.2). | ||
| * jQuery.continuations.forms.js has a dependency on jquery.continuation.js and jQuery.form (>= 2.94) | ||
| * jQuery.continuations.amplify.js has a dependency on jquery.continuations.js and amplify.core.js (>= 1.1.0) |