Functionality Overview

Before building anything, it's always helpful to understand exactly what you're building. Anyone can say they are going to emulate the functionality of Google Suggest, but what does that mean? The example you will build in this section has the following functionality:

• Typeahead: As the user is typing, the rest of the text box fills in with the best suggestion at the time. As the user continues to type, the text box automatically adjusts its suggestion. The suggested text always appears selected (highlighted). This should work no matter how fast the user types.

• Suggestions list: Also as the user is typing, a drop-down list of other suggestions is displayed. These suggestions are generated automatically while the user types so that there is no discernible delay.

• Keyboard controls: When the suggestions are displayed, the user is able to scroll up and down the list by using the up and down arrows on the keyboard and select a suggestion. Pressing Enter places the value into the text box and hides the suggestion list. The Esc key can also be used to hide the suggestions.

• Hide suggestions: The drop-down suggestion list is smart enough to hide itself whenever the text box is not used or when the browser window is hidden.

You probably didn't realize that Google Suggest was doing so much. This is the key with Ajax: you don't think about what's going on because it works in an intuitive way.

The HTML

The first step in any client-side component is to build the HTML that will be used. For the autosuggest text box, this includes the text box itself as well as the drop-down list of suggestions. You're probably familiar with the HTML text box:

<input type=" text" name=" txtAutosuggest" value="" />

In most cases, this line would be enough to use a text box. The problem is that some browsers (notably Internet Explorer on Windows and Mozilla Firefox on all operating systems) provide autocomplete functionality that drops down a list of suggestions based on values you've entered before. Since this would compete directly with the suggestions you'll be providing, this has to be turned off. To do so, set the autocomplete attribute to off:

<input type=" text" name=" txtAutosuggest" value="" autocomplete=" off" />

Now you can be assured that there will be no interference from the autocomplete browser behavior. The only other user interface component to design is the drop-down list of suggestions.

The suggestion drop-down list is nothing more than an absolutely positioned <div/> element that is positioned below the text box so as to give the illusion of being a drop-down list (see Figure 7-1).

Figure 7-1

Inside of this <div/> element are several other <div/> elements, one for each suggestion. By changing the style of these elements, it's possible to achieve the look of highlighting a given suggestion. The HTML to create the list displayed in Figure 7-1 is as follows:

<div class=" suggestions">
    <div class=" current">Maine</div>
    <div>Maryland</div>
    <div>Massachusetts</div>
    <div>Michigan</div>
    <div>Minnesota</div>
    <div>Mississippi</div>
    <div>Missouri</div>
    <div>Montana</div>
</div>

This HTML won't be coded directly into the main HTML file; instead, it will be created dynamically by JavaScript code. However, you need to know the general format of the HTML in order to create it appropriately.

Of course, some CSS is needed to make the drop-down list function properly. The outermost <div/> has a class of suggestions, which is defined as:

div.suggestions {
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    background-color: white;
    border: 1px solid black;
    position: absolute;
}

The first two lines of this CSS class are for browsers that support two forms of box sizing: content box and border box (for more information, read www.quirksmode.org/css/box.html). In quirks mode, Internet Explorer defaults to border box; in standards mode, Internet Explorer defaults to content box. Most other DOM-compliant browsers (Mozilla, Opera, and Safari) default to content box, meaning that there is a difference in how the <div/> element will be rendered among browsers. To provide for this, the first two lines of the CSS class set rendering to border box. The first line, -moz-box-sizing, is Mozilla-specific and used for older Mozilla browsers; the second line is for browsers that support the official CSS3 box-sizing property. Assuming that you use quirks mode in your page, this class will work just fine. (If you use standards mode, simply remove these first two lines.)

The remaining styles simply add a border and specify that the <div/> element be absolutely positioned.

Next, a little bit of formatting is needed for the drop-down list items:

div.suggestions div {
    cursor: default;
    padding: 0px 3px;
}

