C H A P T E R  16

Refactoring the Example: Part II

I have introduced some very rich features in this part of the book, and as before, I want to bring them together to give a broader view of jQuery. I am not going to try to preserve a workable non-JavaScript structure in this chapter, since all of the features I am adding to the example rely heavily on JavaScript.

Reviewing the Refactored Example

In Chapter 11, you used the core jQuery features to refactor the example to include DOM manipulation, effects, and events. Listing 16-1 shows the document you ended up with, which will be the starting point for this chapter as you integrate the features from this part of the book.

There are a number of points in the script where I insert elements dynamically. Rather than making these static, I am going to leave them as they are so that you can focus on adding the new features.

This isn't quite the same as the document in Chapter 11. I have tidied up a lot of the CSS additions by adding a style element, rather than using the css method on individual selections. You can see how this document appears in Figure 16-1, and, of course, Chapter 11 breaks down the set of changes I applied to the document to get this far.

Figure 16-1 The starting point for the example document in this chapter

Updating the Node.js Script

Before you get started with the jQuery features, you need to upgrade your server-side script. These additions are to enrich the data that is sent back when a form is submitted and to support a new validation feature. Listing 16-2 shows the new script.

The response to the browser now includes the total prices for the items selected using the form elements and submitted to the server, returning a JSON result like this:

I saved this script to a file called formserver.js. The easiest way to get this script is to download the source code that accompanies this book and that is freely available from Apress.com. I run the script by entering the following at the command prompt:

Preparing for Ajax

To being with, I am going to add some basic elements and styles that I will use to display any Ajax request errors and set up the basic configuration that will apply to all of my Ajax requests. Listing 16-3 shows the changes to the document.

I have used the global Ajax events to set up a simple display for errors. When an error occurs, new elements are added to the screen with a description of the problem. The error messages that I show are derived from the information I get from jQuery, but I have kept things simple. In a real web application, these messages should be more descriptive and provide suggestions for basic resolution if possible. I have used the global events so that I am able to use the success and error setting on individual requests without having to worry about concatenating arrays of functions. You can see an example of a simple error in Figure 16-2.

Figure 16-2 Displaying an error message for Ajax

The error is displayed until a successful request is made or another error occurs, at which point the elements are removed from the document.

In addition to the events, I used the ajaxSetup method to define values for the timeout setting and to provide a converter for HTML fragments so that they are automatically processed by jQuery.

Sourcing the Product Information

The next change I am going to make is to remove the existing product elements and the loop that adds three additional flowers to the list, replacing them with a couple of Ajax calls and a data template. First, however, I have created a new file called additionalflowers.json, which is shown in Listing 16-4.

This file contains a basic JSON description of the additional products I want to display. I am going to get the main set of products as an HTML fragment and then add to the set by processing the JSON data. Listing 16-5 shows the changes.

I have used the Ajax shorthand methods to get the HTML fragment and the JSON data I need to create the rows. It may not be obvious from the script, but one of the nice things about the shorthand method is that they are just wrappers around calls to the low-level API, and this means that the settings you apply via the ajaxSetup method apply just as they do when you use the ajax method directly.

In addition to the calls to the get and getJSON methods, I have added a simple data template so I can process the JSON simply and easily. There is no change to the appearance of the document, but the source of the content has changed.

Adding Form Validation

The next stage is to add some validation to your input elements. Listing 16-6 shows the additions that are required.

In this listing, I have imported the JavaScript library for the validation plugin and defined some basic styles that will be used to display validation errors. I then call the validate method on the form element to set up form validation, specifying a single validation summary. This approach is straight out of Chapter 13.

Now, the use of Ajax to generate elements for the flower products gives me a problem. These are, of course, asynchronous calls, so I can't make assumptions about the presence of the input elements in the document in the statements that follow the Ajax calls. This is the common pitfall I described in Chapter 14, and if the browser executes my selection of the input elements before both Ajax requests are complete, then I won't match any elements (because they have yet to be created and added to the document), and my validation setup will fail. To get around this, I have used the when and then methods, which are part of the jQuery deferred objects feature that I describe in Chapter 35. Here are the relevant statements:

