ezAJAX Call-Back Functions

The ezAJAX Community Edition Framework makes use of JavaScript based Call-Back functions the ezAJAX Server uses when transferring control back to the client from the server once the server concludes processing.

There are two models for Call-Back functions, the Complex Model and the Simpler Model. The Complex Model is only a bit more complex than the Simpler Model but it allows the programmer to take more control over the flow of control once the Call-Back is fired by the ezAJAX Server.

The Simpler Model is much “simpler” than the Complex Model because it assumes the same processing is to be done just prior to the application specific code the programmer wanted to use for each Call-Back.

Of course it should be noted the programmer could, if desired, provide only one Call-Back through which all Call-Back processing could be done using some kind of Abstract Model the programmer may wish to define. Many Call-Back functions could just as easily be used depending on the wishes of the programmer and the goals the programmer is trying to achieve. For situations where there are very few differences between how certain Call-Backs should be coded it is useful to Abstract them into a single Call-Back.

Complex Model

A typical Complex Model Call-Back sample can be found in the cfinclude_index_body.cfm file that was shipped with the ezAJAX Community Edition Framework.

You may wish to refer to the cfinclude_index_body.cfm file while reading the following sections.

handleSampleAJAXCommand(qObj)

Notice the JavaScript function “handleSampleAJAXCommand(qObj)”. This is a sample of a Complex Model Call-Back function that takes one argument that is the “qObj” pointer to an instance of the ezAJAXObj Object.
Notice the line of code “qStats = qObj.named('qDataNum');” that is used to access the statistics from the ezAJAXObj Object instance.

Notice the line of code “nRecs = qStats.dataRec[1];” that is used to access the number of records that are stored in the ezAJAXObj Object instance. The ezAJAX Community Edition is limited to one data record which is to say the programmer will be allowed to return one (1) Query Object to the client. This limitation is removed for the ezAJAX Enterprise Edition along with some additional features such as the ability to return “Named” Query objects to the client and some performance improvements to make returning Query objects faster and more efficient. The limitation of being able to return one Query object instance should not pose much of a problem for the more skilled programmers because ColdFusion Query Objects can easily be modified and combined to allow almost any goal to be easily accomplished. It is more convenient, however, to have the ability to return many Named Query Objects back to the client as this can make the application specific code that goes in the userDefinedAJAXFunctions.cfc file easier to maintain as well as more powerful.
Notice the line of code “qData1 = qObj.named('qData1');” that is used to access the Query Object that was returned from the ezAJAX Community Edition Server.

Once the Query Object has been accessed from the ezAJAXObj Object instance one can process Query of Queries using aforementioned “iterator” functions using code such as the following:

“qData1.iterateRecObjs(anyErrorRecords);” or “qData1.iterateRecObjs(searchForStatusRecs);”.

The line of code “qData1.iterateRecObjs(anyErrorRecords);” is used to determine if there are any Error conditions that were returned within the Query Object instance that was transmitted back to the client from the server. Error conditions are flagged as being such whenever any of the following Column Names are used in the Query Object: 'ERRORMSG', 'ISPKVIOLATION' or 'ISHTML'. The reference to “anyErrorRecords” is an Abstract function that performs the processing to determine if the Query Object contains any Error Conditions.
The line of code “oParms = qObj.named('qParms');” is used to access the “arguments” that were passed to the ezAJAX Server along with the ezAJAX Command.

The line of code “oParms.iterateRecObjs(searchForArgRecs);” is used to perform a Query of Queries to collect-up the “arguments” from the Arguments Query Object instance.

Notice the function “searchForArgRecs(_ri, _dict)” that is modeled as a local function that takes two arguments which are the “_ri” the record index Integer and the “_dict” ezDictObj instance that contains the record or row of data. The keys from the “_dict” ezDictObj instance for “arguments” will always be 'NAME' and 'VAL'. It is however far more convenient to have an ezDictObj instance that has named arguments and thus the reason for performing the searchForArgRecs iterator on the oParms Query Object instance.

Notice the line of code “argsDict.intoNamedArgs();” that is used to convert the argsDict into a named args dictionary.

