Now we’ll add the JavaScript that sets up the autocompleter on page load. The syn- tax for Ajax.Autocompleter is identical to that of Autocompleter.Local, except for the third argument: new Ajax.Autocompleter(inputElement, updateElement, url, options); Instead of array, we provide the URL for the Ajax request. We can give a simple rela- tive URL, since index.html and autocomplete_players.php are in the same directory: <script type="text/javascript"> document.observe('dom:loaded', function() { new Ajax.Autocompleter('player_name', 'player_suggestions', 'autocomplete_players.php'); }); </script> Reload the page. Make sure the Firebug console is visible. Click the text box, but this time type very slowly. First, type a J, and then look at the console (see Figure 12-5). Figure 12-5. Line indicating an Ajax request went out A line appears in the console to tell us that an Ajax request went out. Look at the details of the request, specifically the Post and Response tabs. Now move back to the text field and add an A, and then an M. There will be two more logged Ajax calls in the console. You’ve probably figured it out: Ajax.Autocompleter is sending out an Ajax request each time the text box’s value changes. Seems wasteful, doesn’t it? If the Internet were a series of tubes, this is the sort of thing that would clog them up. In fact, Ajax.Autocompleter does some clever throttling: it waits for a pause in the input before it sends out a request. To see for yourself, clear the text field, and then type “James” at your normal typing speed. Unless you’re a hunt-and-peck typist, Ajax.Autocompleter won’t make a request until you’ve pressed all five keys. Common Options and Features Let’s not forget about the fourth argument—the one that lets us go under the hood. The two versions of Autocompleter share some configuration options: CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS 285 • tokens lets you “reset” the suggestions every time a given key is pressed. Think of an e-mail client: when you compose a new message, most clients display suggestions as you type in the To and CC fields of the message window. Addresses are delimited by semicolons; pressing the semicolon key tells the client that you’ve entered one address and are ready to enter another. The tokens option accepts either a string or an array of strings. It lets you specify delimiters for your suggestions. The following code will split on commas and semi- colons: new Ajax.Autocompleter('player_name', 'player_suggestions', 'autocomplete_players.php', { tokens: [',', ';' ] }); • frequency controls how long of a pause, in seconds, is needed to trigger sugges- tions. (This is the source of the “throttling” described previously.) Naturally, this behavior is more useful with the Ajax flavor—if the remote server is sluggish to respond, you may want to make this value larger than the default of 0.4. • minChars controls how many characters need to be typed before the autocompleter presents suggestions. It’s set to 1 by default, but if the suggestion bank is especially large, the list of suggestions after one character will be long, unwieldy, and unhelp- ful. Also, raising this value is another way to reduce the number of Ajax requests made by Ajax.Autocompleter. This option is token-aware; if you’ve specified any tokens, the autocompleter will wait the proper number of keystrokes after each token before it starts offering suggestions. Several callback options let you hook into Autocompleter at important points: • onShow and onHide control how the completion menu reveals and hides itself. If specified, they will replace the default hide/show behaviors. (By default, the menu uses Effect.Appear and Effect.Fade.) If you override onShow, be prepared to handle the sizing and positioning of the menu on your own. These callback functions take two parameters: the text box and the menu con- tainer (i.e., the first two arguments passed to the constructor). • updateElement and afterUpdateElement are used to replace or augment what takes place when the user selects a suggestion from the menu. updateElement takes one argument—the li that was chosen—and replaces the default logic (i.e., set the value of the text box to the text content of the li). afterUpdateElement takes two arguments—the input element and the li element— and fires after the updateElement callback. CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS286 Adding In-Place Editing Functionality Ajax.InPlaceEditor is a script.aculo.us class for a UI pattern that is becoming more and more common on web sites. Picture the following: 1. You’re on the page for your fantasy football team. It displays your team’s name and a roster of your players. 2. You move your mouse over the team name and notice that the background color changes slightly. You click. The ordinary text transforms into a compact form—a text box prepopulated with your existing team name and a save button alongside it. Farther to the right is a cancel link that restores the original view. 3. You place focus in the text box and make a change to your team name. You click the save button. After a short pause, the original view is restored—except that the new team name is now shown (see Figure 12-6). Figure 12-6. The user workflow for an Ajax in-place editor CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS 287 For obvious reasons, this is called an in-place editor. This pattern, when executed well, can obviate the administration section—the back end of a content management system where all the editing is done. Instead, the read mode and edit mode are merged. The scenario just described illustrates how this pattern allows a fantasy owner to change her team name. Naturally, permissions would be important—when she’s on her own team’s page, her team’s name could be edited, but she’d be prevented from editing the names of her opponents’ teams. Let’s think through how to turn this user workflow into code. We’ll need to represent the content in two different ways: read mode and edit mode. Read mode will be the ele- ment’s ordinary markup; edit mode will be an HTML form with a text box and an OK button. We’ll also insert a cancel link in case the user changes his mind. To pull this off, we’ll need help from the DOM (to switch dynamically from a read view to an edit view) and Ajax (to tell the ser ver when a value has been changed). As you may have guessed, the script.aculo.us Ajax.InPlaceEditor handles all these details. The wonders never cease. Using Ajax.InPlaceEditor The syntax for declaring a new Ajax.InPlaceEditor is the following: new Ajax.InPlaceEditor(element, url, options); As usual, element refers to the element we want to make editable, and options refers to our object of configuration parameters. The second argument, url, specifies the URL that should be contacted in order to save the data. Let’s create a new page called inplaceeditor.html. It won’t need much markup—just an element with text that we can edit. ■Note As with the previous example, for this part you’ll need to be running a web server (either locally or remotely) that supports PHP. Naturally, the concept is similar for other server environments. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title>Chapter 12</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> <script src="prototype.js" type="text/javascript"""></script> <script src="scriptaculous.js" type="text/javascript"""></script> CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS288 <style type="text/css" media="screen"> body { font: 67.5% "Lucida Grande", Tahoma, sans-serif; } </style> </head> <body> <h1 id="team_name">The Fighting Federalists</h1> </body> </html> The h1 that contains the team name is annotated with an ID so that we can pass it easily into the Ajax.InPlaceEditor constructor. So let’s add a code block to initialize the in-place editor when the DOM is ready. Add this to the head of your document: <script type="text/javascript"> document.observe('dom:loaded', function() { new Ajax.InPlaceEditor('team_name', 'save.php'); }); </script> We don’t need to add any configuration options yet. We’ve set the url argument to a URL that doesn’t exist yet, but we’ll take care of that later. This one line is enough to hook up all the client-side behaviors for the in-place editor. Open the page in a browser, and check that all of these behaviors work: • When you move your mouse over the h1 element, you should see its background color change to a subtle yellow, inviting you to click it. • When you click, the element should be replaced with a text box, a button that says “ok,” and a link that says “cancel.” • The text in the text box should be highlighted already, so that you can type over it immediately. • Clicking the “cancel” link should restore the h1 to its initial state. • Clicking the h1 should bring up the form once again. We’ve tested everything except submitting the form—for that, we’ll need to write a script that will receive the save request. CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS 289 Create a new file called save.php in the same directory as inplaceeditor.html. The in- place editor will, when saved, make an HTTP POST request to the given URL with a value parameter; that’s the name of our text box. Its value will be whatever the user typed into the text box. In response, the script should send as output whatever the new value of the element should be. This value will nearly always be the same one that the script received. (A pro- duction script would also want to store the new value, but we needn’t bother.) So we need only write a PHP script that echoes the value we give it. Here’s what your save.php file should look like: <?php echo $_REQUEST['value']; ?> Yeah, that’s the whole file. Save it. Now we’ll reload inplaceeditor.html and try an actual save. Click the element, rename your team, and click the “ok” button. That was fast, wasn’t it? An instant after you clicked the button, the in-place editor returned to its read state, but with the new value. An Effect.Highlight call makes it clear to the user that the value is “fresh.” If you’re trying out these examples on a remote server, it probably took a bit longer; but those of us who are running a local web server will need to introduce some fake latency to better simulate the lag of an HTTP round trip. We can tell our save.php script to wait for a second before responding: <?php sleep(1); echo $_REQUEST['value']; ?> After adding this line to save.php, try modifying the value in our in-place editor once more (see Figure 12-7). Now you can see much more clearly how it works. As soon as you click the “ok” button, the edit mode disappears and is replaced with a “Saving . . .” mes- sage while the Ajax request is made. When the browser receives the response, it switches back to the in-place editor’s read mode. CHAPTER 12 ■ ADVANCED CONTROLS: AUTOCOMPLETERS, IN-PLACE EDITORS, AND SLIDERS290 . points: • onShow and onHide control how the completion menu reveals and hides itself. If specified, they will replace the default hide/show behaviors. (By default, the menu uses Effect.Appear and Effect.Fade.). constructor). • updateElement and afterUpdateElement are used to replace or augment what takes place when the user selects a suggestion from the menu. updateElement takes one argument—the li that was chosen and replaces. script .aculo. us class for a UI pattern that is becoming more and more common on web sites. Picture the following: 1. You’re on the page for your fantasy football team. It displays your team’s name and a