Last week I blogged a very simple example of jQuery to ColdFusion communication. At the request of a reader I created the simplest example I could come up with that demonstrated the basic concepts. Today I have a slightly more advanced example, one that specifically makes use of a form and a post operation.
My example is a very simple authentication system. The form has a username and password field. We want to integrate with a ColdFusion Component that will handle responding to the post from jQuery. Let's begin with the front end template.
<head> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script> <script> $(document).ready(function() { //grab the submit action $("#loginForm").submit(function(e) { //stop the form submission e.preventDefault() //get my values var uval = $("#username").val() var pval = $("#password").val() //basic validation if(uval == '' || pval == '') return //disable the button $("#loginButton").attr("disabled",true) //Let the user know we are doing something $("#result").html("Logging in...") //Send them to the CFC $.post("test.cfc?method=authenticate&returnformat=json", {username:uval, password:pval}, function(res) { //Handle the result if(res == "true") { $("#result").html("Your login worked.") //Do more here. } else { $("#result").html("Your login failed.") $("#loginButton").removeAttr("disabled") } }) }) }) </script> </head> <body> <form id="loginForm"> username: <input type="text" name="username" id="username"><br/> password: <input type="password" name="password" id="password"><br/> <input type="submit" value="Login" id="loginButton"> </form> <div id="result"></div> </body> </html><html>
Ok, we've got a few things to cover here. I'll begin with the HTML at the bottom. You can see my simple form (2 text fields and a submit button). Also notice the little "result" div at the bottom. I'll be using that later to provide feedback to the user.
Ok, now scroll up to the JavaScript. The meat of this template is all within one main event handler defined here:
$("#loginForm").submit(function(e) {
This is going to "take over" the normal form submission and let me do something else with it. Notice too that the very first command within the handler is: e.preventDefault(). This will ensure that my form never does actually submit (if the user has JavaScript enabled of course). Moving down, I grab the value from my two fields. I do this manually but jQuery does provide a few ways of serializing a form all at once. Once I've got that, I do some very simple validation. If either field is blank we leave the function.
Next up I disable the submit button. Remember that we're going to be doing an Ajax post, a network operation, and that isn't instantaneous. Disabling the submit button is an easy way to prevent a user from going click happy. We also add a status message so that the user knows something is going on.
The portion that actually performs the Ajax based request begins with $.post. We provide the URL first. Remember that you must pass the method to execute within the CFC. That's the method=authenticate part. You can - and normally should - provide a returnFormat argument as well to tell ColdFusion how to format the response. The second argument is a structure of data. These will be sent as POST fields to the CFC. Lastly we have a response handler. This is going to execute when the CFC returns a result to us. For our simple example we are assuming a string result of "true" or "false". Obviously there may be more complex results. In a longer form, you may have a set of error messages. In the result we either provide a "good" message or a "bad" message. As you can see in the comments, you would probably do a bit more on a good result. You may want to hide the form for example. Or you may actually push the user to another URL.
Now let's take a look at the CFC:
remote boolean function authenticate(string username, string password) { sleep(1400); if(arguments.username == "paris" && arguments.password == "hilton") return true; return false; } }component {
Yeah, I love me some script-based CFCs. So as you can imagine, this would probably be replaced with a query call or perhaps LDAP. But that doesn't really matter here. I added a sleep command in there to help simulate a slow network. To see this yourself, click the big new fancy Demo button below.