The first line specifies the default cursor (the arrow) to be displayed when the mouse is over an item in the drop-down list. Without this, the cursor would display as the caret, which is the normal cursor for text boxes and web pages in general. The user needs to believe that the drop-down item is not a part of the regular page flow, but an attachment to the text box, and changing the cursor helps. The second line simply applies some padding to the item (which you can modify as you wish).

Last, some CSS is needed to format the currently selected item in the drop-down list. When an item is selected, the background will be changed to blue and the text color will be changed to white. This provides a basic highlight that is typically used in drop-down menus:

div.suggestions div.current {
    background-color: #3366cc;
    color: white;
}

All these styles are to be contained in an external CSS file named autosuggest.css.

The Database Table

In order to easily query the states and provinces that match a particular text snippet, it is necessary to use a database table. There are a few open source database products that can be paired nicely with PHP, but the most common one is MySQL (available at www.mysql.org). Many web hosting companies that offer PHP hosting also offer one or more MySQL databases as well, so for this example, MySQL will be the database used.

The database table can be very simple for this example, although you may need more information to make it practical for your needs. To get this to work, you really need only a single column to store the state and province names. However, it's always best to define a primary key, so this table will include a second column containing an auto-incremented ID number for each state or province. The following SQL statement creates a table named StatesAndProvinces with two columns, Id and Name:

CREATE TABLE StatesAndProvinces (
    Id INT NOT NULL AUTO_INCREMENT,
    Name VARCHAR(255) NOT NULL,
    PRIMARY KEY (Id)
) COMMENT = 'States and Provinces';

Of course, the time-consuming part is to fill in state and province names from various countries around the world. The code download for this example, available at www.wrox.com, includes a SQL file that will populate the table with all U.S. states as well as one that will insert all Canadian provinces and territories.

Setting up this information in a database table enables you to quickly get a list of suggestions for text the user has typed in. If the user has typed the letter M, for example, you can run the following query to get the first five suggestions:

SELECT *
FROM StatesAndProvinces
WHERE Name LIKE 'M%'
ORDER BY Name ASC
LIMIT 0, 5

This statement returns a maximum of five suggestions, in alphabetical order, for all names starting with M. Later, this will be used in the PHP code that returns the suggestions.

The Architecture

In Chapter 1, you saw the basic architecture of an Ajax solution involving the user interface and Ajax engine on the client. The autosuggest architecture follows this general format, where the user interface is the autosuggest control and the Ajax engine is a suggestion provider (see Figure 7-2).

Figure 7-2

In this architecture, the autosuggest control has no idea where the suggestions are coming from; they could be coming from the client or the server. All the autosuggest control knows is how to call the suggestion provider to get suggestions for the text contained within the text box. The suggestion provider handles all the server communication and notifies the autosuggest control when the suggestions are available. To accomplish this, both the autosuggest control and the suggestion provider need to implement specific interfaces so that each knows what method to call on the other.

The Classes

Two classes are necessary to represent the two client-side components of the autosuggest functionality, appropriately called AutoSuggestControl and SuggestionProvider. The AutoSuggestControl is assigned a SuggestionProvider when it is created so that all requests go through it. The SuggestionProvider has only one method, requestSuggestions(), which is called by the AutoSuggestControl whenever suggestions are needed. This method takes two arguments: the AutoSuggestControl itself and a Boolean value indicating whether the control should type ahead when the suggestions are returned.

When the suggestions have been retrieved, the SuggestionProvider calls the autosuggest() method of the AutoSuggestControl, passing in the array of suggestions as well as the typeahead flag that was passed into it. This allows for a delay between the request for suggestions and the response, making it possible to use asynchronous requests. This approach sounds more complicated than it is; Figure 7-3 represents the interaction between these two objects in a clearer manner.

Figure 7-3

With the architecture designed, it's time to start coding.

The AutoSuggest Control

