jquery-ajax-chain v1.0.8

jQuery Ajax Chain

The $.AjaxChain jQuery helper class allows to perform multiple synchronously chained Ajax calls; its optional settings make possible to filter data and pass it between succeeding calls, manage custom errors, create caching mechanisms and conditionally halt queue progression.

Documentation

Note: although being written in plain JavaScript, this library adopts the TypeScript interface definition standard to document its features.

Constructor

Public methods

Callback functions arguments

Note: differently from the original jQuery implementation, callbacks specified as arguments of then(), done(), fail(), always() methods get passed an array of responses: [response[,responseN, ...]]. Furthermore, callbacks specified as arguments of progress() method get passed an object structured as follows:

Configuration object

Note: All functions specified as values of optional configuration object properties (marked with a question mark) are passed the dequeued Ajax call response as argument.

Examples

Typical setup

var ajaxChain = new $.AjaxChain();
ajaxChain.enqueue([configurationObject[,configurationObjectN, ... ]])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

Common configuration patterns

<!-- The succeeding examples assume the following xml response: -->

<?xml version = "1.0"?>
<items>
    <item id="000001">
        <name>Item #1</name>
        <categoryId>1</categoryId>
    </item>
    <item id="000002">
        <name>Item #2</name>
        <categoryId>2</categoryId>
    </item>
    <item id="000003">
        <name>Item #3</name>
        <categoryId>3</categoryId>
    </item>
</items>

1. Dynamically passing data between succeeding Ajax calls:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
   },
   transform: function(xmlResponse){
        var nextCallDataObj;
        if (xmlResponse) {
            nextCallDataObj = {
                id: $(xmlResponse).find('item')
                                  .first().attr('id')
            };                   
            return nextCallDataObj;               
        }                  
        return false;              
   }
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

2. Dynamically appending url fragments between succeeding Ajax calls:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
    },
    appendToUrl: function(xmlResponse){
        var nextCallUrlFragment = "";
        if (xmlResponse) {
            nextCallUrlFragment = "/" + $(xmlResponse).find('item')
                                                      .first()
                                                      .attr('id');
        };                 
        return nextCallUrlFragment;               
    }               
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

3. Dynamically resolving queue upon custom errors:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
    },
    hasErrors: function(xmlResponse){
        var $tempXmlResponse,
            categoryFilter = "1";
        $tempXmlResponse = $(xmlResponse);
        // check current Ajax call response for errors
        if ($tempXmlResponse.find("item").eq(0)
                            .find("categoryId")
                            .text()
                            .indexOf(categoryFilter) !== -1) {
            return "[Exception] forbidden category id: " + categoryFilter;
        }
        return false;         
   }
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

4. Creating caching mechanisms:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
    },
    hasCache: function(xmlResponse){  
        // retrieve possible cached results
        if (itemsCollection.length) {
            return itemsCollection.toJSON();
        }
        return false;     
    }
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

5. Halting queue upon conditional logic:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
    },
    hasHaltingCapabilities: function(xmlResponse){
        var $tempXmlResponse;
        $tempXmlResponse = $(xmlResponse);
        if ($tempXmlResponse.find("item").eq(0)
                            .find("categoryId")
                            .text().indexOf("1") !== -1) {
            return true;
        }
        return false;        
    }
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

6. Preventing a queue from being halted in case of $.Ajax error:

var ajaxChain,
    configurationObj1,
    configurationObj2;
ajaxChain = new $.AjaxChain();
configurationObj1 = {
    ajaxSettings: {
        type: "GET",
        dataType: "xml",
        url: "/items"
    },
    isSkippable: function(xmlResponse){
        return true;
    }
};
// configuration object omitted for brevity
configurationObj2 = { . . . };
ajaxChain.enqueue([configurationObj1, configurationObj2])
         .dequeue()
         .then(doneCallback, failCallback, progressCallback);

TypeScript

Visual Studio (NuGet)

1. Open the Package Manager Console
2. Install-Package jquery-ajax-chain.TypeScript.DefinitelyTyped

Node.js (TSD)

1. Open a shell in your project's scripts folder
2. npm install tsd -g
3. tsd install jquery-ajax-chain --save

Testing

Headless

1. Open a shell in the package root folder
2. npm install
3. bower install
4. grunt test:headless

Browser

1. Open a shell in the package root folder
2. npm install
3. bower install
4. grunt test:browser (--port option available, e.g.: grunt test:browser --port=8083)

Note: this project was packaged with grunt-init-jquery.