Practical prototype and scipt.aculo.us part 49 pptx

You’ve probably figured it out: Ajax.Autocompleter is sending out an Ajax request each time the text box’s value changes.. The ordinary text transforms into a compact form—a text box pre

Now we’ll add the JavaScript that sets up the autocompleter on page load The

syn-tax for Ajax.Autocompleteris 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.htmland autocomplete_players.phpare 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.Autocompleterdoes 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.Autocompleterwon’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 Autocompletershare some configuration options:

• tokenslets 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 tokensoption 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: [',', ';' ] });

• frequencycontrols 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

• minCharscontrols how many characters need to be typed before the autocompleter presents suggestions It’s set to 1by 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 Autocompleterat important points:

• onShowand onHidecontrol how the completion menu reveals and hides itself If

specified, they will replace the default hide/show behaviors (By default, the menu

uses Effect.Appearand 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)

• updateElementand afterUpdateElementare used to replace or augment what takes place when the user selects a suggestion from the menu

updateElementtakes one argument—the lithat was chosen—and replaces the

default logic (i.e., set the value of the text box to the text content of the li)

afterUpdateElementtakes two arguments—the inputelement and the lielement—

and fires after the updateElementcallback

Adding In-Place Editing Functionality

Ajax.InPlaceEditoris 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

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 server when a value has been changed)

As you may have guessed, the script.aculo.us Ajax.InPlaceEditorhandles all these details The wonders never cease

Using Ajax.InPlaceEditor

The syntax for declaring a new Ajax.InPlaceEditoris the following:

new Ajax.InPlaceEditor(element, url, options);

As usual, elementrefers to the element we want to make editable, and optionsrefers

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>

<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 h1that contains the team name is annotated with an ID so that we can pass it

easily into the Ajax.InPlaceEditorconstructor 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 urlargument 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 h1element, 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 h1to its initial state

• Clicking the h1should 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

Create a new file called save.phpin 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.phpfile should look like:

<?php echo $_REQUEST['value']; ?>

Yeah, that’s the whole file Save it

Now we’ll reload inplaceeditor.htmland 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.Highlightcall 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.phpscript 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