The AutoSuggestControl class is the wrapper for all autosuggest functionality. To work properly, the control needs to know which text box to work on and the suggestion provider to use. This makes for a relatively simple constructor:

function AutoSuggestControl(oTextbox, oProvider) {
    this.provider = oProvider;
    this.textbox = oTextbox;
}

It's upon this simple base that the complex functionality of an autosuggest text box will be built.

Since the AutoSuggestControl class is quite complicated, it's much simpler to break up its explanation into specific types of functionality. The following sections build on each other, and the complete code can be downloaded from www.wrox.com.

var oTextbox = document.getElementById("txtState");
oTextbox.select();

var oRange = oTextbox.createTextRange();
oRange.moveStart("character", 0);
oRange.moveEnd("character", 3 - oTextbox.value.length);
oRange.select();
oTextbox.focus();

oTextbox.setSelectionRange(0,3);
oTextbox.focus();

AutoSuggestControl.prototype.selectRange = function (iStart, iEnd) {
    if (this.textbox.createTextRange) {
        var oRange = this.textbox.createTextRange();
        oRange.moveStart("character", iStart);
        oRange.moveEnd("character", iEnd- this.textbox.value.length);
        oRange.select();
    } else if (this.textbox.setSelectionRange) {
        this.textbox.setSelectionRange(iStart, iEnd);
    }

    this.textbox.focus();
};

AutoSuggestControl.prototype.typeAhead = function (sSuggestion) {
    if (this.textbox.createTextRange || this.textbox.setSelectionRange) {
        var iLen = this.textbox.value.length;
        this.textbox.value = sSuggestion;
        this.selectRange(iLen, sSuggestion.length);
    }
};

AutoSuggestControl.prototype.autosuggest = function (aSuggestions) {
    if (aSuggestions.length > 0) {
        this.typeAhead(aSuggestions[0]);
    }
};

AutoSuggestControl.prototype.handleKeyUp = function (oEvent) {
    var iKeyCode = oEvent.keyCode;

     if (iKeyCode < 32 || (iKeyCode >= 33 && iKeyCode <= 46)
         || (iKeyCode >= 112 && iKeyCode <= 123)) {

        //ignore
    } else {
        this.provider.requestSuggestions(this);
    }
};

AutoSuggestControl.prototype.init = function () {
    var oThis = this;
    this.textbox.onkeyup = function (oEvent) {
        if (!oEvent) {
            oEvent = window.event;
        }
        oThis.handleKeyUp(oEvent);
    };
};

function AutoSuggestControl(oTextbox, oProvider) {
    this.provider = oProvider;
    this.textbox = oTextbox;
    this.init();
}

Showing Multiple Suggestions

Earlier in the chapter you took a look at the HTML and CSS used for the drop-down list of suggestions. Now the task is to create the HTML programmatically and apply the CSS to create the actual functionality; this is a multistep process. First, a property is needed to store the <div/> element because various methods of the AutoSuggestControl need access to it. This property is called layer and is initially set to null:

function AutoSuggestControl(oTextbox, oProvider) {
    this.layer = null;
    this.provider = oProvider;
    this.textbox = oTextbox;
    this.init();
}

The drop-down list will be created after you define a few simple methods to help control its behavior. The simplest method is hideSuggestions(), which hides the drop-down list after it has been shown:

AutoSuggestControl.prototype.hideSuggestions = function () {
    this.layer.style.visibility = "hidden";
};

Next, a method is needed for highlighting the current suggestion in the drop-down list. The highlightSuggestion() method accepts a single argument, which is the <div/> element containing the current suggestion. The purpose of this method is to set the <div/> element's class attribute to current on the current suggestion and clear the class attribute on all others in the list. Doing so provides a highlighting effect on the drop-down list similar to the regular form controls. The algorithm is quite simple: iterate through the child nodes of the layer. If the child node is equal to the node that was passed in, set the class to current; otherwise, clear the class attribute by setting it to an empty string:

