Using Deferred Objects In jQuery 1.5 To Normalize API Responses

<!---
	Create the default response object. This is what will be
	serialized and return the client in JSON format.

	NOTE: We are using array-notation here in order to maintain case
	for easier use within the client-side environment (Javascript).
--->
<cfset response = {} />
<cfset response[ "statusCode" ] = "200" />
<cfset response[ "statusText" ] = "OK" />
<cfset response[ "success" ] = true />
<cfset response[ "data" ] = "" />
<cfset response[ "errors" ] = [] />


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!--- Randomly cause unexpected errors. --->
<cfif (randRange( 1, 3 ) eq 2)>

	<cfthrow type="eyeIzInYourServerMaykinItBetterz" />

</cfif>


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	Wrap the entire processing of the form in a try/catch so that
	we can return the appropriate response code should something
	go wrong.
--->
<cftry>

	<!--- Param the incoming form values. --->
	<cfparam name="form.username" type="string" default="" />
	<cfparam name="form.name" type="string" default="" />
	<cfparam name="form.age" type="string" default="0" />


	<!--- Make sure the user is validated. --->
	<cfif (form.username neq "ben")>

		<!--- This user is not authorized to access this API. --->
		<cfthrow
			type="NotAuthorized"
			/>

	</cfif>


	<!--- Validate the data. --->
	<cfif !len( form.name )>

		<!--- Append an error. --->
		<cfset arrayAppend(
			response.errors,
			"Please enter a valid name."
			) />

	</cfif>

	<!--- Validate the data. --->
	<cfif !isNumeric( form.age )>

		<!--- Append an error. --->
		<cfset arrayAppend(
			response.errors,
			"Please enter a numeric age."
			) />

	<cfelseif (form.age lt 18)>

		<!--- Append an error. --->
		<cfset arrayAppend(
			response.errors,
			"Please enter an age greater than 18."
			) />

	</cfif>

	<!--- Check to see if there are any errors. --->
	<cfif arrayLen( response.errors )>

		<!--- Throw a bad request error. --->
		<cfthrow
			type="BadRequest"
			message="Invalid Request Parameters"
			/>

	</cfif>



	<!---
		If we have made it this far then the data is valid and
		can be persisted to the database. Of course, this is just
		an exploration of jQuery, so we don't need a database...
		just return a valid data point.
	--->
	<cfset response.data = "#form.name# (#form.age#)" />



	<!--- Not authorized.. --->
	<cfcatch type="NotAuthorized">

		<!--- Set authorization message. --->
		<cfset arrayAppend(
			response.errors,
			"You are not authorized to use this API."
			) />

		<!--- Flag the security concern. --->
		<cfset response.statusCode = "401" />
		<cfset response.statusText = "Unauthorized" />
		<cfset response.success = false />

	</cfcatch>

	<!--- Bad request errors (data validation). --->
	<cfcatch type="BadRequest">

		<!--- Flag the server error. --->
		<cfset response.statusCode = "400" />
		<cfset response.statusText = "Bad Request" />
		<cfset response.success = false />

	</cfcatch>

	<!--- Unexpected error. --->
	<cfcatch>

		<!--- An unknown error occurred. --->
		<cfset arrayAppend(
			response.errors,
			"An unexpected error occurred."
			) />

		<!--- Flag the server error. --->
		<cfset response.statusCode = "500" />
		<cfset response.statusText = "Internal Server Error" />
		<cfset response.success = false />

	</cfcatch>

</cftry>


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	Set the appropriate status code for the response.

	NOTE: Only 20x status codes will result in a success handler
	(or a "done" deferred handler); anything else will result in an
	error handler (or a "fail" deferred handler) being called.
--->
<cfheader
	statuscode="#response.statusCode#"
	statustext="#response.statusText#"
	/>

<!--- Return the JSON response to the client. --->
<cfcontent
	type="application/json"
	variable="#toBinary( toBase64( serializeJSON( response ) ) )#"
	/>

<!DOCTYPE html>
<html>
<head>
	<title>Playing With Deferred And AJAX In jQuery 1.5</title>
	<script type="text/javascript" src="../jquery-1.5.js"></script>
