Documentation

1 Getting Started
2 Design Overview
3 Page Controller Boot Process
4 Your First App
5 Page Controller
6 Modules
7 Components
8 jqcEmpty
9 jqcLabel
10 jqcButton
11 jqcLayer
12 jqcPanelDeck
13 jqcAccordion
14 jqcProgressBar
15 Data Binding & Remote Data Synchronization
16 jqcDataService
17 jqcDataModel
18 jqcViewModel
19 jqcList
20 jqcTable
21 jqcForm
22 jqcResponsiveLayoutManager
23 jqcTreeList
24 Demos

jqcDataService


This document matches version 1.6.0 .

The jqcDataService component represents a remote data service. The component works as a proxy (client) for the remote service.

The jqcDataService component is optional. You can easily just use jQuery's AJAX features directly, and set the data objects read from the remote service on a view model that way. It is up to you. The data model and view model components don't know anything about the jqcDataService component.

Creating a jqcDataService

You create a jqcDataService like this:

<span id="theDataService" jqc-type="jqcDataService"></span>    

This example declares a jqcDataService with the id theDataService. When the page controller boots it will find this span element and create the jqcDataService instance.

The second way to add a jqcDataService to the page controller is by calling the addComponent() function on the page controller, like this:

<span id="bootModule" jqc-module="bootModule"></span>

<script>
    function bootModule() {
        var bootModule = {};

        bootModule.postInstantiate = function() {
            bootModule.jqc.pageController.addComponent("addTaskDataService",
                bootModule.jqc.pageController.factories.jqcDataService());
        }

        return bootModule;
    }
</script>

This way the jqcDataService is added to the page controller from inside the postInstantiate() boot phase function of a module.

Setting the Service URL

You can set the data service URL in two ways. The first one is declaratively by inserting a jqc-url attribute into the HTML element declaring the jqcDataService. Here is an example of how that looks:

<span id="theDataService" jqc-type="jqcDataService"
      jqc-url="/myDataService.json"
    ></span>

You can also set the URL programmatically from inside a module. Here is an example of how that could look:

<span id="bootModule" jqc-module="bootModule"></span>

<script>
    function bootModule() {
        var bootModule = {};

        bootModule.postConfigure = function() {
            var components = bootModule.jqc.pageController.components;

            components.theDataService.url("/myDataService.json");
        }

        return bootModule;
    }
</script>

Calling the jqcDataService

You call the jqcDataService by calling the sendRequest() function. You can pass a JavaScript object along to the function as parameter. All properties inside this object will be passed as HTTP request parameters to the data service. Here is an example which sends an empty object to the remote data service:

<span id="bootModule" jqc-module="bootModule"></span>

<script>
    function bootModule() {
        var bootModule = {};

        bootModule.postConfigure = function() {
            var components = bootModule.jqc.pageController.components;

            components.theDataService.url("/examples/remote-data-service.jsp");
        }

        bootModule.postRender = function() {
            var components = bootModule.jqc.pageController.components;

            components.theDataService.sendRequest({});
        }

        return bootModule;
    }
</script>

The sendRequest() function takes two parameters:

The requestObj is the object to send to the remote data service. If you don't want to send any data to the remote service, you can leave out this object (or pass null), or pass an empty JavaScript object.

The carryThrough is an optional extra JavaScript object which is passed on to the done and fail listeners. The carryThrough is not sent to the remote data service. It is just a way for you to connect requests and responses if you need that, or pass information from the request to the response which is not sent to the remote data service.

Here is a sendRequest() example which uses both a request object and a carry through object:

components.theDataService.sendRequest({ title : "Read book" }, { extraInfo : "none" } );

Adding Listeners to the jqcDataService

When you call a jqcDataService and the remote data service responds, the jqcDataService calls the done listener function. If the communication with the remote data service fails, the jqcDataService calls the fail listener function.

Adding a Done Listener

You can add a done listener to the jqcDataService like this:

components.theDataService.done( function(data, requestObject, carryThrough, textStatus, jqxhr) {
        // process the responseObj , e.g. add it to a data model
});

The done listener function can take five parameters:

The responseObj parameter is the data (typically a JSON object) returned by the remote data service.

The requestObj is the request object passed to sendRequest() which resulted in this call to the done listener.

The carryThrough is an optional object you can pass to the sendRequest() function, which is then carried through to the done listener. This object is not sent to the server. It is normally just used to pass additional information from the code calling sendRequest() to the done listener.

The textStatus is the HTTP text status returned by the server.

The jqxhr parameter is the jqxhr object returned by jQuery's AJAX function.

Since version 1.4.0 you can also add a done listener by inserting a jqc-done attribute into the HTML element declaring the jqcDataService. Here is an example:

<span id="theDataService" jqc-type="jqcDataService"
      jqc-url="/myDataService.json"
      jqc-done="bootModule.dataReadDone"
    ></span>