AutoSuggestControl.prototype.highlightSuggestion = function (oSuggestionNode) {

    for (var i=0; i < this.layer.childNodes.length; i++) {
        var oNode = this.layer.childNodes[i];
        if (oNode == oSuggestionNode) {
            oNode.className = "current"
        } else if (oNode.className == "current") {
            oNode.className = "";
        }
    }
};

With these two methods defined, it's time to create the drop-down list <div/>. The createDropDown() method creates the outermost <div/> element and defines the event handlers for the drop-down list. To create the <div/> element, use the createElement() method and then assign the various styling properties:

AutoSuggestControl.prototype.createDropDown = function () {

    this.layer = document.createElement("div");
    this.layer.className = "suggestions";
    this.layer.style.visibility = "hidden";
    this.layer.style.width = this.textbox.offsetWidth;
    document.body.appendChild(this.layer);

    //more code to come
};

This code first creates the <div/> element and assigns it to the layer property. From there, the className (equivalent to the class attribute) is set to suggestions, as is needed for the CSS to work properly. The next line hides the layer, since it should be invisible initially. Then, the width of the layer is set equal to the width of the text box by using the text box's offsetWidth property (this is optional depending on your individual needs). The very last line adds the layer to the document. With the layer created, it's time to assign the event handlers to control it.

At this point, the only concern is making sure that the drop-down list is functional if the user uses the mouse. That is, when the drop-down list is visible, moving the mouse over a suggestion should highlight it. Likewise, when a suggestion is clicked on, it should be placed in the text box and the drop-down list should be hidden. To make this happen, you need to assign three event handlers: onmouseover, onmousedown, and onmouseup.

The onmouseover event handler is used simply to highlight the current suggestion; onmousedown is used to select the given suggestion (place the suggestion in the text box and hide the drop-down list); and onmouseup is used to set the focus back to the text box after a selection has been made. Because all these events are fired by the drop-down list itself, it's best just to use a single function for all of them, as follows:

AutoSuggestControl.prototype.createDropDown = function () {

    this.layer = document.createElement("div");
    this.layer.className = "suggestions";
    this.layer.style.visibility = "hidden";
    this.layer.style.width = this.textbox.offsetWidth;
    document.body.appendChild(this.layer);

    var oThis = this;

    this.layer.onmousedown = this.layer.onmouseup =
    this.layer.onmouseover = function (oEvent) {
        oEvent = oEvent || window.event;
        oTarget = oEvent.target || oEvent.srcElement;

        if (oEvent.type == "mousedown") {
            oThis.textbox.value = oTarget.firstChild.nodeValue;
            oThis.hideSuggestions();
        } else if (oEvent.type == "mouseover") {
            oThis.highlightSuggestion(oTarget);
        } else {
            oThis.textbox.focus();
        }
    };

};

The first part of this section is the assignment of oThis equal to the this object. This is necessary so that a reference to the AutoSuggestControl object is accessible from within the event handler. Next, a compound assignment occurs, assigning the same function as an event handler for onmousedown, onmouseup, and onmouseover. Inside of the function, the first two lines are used to account for the different event models (DOM and IE), using a logical OR (||) to assign the values for oEvent and oTarget. (The target will always be a <div/> element containing a suggestion.)

If the event being handled is mousedown, then set the value of the text box equal to the text inside of the event target. The text inside of the <div/> element is contained in a text node, which is the first child node. The actual text string is contained in the text node's nodeValue property. After the suggestion is placed into the text box, the drop-down list is hidden.

When the event being handled is mouseover, the event target is passed into the highlightSuggestion() method to provide the hover effect; when the event is mouseup, the focus is set back to the text box (this fires immediately after mousedown).

AutoSuggestControl.prototype.getLeft = function () {

    var oNode = this.textbox;
    var iLeft = 0;

    while(oNode.tagName != "BODY") {
        iLeft += oNode.offsetLeft;
        oNode = oNode.offsetParent;
    }

    return iLeft;
};