</head>
<body>

	<h1>
		Playing With Deferred And AJAX In jQuery 1.5
	</h1>

	<form>

		<h2>
			Enter Data
		</h2>

		<p class="message" style="display: none ;">
			<!--
				This is where the confirmation message will go
				on the AJAX request completion.
			--->
		</p>

		<p>
			Username:
			<input type="text" name="username" size="20" />
		</p>

		<p>
			Name:
			<input type="text" name="name" size="20" />
		</p>

		<p>
			Age:
			<input type="text" name="age" size="5" />
		</p>

		<p>
			<input type="submit" value="Save Contact" />
		</p>

	</form>


	<!-- --------------------------------------------------- -->
	<!-- --------------------------------------------------- -->


	<script type="text/javascript">

		// Store DOM references.
		var form = $( "form" );
		var message = $( "p.message" );
		var username = form.find( "input[ name = 'username' ]" );
		var contactName = form.find( "input[ name = 'name' ]" );
		var contactAge = form.find( "input[ name = 'age' ]" );


		// Bind to the form submission error to handle it via AJAX
		// rather than through the standard HTTP request.
		form.submit(
			function( event ){

				// Prevent the default browser behavior.
				event.preventDefault();

				// Try to save the contact to the server. The
				// saveContact() method returnes a promise object
				// which will come back with a result eventually.
				// Depending on how it resolves, either the done()
				// or fail() event handlers will be invoked.
				//
				// NOTE: This return object can be chained; but for
				// clarity reasons, I am leaving these as one-offs.
				var saveAction = saveContact(
					username.val(),
					contactName.val(),
					contactAge.val()
				);

				// Hook into the "success" outcome.
				saveAction.done(
					function( response ){

						// Output success message.
						message.text(
							"Contact " + response.data + " saved!"
						);

						// Show the message.
						message.show();

					}
				);

				// Hook into the "fail" outcome.
				saveAction.fail(
					function( response ){

						// Output fail message.
						message.html(
							"Please review the following<br />-- " +
							response.errors.join( "<br />-- " )
						);

						// Show the message.
						message.show();

					}
				);

			}
		);


		// I save the contact data.
		function saveContact( username, name, age ){
			// Initiate the AJAX request. This will return an
			// AJAX promise object that maps (mostly) to the
			// standard done/fail promise interface.
			var request = $.ajax({
				type: "post",
				url: "./api.cfm",
				data: {
					username: username,
					name: name,
					age: age
				}
			});

			// Return a normalized request promise.
			return(
				normalizeAJAXResponse( request )
			);
		}


		// -------------------------------------------------- //
		// -------------------------------------------------- //
		// -------------------------------------------------- //
		// -------------------------------------------------- //


		// I take the AJAX request and return a new deferred object
		// that is able to normalize the response from the server so
		// that all of the done/fail handlers can treat the incoming
		// data in a standardized, unifor manner.
		function normalizeAJAXResponse( request ){
			// Create an object to hold our normalized deferred.
			// Since AJAX errors don't get parsed, we need to
			// create a proxy that will handle that for us.
			var normalizedRequest = $.Deferred();

			// Bind the done/fail aspects of the original AJAX
			// request. We can use these hooks to resolve our
			// normalized AJAX request.
			request.then(

				// SUCCESS hook. ------ //
				// Simply pass this onto the normalized
				// response object (with a success-based resolve).
				normalizedRequest.resolve,

				// FAIL hook. -------- //
				function( xhr ){

					// Check to see what the status code of the
					// response was. A 500 response will represent
					// an unexpected error. Anything else is simply
					// a non-20x error that needs to be manually
					// parsed.
					if (xhr.status == 500){

						// Normalize the fail() response.
						normalizedRequest.reject(
							{
								success: false,
								data: "",
								errors: [ "Unexpected error." ],
								statusCode: xhr.statusCode()
							},
							"error",
							xhr
						);

					} else {

						// Normalize the non-500 "failures."
						normalizedRequest.reject(
							$.parseJSON( xhr.responseText ),
							"success",
							xhr
						);

					}

				}

			);

			// Return the normalized request object. This deferred
			// object can then be used by the calling context to
			// deal with success and failure. By normalizing it, both
			// the success and error handlers will be able to assume
			// that the response is coming in the same format.
			//
			// NOTE: Calling the .promise() method creates a read-only
			// interace to the deferred object such that the receiving
			// context can only hook into the object, not mutate it.
			return( normalizedRequest.promise() );
		}

	</script>

</body>
</html>