<span jqc-module="bootModule"></span>    
<script>
funtion bootModule() {
    var module = {};
    
    module.dataReadDone = function(data, requestObject, carryThrough, textStatus, jqxhr) {
        //process response
    }
    
    return module;
}    
</script>

This example declares a done listener which calls the bootModule's dataReadDone() function.

You can use a global function or a function in a module or component. For a global function, leave out the module or component name (in front of the .). For a function inside a module or component, write the module or component first followed by a . , then the name of the function to call (as shown in the example above).

Adding a Fail Listener

You add a fail listener using the fail() function. Here is an example:

theDataService.fail( function(requestObject, carryThrough, jqxhr, textStatus, errorThrown) {
        // process response
});

The fail listener function takes 5 parameters:

The requestObj is the request object passed to sendRequest() which resulted in the fail listener being called.

The carryThrough is the optional carryThrough object passed to the sendRequest() function which resulted in the fail listener being called.

The jqXHR is the jqXHR object used internally by jQuery for calling the remote data service.

The textStatus is the textual error message as given to fail listeners by jQuery's own AJAX fail listener invocation.

The errorThrown is the errorThrown object given to fail listeners by jQuery's own AJAX fail listener invocation.

Since version 1.4.0 you can also add a fail listener by inserting a jqc-fail attribute into the HTML element declaring the jqcDataService. Here is an example:

<span id="theDataService" jqc-type="jqcDataService"
      jqc-url="/myDataService.json"
      jqc-done="bootModule.dataReadDone"
      jqc-fail="bootModule.dataReadFail"
    ></span>

<span jqc-module="bootModule"></span>
<script>
funtion bootModule() {
    var module = {};

    module.dataReadDone = function(data, requestObject, carryThrough, textStatus, jqxhr) {
        //process response
    }

    module.dataReadFail = function(requestObject, carryThrough, textStatus, errorThrown, jqxhr) {
        //process response
    }

    return module;
}
</script>

This example declares a fail listener which calls the bootModule's dataReadFail() function.

You can use a global function or a function in a module or component. For a global function, leave out the module or component name (in front of the .). For a function inside a module or component, write the module or component first followed by a . , then the name of the function to call (as shown in the example above).

Adding an Always Listener

You add an always listener using the always() function. The always listener is always called when a remote data service responds, regardless of whether the request succeeded or failed. Here is an example:

theDataService.always( function(dataOrJqxhr, requestObject,
    carryThrough, textStatus, errorThrownOrJqxhr) {

});

The always listener function takes 5 parameters:

The dataOrJqxhr contains the data returned by the remote service if the call succeeds, and the jQuery jqXHR object if the call fails.

The requestObject contains the request object which was sent to the remote service when it was called.

The carryThrough is the carry through object used when the service call was made (if any).

The textStatus is the HTTP text status sent back by the remote server.

The errorThrownOrJqxhr is the errorThrown contains the errorThrown object passed to fail listeners if the call fails, or the jqXHR object if the remote data service call succeeds.

Since version 1.4.0 you can also add an always listener by inserting a jqc-always attribute into the HTML element declaring the jqcDataService. Here is an example:

<span id="theDataService" jqc-type="jqcDataService"
      jqc-url="/myDataService.json"
      jqc-done="bootModule.dataReadDone"
      jqc-fail="bootModule.dataReadFail"
      jqc-always="bootModule.dataReadAlways"
    ></span>

<span jqc-module="bootModule"></span>
<script>
funtion bootModule() {
    var module = {};

    module.dataReadDone = function(data, requestObject, carryThrough, textStatus, jqxhr) {
        //process response
    }

    module.dataReadFail = function(requestObject, carryThrough, textStatus, errorThrown, jqxhr) {
        //process response
    }

    module.dataReadAlways = function(dataOrJqxhr, requestObject,
        carryThrough, textStatus, errorThrownOrJqxhr) {

        //process response
    }

    return module;
}
</script>

This example declares an always listener which calls the bootModule's dataReadAlways() function.

You can use a global function or a function in a module or component. For a global function, leave out the module or component name (in front of the .). For a function inside a module or component, write the module or component first followed by a . , then the name of the function to call (as shown in the example above).

Attributes

AttributeDescription
jqc-url Sets the URL of the remote data service. The URL the requests will be sent to.
jqc-done Sets the done listener function to call when remote service calls succeed.
jqc-fail Sets the fail listener function to call when remote service calls fails.
jqc-always Sets the always listener function to call regardless of whether the remote service calls succeeds or fails.

Functions

FunctionDescription
url(theUrl) Sets the URL of the remote data service. The URL the requests will be sent to.
dataType(theDataType) Sets the dataType passed on to jQuery's AJAX function. Defaults to 'json'.
type(theType) Sets the type passed on to jQuery's AJAX function. Defaults to 'POST'.
sendRequest(dataObject) Sends the request to the remote data service. Each property of the dataObject is sent to the remote data service as a request parameter. By default the jqcDataService sends the request as a HTTP POST request.
done(doneListener) Sets the function to call when a request succeeds.
fail(failListener) Sets the function to call when a request fails.