AutoSuggestControl.prototype.getTop = function () {

    var oNode = this.textbox;
    var iTop = 0;

    while(oNode.tagName != "BODY") {
        iTop += oNode.offsetTop;
        oNode = oNode.offsetParent;
    }

    return iTop;
};

AutoSuggestControl.prototype.showSuggestions = function (aSuggestions) {

    var oDiv = null;
    this.layer.innerHTML = "";

    for (var i=0; i < aSuggestions.length; i++) {
        oDiv = document.createElement("div");
        oDiv.appendChild(document.createTextNode(aSuggestions[i]));
        this.layer.appendChild(oDiv);
    }

    this.layer.style.left = this.getLeft() + "px";
    this.layer.style.top = (this.getTop()+this.textbox.offsetHeight) + "px";
    this.layer.style.visibility = "visible";
};

AutoSuggestControl.prototype.autosuggest = function (aSuggestions, bTypeAhead) {
    if (aSuggestions.length > 0) {
        if (bTypeAhead) {
            this.typeAhead(aSuggestions[0]);

        }
        this.showSuggestions(aSuggestions);
    } else {
        this.hideSuggestions();
    }
};

AutoSuggestControl.prototype.handleKeyUp = function (oEvent) {

    var iKeyCode = oEvent.keyCode;

    if (iKeyCode < 32 || (iKeyCode >= 33 && iKeyCode <= 46)
        || (iKeyCode >= 112 && iKeyCode <= 123)) {
        //ignore
    } else {
        this.provider.requestSuggestions(this, true);
    }
};

AutoSuggestControl.prototype.handleKeyUp = function (oEvent) {

    var iKeyCode = oEvent.keyCode;

    if (iKeyCode == 8 || iKeyCode == 46) {
        this.provider.requestSuggestions(this, false);

    } else if (iKeyCode < 32 || (iKeyCode >= 33 && iKeyCode <= 46)
               || (iKeyCode >= 112 && iKeyCode <= 123)) {
        //ignore
    } else {
        this.provider.requestSuggestions(this, true);
    }
};

function AutoSuggestControl(oTextbox, oProvider) {
    this.cur = -1;
    this.layer = null;
    this.provider = oProvider;
    this.textbox = oTextbox;
    this.userText = oTextbox.value;
    this.init();
}

AutoSuggestControl.prototype.goToSuggestion = function (iDiff) {
    var cSuggestionNodes = this.layer.childNodes;

    if (cSuggestionNodes.length > 0) {
        var oNode = null;

        if (iDiff > 0) {
            if (this.cur < cSuggestionNodes.length-1) {
                oNode = cSuggestionNodes[++this.cur];
            }
        } else {
            if (this.cur > 0) {
                oNode = cSuggestionNodes[--this.cur];
            }
        }

        if (oNode) {
            this.highlightSuggestion(oNode);
            this.textbox.value = oNode.firstChild.nodeValue;
        }
    }
};

AutoSuggestControl.prototype.autosuggest = function (aSuggestions, bTypeAhead){

    this.cur = -1;

    if (aSuggestions.length > 0) {
        if (bTypeAhead) {
           this.typeAhead(aSuggestions[0]);
        }

        this.showSuggestions(aSuggestions);
    } else {
        this.hideSuggestions();
    }
};

AutoSuggestControl.prototype.handleKeyUp = function (oEvent) {

    var iKeyCode = oEvent.keyCode;
    this.userText = this.textbox.value;

    if (iKeyCode == 8 || iKeyCode == 46) {
        this.provider.requestSuggestions(this, false);

    } else if (iKeyCode < 32 || (iKeyCode >= 33 && iKeyCode <= 46)

               || (iKeyCode >= 112 && iKeyCode <= 123)) {
        //ignore
    } else {
        this.provider.requestSuggestions(this, true);
    }
};