I don't want to get ahead of myself, but the jqXHR objects that are returned by all of the Ajax methods can be passed as arguments to the when method, and if both requests are successful, then the function passed to the then method will be executed.

I set up my form validation in the function I pass to the then method, selecting the input elements and adding the validation rules I require to each of them. I have specified that values are required, that they must be digits, and that the minimum acceptable value is zero. I have defined custom messages for each check, and these refer to an array of plural flower names to help them make sense to the user.

Since I have the input elements selected, I take the opportunity to provide a handler function for the change event, which is triggered when the value entered into the field changes. Notice that I call the element method, like this:

This triggers validation on the changed element, and the result from the method is a Boolean indicating the validity of the entered value. By using this in an if block, I can avoid adding invalid values to my running total of selected items.

Adding Remote Validation

The validation I performed in the previous example and that I described in Chapter 13 are examples of local validation, which is to say that the rules and the data required to enforce them are available within the document.

The validation plugin also supports remote validation, where the value entered by the user is sent to the server and the rules are applied there. This is useful when you don't want to send the data to the browser because there is too much of it, because doing so would be insecure, or because you want to perform validation against the latest data.

I didn't explain remote validation in Chapter 13 because it relies on JSON and Ajax, and I didn't want to get into those topics too early. Listing 16-7 shows the addition of remote validation to the example document, where I use it to ensure that the user is unable to order more items than the server records as being in stock.

Setting remote validation is easy now that you have seen the jQuery support for Ajax. We specify the check as remote and set it to be a standard Ajax settings object. In this example, I have used the url setting to specify the URL will be called to perform the remote validation, the type setting to specify that I want a POST request, and the global setting to disable global events.

I have disabled global events because I don't want errors making the validation request to be treated as general errors that the user can do something about. Instead, I want them to fail quietly, on the basis that the server will perform further validation when the form is submitted (the Node.js script doesn't perform any validation, but it is important that real web applications do, as I mentioned in Chapter 13).

The validation plugin uses your Ajax setting to make a request to the specified URL, sending the name of the input element and the value that the user has entered. If the response from the server is the word true, then the value is valid. Any other response is considered to be an error message that will be displayed to the user. You can see how these messages are used in Figure 16-3.

Figure 16-3 Displaying remote validation messages

Submitting the Form Data Using Ajax

Submitting the values in the form is exceptionally simple, and Listing 16-8 shows the same technique that I used in Chapter 15.

I've gone beyond just making an Ajax POST request because I want to provide some additional context for how these requests can be handled in real projects. To start with, I have added an element that is positioned above all of the other elements in the document and tells the user that their order is being placed. Here are the CSS and jQuery statements that create this effect:

It is surprisingly hard to create an element that looks like a pop-up and that is properly positioned on the screen, and you can see that the amount of CSS required to make it work is significant. The HTML elements are surprisingly simple by comparison, and the HTML that is generated looks like this when properly formatted:

The img element I have specified (progress.gif) is an animated GIF image. There are a number of web sites that will generate progress images to your specification, and I used one of them. If you don't want to create your own, then use the one from this example that is included in the source code download for this book (available without charge at Apress.com). You can see how these elements appear in Figure 16-4, where I have removed the other elements for clarity.

Figure 16-4 Showing progress to the user

I hide these elements initially because it makes no sense to show the user a progress display until they actually place the order:

With these elements in place and hidden, you can turn to the form submission. I register a handler function for the click event for the button element, as follows:

Before starting the Ajax request, I show the pop-up elements and make all of the other elements partially transparent. I also disable the input elements by adding the disabled attribute. I do this because I don't want the user to be able to change the value of any of the input elements while I am sending the data to the user:

The problem with disabling the input elements is that their values won't be included in the data sent to the server. The serialize method will include values only from input elements that are successful controls, as defined by the HTML specification; this excludes those elements that are disabled or don't have a name attribute. I could iterate through the input elements myself and get the values anyway, but it is simpler to gather the data to send before disabling the elements, like this:

