Learning jQuery: Day 4 - A Simple Username Checker

I received an email recently that went like this:

"Hal, love your series on jQuery and ColdFusion, but I wonder could you show a really simple example just to get us started?"

Well...sure! Let's take a common situation and see if we can make the user experience better. We've probably all used (and written) countless registration pages that ask for your username and email. It's a particular pet peeve of mine when sites make me click "Submit" -- only to find out that my preferred username ("bradpitt") is already taken. Often, any information I've entered is lost. Time to stop that.

Let's begin with a very simple signup page:

At the bottom of the page, let's append some jQuery magic:

"Wait!" (I can hear your thoughts.) "That doesn't look so simple!"

Let's dissect it to understand it. Along the way, we'll have a chance to see several jQuery features.

The first line brings in the base jQuery library from Google. (You can also import it from your own site, if you prefer.)

Next, we write our own script. The first line of that script uses the $('#id_of_element_to_be_matched') pattern. It wraps a DOM element with the id of "username" with a jQuery object. We could get the DOM element by itself with some simple JavaScript -- document.getElementById('username') -- but that would lack the jQuery goodness we're after.

So, what do we want to do with this element? When the value changes, we want to do check whether the username entered already exists on the server. If so, we'll alert the user in the span tag with an id of "msg", remove the offending username, and focus the cursor back to the username field.

If the user has already entered a bad username, the "msg" will already be filled, so let's start by removing any existing message with this code:

$('#msg').empty();

As you can see, we used that same selector pattern, applying it this time to the DOM element with an id of "msg". The "empty" method belongs to jQuery.

Now, it's time to involve ColdFusion in this great effort. We do this by using an Ajax call to a CFC method: checkUsername, located in a UsernameChecker CFC. (We'll see that in a moment.) The "$.post" is jQuery shorthand for the Ajax communication with the server using the "post" method. (We could have also used "get".)

In addition to posting to a specific file (you can also post to a .cfm file), I'm sending an argument called "username" with the value of whatever username was entered. The format is JSON. As you can see, it's pretty simple: a name/value pair, separated by a colon. The code, "this.value", provides us with the actual username entered. (If you're a bit confused by what "this" stands for, it points to the DOM element we started with -- the one with an id of "username". Because of the extremely dynamic nature of JavaScript, "this" is one of the harder things to pin down as to exactly what it's referring to. We'll have to pick that advanced topic up in another post.)

After supplying the data to ColdFusion, ColdFusion will return a value (the number of records found matching the username). When that response is returned, I have provided an anonymous function (so-called because it has no name) that I want to run.

It takes as its sole argument the response from ColdFusion. If the response is greater than 0, we've found that username in our database already and will fill the "msg" span with a pithy condolence.

Next, we again select the DOM element with an id of "username", wrap it in a jQuery object, and remove its "value" attribute. What, then, are we to make of the next bit: ".focus()"?

This introduces to a nice feature in jQuery: chaining. Having cleared the value in the "username" text box, jQuery returns that element for any more calls we might like to make on it. We have just one: setting the cursor in that text box.

Now, that wasn't too bad -- and like everything, it gets easier and easier with practice until it will feel like second nature. As for the UsernameChecker CFC, it looks like this:

Note the use of the 'access="remote"' for our method. That allows us to call a CFC directly from a URL (or via Ajax in our case). As long as our argument name matches the name in the JSON data sent via jQuery, there's nothing else we need to do. Now, we have a choice of return formats to send the recordcount in. If you don't specify anything, ColdFusion will wrap anything you return in a WDDX packet. There are some other ways to handle this, but I recommend you return values in JSON. Very nicely, ColdFusion makes this very easy; we need only append the 'returnformat="json"' to our cffunction tag.

And that's it. Working with jQuery and JavaScript can be confusing at first, but I think you'll find (as I did), that it more than repays the effort by allowing us to make the user experience richer.