AutoSuggestControl.prototype.handleKeyDown = function (oEvent) {
    switch(oEvent.keyCode) {
        case 38: //up arrow
            this.goToSuggestion(-1);
            break;
        case 40: //down arrow
            this.goToSuggestion(1);
            break;
        case 27: //esc
            this.textbox.value = this.userText;
            this.selectRange(this.userText.length, 0);
            /* falls through */
        case 13: //enter
            this.hideSuggestions();
            oEvent.returnValue = false;
            if (oEvent.preventDefault) {
                oEvent.preventDefault();
            }
            break;
    }
};

AutoSuggestControl.prototype.init = function () {

     var oThis = this;

    this.textbox.onkeyup = function (oEvent) {
        if (!oEvent) {
            oEvent = window.event;
        }

        oThis.handleKeyUp(oEvent);
    };

    this.textbox.onkeydown = function (oEvent) {

        if (!oEvent) {
            oEvent = window.event;
        }

        oThis.handleKeyDown(oEvent);
    };

    //more code to come
};

AutoSuggestControl.prototype.init = function () {

    var oThis = this;

    this.textbox.onkeyup = function (oEvent) {
        if (!oEvent) {
            oEvent = window.event;

        }

        oThis.handleKeyUp(oEvent);
    };

    this.textbox.onkeydown = function (oEvent) {

        if (!oEvent) {
            oEvent = window.event;
        }

        oThis.handleKeyDown(oEvent);
    };

    this.textbox.onblur = function () {
        oThis.hideSuggestions();
    };

    this.createDropDown();
};

function AutoSuggestControl(oTextbox, oProvider) {
    this.cur = -1;
    this.layer = null;
    this.provider = oProvider;
    this.textbox = oTextbox;
    this.timeoutId = null;
    this.userText = oTextbox.value;
    this.init();
}

AutoSuggestControl.prototype.handleKeyUp = function (oEvent /*:Event*/) {

    var iKeyCode = oEvent.keyCode;
    var oThis = this;

    this.userText = this.textbox.value;

    clearTimeout(this.timeoutId);

    if (iKeyCode == 8 || iKeyCode == 46) {

        this.timeoutId = setTimeout(function () {
            oThis.provider.requestSuggestions(oThis, false);
        }, 250);

    } else if (iKeyCode < 32 || (iKeyCode >= 33 && iKeyCode < 46)
               || (iKeyCode >= 112 && iKeyCode <= 123)) {
        //ignore
    } else {
        this.timeoutId = setTimeout(function () {
            oThis.provider.requestSuggestions(oThis, true);
        }, 250);
    }
};

The Suggestion Provider

The SuggestionProvider class is relatively simple compared to the AutoSuggestControl since it has only one purpose: to request suggestions from the server and forward them to the control. To do so, SuggestionProvider needs an instance of XmlHttp. Instead of using a new object for each request, the same object will be used over and over, to avoid the overhead of creating and destroying objects in rapid succession. This single instance is created using the zXML library's zXmlHttp factory and stored in a property called http:

function SuggestionProvider() {
    this.http = zXmlHttp.createRequest();
}

The lone method of the suggestion provider is requestSuggestions(), which you may remember from the architecture discussion. This method accepts two arguments: the AutoSuggestControl to work on and a flag indicating whether typeahead should be used. The complete code is as follows:

SuggestionProvider.prototype.requestSuggestions = function (oAutoSuggestControl,
                                                            bTypeAhead) {

    var oHttp = this.http;

    //cancel any active requests
    if (oHttp.readyState != 0) {
        oHttp.abort();
    }

    //define the data
    var oData = {
        requesting: "StatesAndProvinces",
        text: oAutoSuggestControl.userText,
        limit: 5
    };

    //open connection to server
    oHttp.open("post", "suggestions.php", true);
    oHttp.onreadystatechange = function () {
        if (oHttp.readyState == 4) {
            //evaluate the returned text JavaScript (an array)
            var aSuggestions = JSON.parse(oHttp.responseText);

            //provide suggestions to the control
            oAutoSuggestControl.autosuggest(aSuggestions, bTypeAhead);
        }
    };

    //send the request
    oHttp.send(JSON.stringify(oData));

};

