The API

Overview

One of the goals of COWS Ajax was to make it simple. It does not model the function calls of the traditional XMLHttpRequest (XHR) method. Why is that? Well I don't recall that API being all that straightforward in the first place! The first thing developers do is encapsulate the calls into their own class to make XHR 'easy'. So I didn't see any value in emulating that model. Instead, I've choosen to create a full service class that is extensible and lightwieght but comes with the functions developers really need built in.

COWS Ajax does a fair amount of the nuts and bolts for you, including managing the request queue and polling for requests and response. There are three basic aspects to be dealt with: COWS Ajax calls to be made, the server coupling function, and functions you can define that COWS Ajax will hook into. The following is a quick reference guide:

Function Description Parameters
cows_ajax class method - the class constructor; need to create the object before doing anything; defines some members, but doesn't actually "do" anything params - JSON object; success_handler and failure_handler must be defined
connect class method - called when ready to make initial contact with the server; activates polling for request and responses params - JSON object; server_url must be supplied
send class method - adds a request into the queue to be processed by the server once requests ahead of it are completed params - JSON object; server_url must be supplied
disconnect class method - stop polling for requests and response; flushes queue of existing requests -
cows_ajax_response server defined - this is the "coupled" function that COWS Ajax looks for to know when the server has prepared a response -
success_handler application defined - defined in your javascript app that gets called when the server successfully communicates back with the client a connection index
failure_handler application defined - defined in your javascript app that gets called when connecting to the server is unsuccessful by any means, including a timeout a connection index
display_processing_message application defined - defined in your javascript app where if defined, gets called prior to making a request (toggle on) and again after a success or failure response is received (toggle off). Can be used for a 'status' indicator. a connection index