The line of code “qData1.iterateRecObjs(searchForStatusRecs);” is used to perform a Query of Queries and serves as a sample only to help illustrate how to construct an iterator function.

Notice the function “searchForStatusRecs(_ri, _dict)” that takes the same two arguments as the “searchForArgRecs(_ri, _dict)” function. These are the same two arguments that all Query of Queries iterator functions take.

Notice the line of code “aDict = ezDictObj.get$(_dict.asQueryString());” that is used within the “searchForStatusRecs(_ri, _dict)” function to convert the “_dict” ezDictObj from an instance pointer to a new ezDictObj instance. This has to be done within Query of Queries iterator functions because the “_dict” ezDictObj instance pointer points to an instance of a ezDictObj that is removed shortly after it is created within the code that fires the iterator function. As you can see it is possible and sometimes desirable to retrieve the whole Query Record Dictionary Object from the Query Object that record inhabits.

As you have seen it is quite easy to construct Query of Queries iterator functions that can access records from the Query Objects that are returned from the ezAJAX Server using whatever criteria one may desire to construct. This may not be as elegant as the way one constructs Query of Queries using ColdFusion but it gets the job done quite nicely nonetheless.

Notice the line of code “ezDictObj.remove$(argsDict.id);” that appears near the bottom of the Complex Model Call-Back function. This ensures we don’t collect-up too many instances of ezDictObj Objects while processing Call-Back functions. Since there is little reason to leave the arguments dictionary in the Object cache beyond the scope of the Call-Back function we simply remove the whole ezDictObj instance using the appropriate function to deconstruct the object instance.

Simpler Model

A typical Simpler Model Call-Back sample can be found in the cfinclude_index_body.cfm file that was shipped with the ezAJAX Community Edition Framework.

You may wish to refer to the cfinclude_index_body.cfm file while reading the following sections.

simplerHandleSampleAJAXCommand(qObj, nRecs, qStats, argsDict, qData1)

Notice the JavaScript function “simplerHandleSampleAJAXCommand(qObj, nRecs, qStats, argsDict, qData1)”. This is a sample of a Simpler Model Call-Back function that takes five arguments which are the “qObj” pointer to an instance of the ezAJAXObj Object, “nRecs” Integer number of records or Query Objects returned, “qStats” pointer to a statistics Query Object, “argsDict” pointer to an ezDictObj that contains the named arguments that were passed to the ezAJAX Server and “qData1” pointer to the Query Object that stores the data that was returned from the ezAJAX Server.

Notice how much simpler it is to use the Simpler Model Call-Back. Error handling is done automatically. The various data elements are automatically separated from the Object that is returned from the ezAJAX Server.
The programmer should still write enough code to properly validate that the arguments to a Simpler Model Call-Back are in-fact not “null” values as seen in the sample function provided with the base product. The Simpler Model Call-Back, when used, would result in far less code to write and therefore would result in faster access times for end-users due to the need to download less content for a typical ezAJAX web app that uses Simpler Model Call-Backs.

ezAJAXEngine.receivePacketMethod()

The “ezAJAXEngine.receivePacketMethod()” function which is a Class method for the ezAJAXEngine Object that is used to define to the system which “method” is to be used when receiving packets from the ezAJAX Server. Depending on the value this function returns the system will use either the Simpler Model or Complex Model for Call-Backs. The decision to use either Model for Call-Backs is considered to be dynamic in that one could code the value returned in a dynamic manner.

To use the Simpler Model Call-Backs one would return the value “const_simpler_symbol” from the “ezAJAXEngine.receivePacketMethod()” function that would be implemented within the code file the programmer can supply to the ezAJAX Community Edition Framework. By default, there is already a “ezAJAXEngine.receivePacketMethod()” function implemented that causes the Simpler Model to be used however it is an easy thing to cause the system to use Complex Model Call-Backs if doing so becomes necessary.

To use the Complex Model Call-Backs one would return any String value other than “const_simpler_symbol” from the “ezAJAXEngine.receivePacketMethod()” function. Any suitably skilled programmer should be able to code the “ezAJAXEngine.receivePacketMethod()” function as stated above to cause the desired effect of using the Complex Model Call-Backs should doing so become necessary.