The first line inside the method sets oHttp equal to the stored XmlHttp object. This is done simply for convenience and keeping the code clean. Next, you check to make sure that there isn't already a request waiting for a response. If the XmlHttp object is ready to be used cleanly, its readyState will be 0; otherwise, you must cancel the existing request (by calling abort()) before making another request.

Because the data being sent to the server is to be JSON-encoded, you first need to create an object (oData) to hold the information. There are three pieces of information being sent: the table to get the data out of, the current value in the text box, and the maximum number of suggestions to retrieve (5). The maximum number of suggestions is important because it prevents long database queries from being executed repeatedly.

Next, a request is opened to suggestions.php, the server-side component of the control. This request is asynchronous (last argument of open() is set to true), so it's necessary to provide an onreadystate-change event handler. The event handler first checks to ensure that the readyState is 4, and then parses the returned text as a JSON array of values. This array, along with the original typeahead flag, is then passed back to the AutoSuggestControl via the autosuggest() method.

The last step in this method is, of course, to send the request. Note that since the request is doing a POST, the data has to be passed into the send() method. The oData object is first encoded into JSON before being sent.

With that, the SuggestionProvider class is complete. The only thing left to do is to write the suggestions.php file that uses the data that is sent.

The Server-Side Component

In many ways, the server-side component for the autosuggest control is the most straightforward: it's just a single thread being executed from top to bottom, with no functions or methods to be concerned about. Note that because this is a PHP page, all the code discussed in this section must be contained within a PHP code block (<?php . . . ?>).

The first part of the page is to set the content type to text/plain, indicating that this is a plain text file and shouldn't be handled as anything else. You can optionally specify a character set, but make sure that it is Unicode-compatible, such as UTF-8, since all Unicode characters are valid in JavaScript. Here's the line that accomplishes assigning the content type:

header("Content-Type: text/plain; charset=utf-8");

Next, include the JSON-PHP library and create a new instance of the JSON object:

require_once("JSON.php");
$oJSON = new JSON();

Normally when data is sent to a PHP page, you can use $_GET, $_POST, or $_REQUEST to retrieve it. In this case, however, the data isn't being sent in traditional name/value pairs; instead, it's being sent as a JSON string, and there is no built-in support for this specific type of data. Instead, you need to get the body of the request and decode it manually. The body of any request is available in PHP through $HTTP_RAW_POST_DATA, which contains the original, encoded content that was sent. Because the JSON string wasn't URL encoded, however, you can just pass this directly into the decode() method to reconstitute the oData object:

$oData = $oJSON->decode($HTTP_RAW_POST_DATA);

You'll also need an array to store the suggestions in:

$aSuggestions = array();

If there are no suggestions, no values will be added to the array and an empty array ([]) will be returned to the client.

Before tapping the database for suggestions, make sure that there is actually text in the text box. Suggestions are requested when the user hits Delete or Backspace, so there's a possibility that the text box could be empty. You should check for this first by seeing if the length of the text is greater than 0; if so, you can continue on to query the database.

The query string itself is built up from the data submitting from the client. The name of the table, the LIKE statement, and the number of results to return are all incorporated into the SQL query. The following code creates a connection to the database, executes the query, and then adds the results of the query to the $aSuggestions array:

if (strlen($oData->text) > 0) {

    //create the SQL query string
    $sQuery = "Select Name from ".$oData->requesting." where Name like '".
              $oData->text."%' order by Name ASC limit 0,".$oData->limit;

    //make the database connection
    $oLink = mysql_connect($sDBServer,$sDBUsername,$sDBPassword);
    @mysql_select_db($sDBName) or die("Unable to open database");

    if($oResult = mysql_query($sQuery)) {
        while ($aValues = mysql_fetch_array($oResult,MYSQL_ASSOC)) {
            array_push($aSuggestions, $aValues['Name']);
        }
    }

    mysql_free_result($oResult);
    mysql_close($oLink);
}

