ezAJAX Server Command Handlers
The ezAJAX Community Edition Framework makes it very easy to code server-side command handlers. It is possible to code a server-side command handler using as few as a dozen lines of code.
A typically simple server-side command handler would look like the following:
function userDefinedAJAXFunctions(qryStruct) {
switch(qryStruct.ezCFM) {
case 'sampleAJAXCommand':
qObj = QueryNew('id, status');
QueryAddRow(qObj, 1);
QuerySetCell(qObj, 'id', qObj.recordCount, qObj.recordCount);
QuerySetCell(qObj, 'status', ‘OK’, qObj.recordCount);
ezRegisterQueryFromAJAX(qObj);
break;
}
} |
The above sample server-side command handler performs a very simple task of doing nothing more than creating a small Query Object that is passed back to the ezAJAX client. This is what makes ezAJAX so easy. The last thing any server-side command handler does is to “register” a Query Object that is sent back to the client.
Automatic Argument or Parameter Handling
ezAJAX provides a very easy to use argument or parameter handling mechanism that takes all the “named” parameters from the “oAJAXEngine.doAJAX()” invocation and collects them into an easy to use structure the programmer can use when coding server-side command handlers that reside in the “userDefinedAJAXFunctions.cfc” file.
The ColdFusion variable “Request.qryStruct.namedArgs” holds the named arguments that were passed from JavaScript to the ezAJAX Server via the “oAJAXEngine.doAJAX()” invocation. This allows the programmer to quickly and easily manipulate the arguments that were passed to the ezAJAX Server . This also makes it easy to use the “IsDefined()” ColdFusion function to determine when named argument has in-fact been passed to the server or not.
The “argsDict” parameter to a Simpler Model Call-Back is populated with the contents of the “Request.qryStruct.namedArgs” ColdFusion Structure. This makes it easy for the programmer to write abstract code that can be made aware of the arguments that were passed to the ezAJAX Server without having to necessarily have access to the original code that was written to interface with the ezAJAX Server.
Automatic Error Handling
ezAJAX provides a very easy to use Error Handling system for communicating errors from the ezAJAX Server to the client.
Consider the following server-side command handler that notifies the client that an error happened:
function userDefinedAJAXFunctions(qryStruct) {
switch (qryStruct.ezCFM) {
case 'sampleAJAXCommand':
qObj = QueryNew('id, errorMsg, moreErrorMsg, explainError, isPKviolation');
QueryAddRow(qObj, 1);
QuerySetCell(qObj, 'id', qObj.recordCount, qObj.recordCount);
QuerySetCell(qObj, 'errorMsg', ‘An Error occurred.’, qObj.recordCount);
QuerySetCell(qObj, 'moreErrorMsg', ‘Verbose Error Message’, qObj.recordCount);
QuerySetCell(qObj, 'explainError', '', qObj.recordCount);
QuerySetCell(qObj, 'isPKviolation', false, qObj.recordCount);
ezRegisterQueryFromAJAX(qObj);
break;
}
} |
The ezAJAX client when using the Simpler Call-Back Model keys on the following Query Column names when deciding when to pop-up an automatic Error Message Panel (Query Column Names are converted to upper-case once the Query Object reaches the client): ERRORMSG, ISPKVIOLATION, or ISHTML.
Any Query Object that uses any of the three reserved Column Names will be interpreted by the Simpler Call-Back Model as an Error Message and an automatic pop-up panel will be displayed to communicate the error condition to the end-user. Whenever the ISHTML Column Name is used it is assumed to be a Boolean value represented as a String Object instance which allows the ERRORMSG to contain HTML which is then displayed as HTML in the automatic pop-up panel that is used to communicate the Error condition to the end-user.
As the programmer you may choose to use the Complex Call-Back Model and handle the Error Conditions yourself using whatever technique meets your individual needs and goals.
ezAJAX stands ready to make this as easy as is desired or as powerful and flexible as is desired.
|