I have used the complete setting to restore the interface to its normal state by making all of the elements opaque, removing the disabled attribute from the input elements and hiding the pop-up elements. I have introduced an artificial 1.5-second delay after the request has completed before restoring the interface, like this:

I would not do this in a real web application, but for demonstration purposes when the development machine and the server are on the same LAN, this is useful to emphasize the transition. You can see how the browser appears during the Ajax request in Figure 16-5.

Figure 16-5 The browser during the form submission request

Processing the Server Response

All that remains is to do something useful with the data that you get back from the server. For this chapter, I am going to use a simple table. You will learn about creating rich user interfaces with jQuery UI in the next part of this book, and I don't want to have to do by hand what I can do much more elegantly with the UI widgets. You can see the finished result in Figure 16-6.

Figure 16-6 Displaying the order summary

Listing 16-9 shows the complete document that supports this enhancement.

I'll break down the changes I made step by step.

Adding the New Form

The first thing that I did was add a new form to the static HTML part of the document, like this:

This is the heart of the new functionality. When the user submits their product selection to the server, the table in this form will be used to display the data you get back from the Ajax request.

I don't want to display the new form immediately, so I added it to the list of elements that I hide in the script, like this:

And, as you might expect by now, when there are new elements, there is new CSS to style them, as follows:

These styles ensure that the table is displayed in the middle of the browser window and the text in various columns is aligned to the correct edge.

Completing the Ajax Request

The next step was to complete the call to the ajax request, like this:

I removed the explicit delay in the complete function and added the dataFilter, converters, and success settings to the request.

I use the dataFilters setting to provide a function that transforms the JSON data I get from the server into something more useful. The server sends me a JSON string like this:

I parse the JSON data and restructure it so that I get this:

This format has two advantages. The first is that it is better suited for use with data templates because I can pass the products property to the tmpl method. The second is that I can check whether the user has selected any elements with products.length. These are two quite minor advantages, but I wanted to integrate as many of the features from the earlier chapters as possible. Notice that I have also replaced the name of the product (orchid, for example) with the plural name (Orchids).

Having already parsed the JSON data into a JavaScript object (using the parseJSON method, which I describe in Chapter 33), I want to disable the built-in converter, which will try to do the same thing. To that end, I have defined a custom converter for JSON, which just passes the data through without modification:

Processing the Data

For the success setting in the ajax method call, I specified the processServerResponse function, which I defined as follows:

If the data from the server contains product information, then I hide all of the elements in the document that I don't want (including the original form element and the additions I made in the script) and show the new form. I populate the table using the following data template:

This is a very simple template and produces a table row for each selected product. Finally, I set contents of the cells that display the total price and item count using the text method:

However, if the data from the server doesn't contain any product information (which indicates that the user has left all of the input element values as zero), then I do something very different. First I select the first of the input elements, like this:

I then create an object that contains a property whose name is the name value of the input element and whose value is a message to the user. I then call the validate method on the form element and the showErrors method on the result, like this:

This allows me to manually inject an error into the validation system and take advantage of all of the structure and formatting that I put in place earlier. I have to provide the name of an element so that the validation plugin can highlight where the error occurs, which is not ideal, as you can see in Figure 16-7.

Figure 16-7 Display the selection error

I am displaying a general message, but the highlighting is applied to just one input element. To deal with this, I remove the class that the validation plugin uses for highlighting, like this:

This produces the effect shown in Figure 16-8.

Figure 16-8 Removing the highlighting from the element associated with the error

Summary

In this chapter, I refactored the example to bring together the themes and features covered in this part of the book. I used Ajax widely (using both the shorthand and low-level methods), applied a pair of data templates, and used the validation plugin to check values locally and remotely (and to display an error manually).

In the next part of the book, you will turn your attention to jQuery UI, and the next time that you refactor the example document, it will have a very different appearance.