This code should be fairly familiar to you as it is the same basic algorithm used throughout the book to access a MySQL database using PHP. (You must fill in the appropriate values for $sDBServer, $sDBUsername, and $sDBPassword to reflect your database settings.) The only unique part is that the results are being stored in an array, which facilitates the conversion into a JSON string to be sent back to the client.

The actual encoding is the very last step of the page. In one step, you can encode the array and output it to the page:

echo($oJSON->encode($aSuggestions));

Now it's up to the client to parse the JSON code correctly.

The Client-Side Component

So far, you've built the HTML, CSS, JavaScript, and PHP to be used by the autosuggest control. The only thing left to do is to assemble it all into a page that you can use. The most important thing to remember is the inclusion of all necessary JavaScript files. In this case, you need to include json.js, zxml.js, and autosuggest.js. Also important is the inclusion of the style sheet file, autosuggest.css.

It's also necessary to instantiate the AutoSuggestControl after the page has completely loaded, using the onload event handler. The complete code for the example page is:

<html>
    <head>
        <title>Autosuggest Example</title>
        <script type=" text/javascript" src=" json.js"></script>
        <script type=" text/javascript" src=" zxml.js"></script>
        <script type=" text/javascript" src=" autosuggest.js"></script>
        <link rel=" stylesheet" type=" text/css" href=" autosuggest.css" />
        <script type=" text/javascript">
            window.onload = function () {
                var oTextbox = new
AutoSuggestControl(document.getElementById("txtState"), new SuggestionProvider());
            }
        </script>
    </head>
    <body>
        <form method=" post" action=" your_action.php">
            <table border="0">
                <tr>
                    <td>Name:</td>
                    <td><input type=" text" name=" txtName" id=" txtName" /></td>
                </tr>
                <tr>
                   <td>Address 1:</td>
                   <td><input type=" text" name=" txtAddress1"
                              id=" txtAddress1" /></td>
                </tr>
                <tr>
                   <td>Address 2:</td>
                   <td><input type=" text" name=" txtAddress2"
                              id=" txtAddress2" /></td>
                </tr>
                <tr>
                   <td>City:</td>
                   <td><input type=" text" name=" txtCity" id=" txtCity" /></td>
                </tr>
                <tr>
                   <td>State/Province:</td>
                   <td><input type=" text" name=" txtState" id=" txtState"
                              autocomplete=" off" /></td>
                </tr>
                <tr>
                    <td>Zip Code:</td>
                    <td><input type=" text" name=" txtZip" id=" txtZip" /></td>
                </tr>
                <tr>
                    <td>Country:</td>
                    <td><input type=" text" name=" txtCountry"
                               id=" txtCountry" /></td>
                </tr>
            </table>
            <input type=" submit" value=" Save Information" />
        </form>
    </body>
</html>

Note that once the necessary files are included, you need to place only one line of JavaScript in the window.onload event handler to set up the functionality:

var oTextbox = new AutoSuggestControl(document.getElementById("txtState"),
                                      new SuggestionProvider());

This line creates a new AutoSuggestControl object, passing a reference to the text box with the id of txtState and a new SuggestionProvider() class. It's important that this line be executed in the onload event handler because document.getElementById() isn't 100 percent accurate until the entire page has been loaded.

The example itself is done in a way in which this control may be used: filling in personal information. This could be a page where customers can update their information or it could be a shipping form. Whichever way you choose to use this functionality, it is sure to improve the usability of your form. An autosuggest control, although not as flashy as some Ajax solutions, really is a good example of how Ajax can be used in a non-interfering way.