To swap in another image file, you just use the attr() function (page 137) to set the
tag’s src property to a new file, like this:
$('#photo').attr('src','images/newImage.jpg');
NOTE When you change the src property of an image using JavaScript, the path to the image file is
based on the page location, not the location of the JavaScript code. This point can be confusing when you use
an external JavaScript file (page 15) located in a different folder. In the example above, the web browser would
try to download the file newImage.jpg from a folder named images, which is located in the same folder as the
web page. That method works even if the JavaScript code is included in an external file located in another folder
elsewhere on the site. Accordingly, it’s often easier to use root-relative links inside external JavaScript files (see
the box on page 11 for more information on the different link types).
Changing an image’s src attribute doesn’t change any of the 
You could replace that image with another 
');
jQuery’s replaceWith() method replaces the current selection with whatever HTML
you give it. Using this method you can set different src, alt, width, and height attributes in the string you provide to replaceWith()—for example: will also work. 3. Add jQuery’s $(document).ready() function to your page: $(document).ready(function() { }); // end ready 4. Use jQuery to select the
and call the dialog function:
$(document).ready(function() {
$('#hello').dialog();
}); // end ready
In this example, you’re using $('#hello') because that’s the ID you gave the
in step 2, but you can use any of jQuery’s many ways of selecting elements
(page 119) to select the dialog HTML and turn it into a dialog box.
These steps will make the dialog box appear as soon as the page loads. This setup
is good for whenever you need to give your site’s visitors an urgent notice like “This
site will be offline for routine maintenance from 3:00–4:00 a.m.,” or you want to pop
up an ad before they can read the content on your site. In the next section, you’ll see
how to keep the dialog box hidden when the page loads and only open it based on
an event. But first, here’s how to create your first dialog box.
Mini-Tutorial: Creating a Dialog Box
Now that you know how the Dialog widget works, take it for a quick spin by adding
a basic dialog box that appears when the page loads.
306
JAVASCRIPT & JQUERY: THE MISSING MANUAL
NOTE
ADDING
MESSAGES
WITH DIALOG
BOXES
See the note on page 12 for information on how to download the tutorial files.
1. In a text editor, open the file hello_world.html in the chapter09 folder.
This file already contains a link to the jQuery file and the $(document).ready()
function (page 160), but you have to link to the jQuery UI CSS and JavaScript files.
FIGURE 9-4
jQuery UI’s Dialog widget
makes it very easy to
add dialog boxes that
match the look and feel of
your site.
2. Add the lines in bold to the page’s section:
Notice that jQuery UI’s style sheet goes before the site.css file, and the jQuery
UI file is linked after the jQuery file. Now it’s time to add the HTML that makes
up the dialog box.
3. Locate the empty line, just below the HTML comment and type:
Next, you’ll turn this div into a dialog box.
Chapter 9: Expanding Your Interface
307
ADDING
MESSAGES
WITH DIALOG
BOXES
4. In the empty line inside the $(document).ready() function, add the bolded
line below:
$(document).ready(function() {
$('#hello').dialog();
}); // end ready
This selects the
A jQuery UI Dialog Box
you just added and turns it into a dialog box. It really is
that simple.
5. Save the page and preview it in a web browser.
A dialog box appears. You can move the dialog box by clicking the orange title
bar and dragging it around the screen. You can even drag any of the four corners
of the dialog box to make the box larger or smaller. Grab the title area again and
notice that the cursor changes to a four-way arrow. That’s not your regular old
browser behavior—it’s one of the little details programmed right into jQuery UI.
You’ll find the finished version of this tutorial in the complete_hello_world.
html file.
Setting Dialog Box Properties
You can set various properties of the dialog box—like its height, width, and how it
animates on and off the screen—by sending the dialog() function a list of property
names and values in an object. As you read on page 136, an object literal is a group
of name/value pairs enclosed in braces, like this:
{
name : 'Dave',
awesomeAuthor : true
}
You pass an object with options the plug-in understands when you call the dialog()
function. For example, say you didn’t want visitors to be able to either drag or resize
a dialog box. You’d just pass an object literal with two dialog options, like this:
$('#hello').dialog({
draggable : false,
resizable : false
});
The Dialog widget is programmed to turn off the dragging ability when the draggable property is set to false, and prevent resizing of the dialog when the resizable
property is set to false. Here are some of the most useful properties:
• draggable. Set this property to false to keep the dialog box locked in place
on the screen and prevent visitors from dragging it around. (If you want to let
visitors drag the dialog around, you don’t have to do anything; that’s the normal
behavior of the Dialog widget.)
308
JAVASCRIPT & JQUERY: THE MISSING MANUAL
• resizable. Set this property to false to keep the dialog box at its default size
and prevent visitors from making it bigger or smaller. (Again, if you want to
let visitors resize the dialog, you don’t have to do anything; that’s the normal
behavior.)
ADDING
MESSAGES
WITH DIALOG
BOXES
• height and width. Normally, jQuery UI makes a dialog box just big enough to
display all of the content in it. But you can control this behavior by specifying
an exact height and width in pixels. For example, if you wanted the dialog box
to be 600 pixels wide and 400 pixels tall, you could add this code to the object
literal you pass to the dialog:
width: 600,
height: 400
You can use only pixels (no percentage or em values), and you leave off the
px you’d normally attach to a CSS pixel value. If you set the width and height
and there’s more content inside that dialog box than will fit, jQuery UI will add
a scroll bar inside the dialog box. Visitors can then scroll down to see all of the
content in the dialog box. (This is the kind of behavior you see on many “Terms
and Conditions” pop-up windows, where you have to keep scrolling for a few
days in order to read all of the fine print.)
You don’t have to set both properties. Maybe you want to make sure that the
dialog box is a certain width, but you don’t care how tall it is. In that case, just
set the width property.
• Minimum width and heights. You can tell the dialog widget to make a dialog
at least a certain width and height by specifying values for the minWidth and
minHeight properties. For example, if you wanted a dialog box to be at least
600 pixels wide and 400 pixels tall, you’d set the properties like this:
minWidth: 600,
minHeight: 400
When you set a minimum height and width, jQuery UI may make the dialog box
bigger than those values but not smaller. In other words, if you put more content
than will fit inside the dialog box, jQuery UI will expand the dialog enough to
show all of the content.
• Maximum width and heights. You can also tell the dialog widget that it can’t
make the dialog box wider than a certain value or taller than a certain value
with the maxWidth and maxHeight properties. For example, if you wanted a
dialog box to be at most 600 pixels wide and 400 pixels tall, you’d set the
properties like this:
maxWidth: 600,
maxHeight: 400
If you don’t have much content inside the box, jQuery UI will make the dialog
smaller than these values, but never bigger. If the content won’t fit within the
Chapter 9: Expanding Your Interface
309
ADDING
MESSAGES
WITH DIALOG
BOXES
dialog box, jQuery UI adds a scrollbar so visitors can scroll down and read all
of the content.
• modal. A modal dialog box is used to lock a visitor’s attention on a message and
prevent her from doing anything else until she’s closed the dialog box. When
a modal dialog box opens, the visitor can’t click anywhere else on the page: in
fact, a dark transparent overlay settles over the page, so it’s difficult to even
read. Use modal dialog boxes when you don’t want a visitor to proceed until
she’s read the message and perhaps made an important decision: “Are you sure
you want to delete every episode of Dr. Who from your video library?” To make
a dialog box modal, just set the modal property to true:
modal: true
NOTE For a complete list of options as well as more information on how to use the dialog widget, visit
http://api.jqueryui.com/dialog/.
• show and hide. A dialog box usually appears on the screen when it’s opened
and disappears when it’s closed. But what fun is that? You can animate how
the dialog box opens and closes by setting the show and hide properties. These
properties can take many different values. If you set them to true, then the
dialog box will fade in and out quickly:
show: true,
hide: true
You can also provide a number, which is the number in milliseconds it takes to
either fade the dialog in or out. For example, say you wanted the dialog box to
fade in really quickly—say 250 milliseconds—but take 2 seconds to fade out.
You’d set those properties like this:
show: 250,
hide: 2000
You’re not limited to just the fade effect either. You can pass the name of any
jQuery effect (page 183) to these properties as a value. Just enclose the name
of the effect in quotes—'slideDown'—for example. To make a dialog box slide
in and out of view, use these settings:
show: 'slideDown',
hide: 'slideUp'
You can also use jQuery UI effects (page 438) like 'scale' or 'explode'. As if
that weren’t enough options, you can also pass another object literal specifying an effect name, a duration, a delay, and an easing value (page 442). For
example, say, when a dialog is closed you want it to wait 250 milliseconds and
then explode for 1 second, using an 'easeInQuad' easing function (please don’t
try this at home). You’d pass this line along with the properties object:
310
JAVASCRIPT & JQUERY: THE MISSING MANUAL
hide: { effect: 'explode',
'easeInQuad' }
delay: 250, duration: 1000, easing:
ADDING
MESSAGES
WITH DIALOG
BOXES
• position. Dialog boxes usually pop up right in the middle of the browser window. But they don’t have to. You can set the position of the dialog box using
the position property. Like show and hide, it can accept several different types
of values. For simple x,y coordinates pass an array (page 44) containing two
numbers. The first sets the left position of the dialog (the distance from the left
edge of the browser window to the left edge of the dialog box) in pixels; the
second is the top position in pixels. For example, say you wanted the dialog to
open 100 pixels from the left side of the screen and very close to the top of the
screen (say 10 pixels from the top). You’d set the position property like this:
position: [100,10]
You can also use keywords—center, left, top, right, bottom—to specify the
dialog’s position. For example, to place the dialog in the bottom-right corner
of the screen, set the position property like this:
position: 'right bottom'
The first keyword must be the horizontal setting—left, center, or right—and
the second keyword the vertical—top, center, or bottom. Separate the two
keywords with a space.
Finally, you can give the position property a jQuery UI position object. This
useful utility is discussed in the box on page 318.
Mini Tutorial: Passing Options to the Dialog Widget
You can combine any or all of the properties listed above when you call the dialog()
function. You can see how properties work by building upon the dialog box code
from the previous tutorial. Here you’ll make the dialog modal, so the visitor can’t
do anything until the dialog is dismissed; you’ll also prevent visitors from moving or
resizing the dialog; and, lastly, you’ll make it disappear in a flashy way:
1. In a text editor, return to the hello_world.html file you worked on in the
steps on page 306.
You’ll start by passing an empty object literal to the dialog function.
2. Click between the opening and closing parentheses in dialog(). Type {, press
Return twice, then type }. The code should now look like this:
$(document).ready(function() {
$('#hello').dialog({
});
}); // end ready
You can now plug in property and value pairs. First, you’ll make the dialog modal.
Chapter 9: Expanding Your Interface
311
ADDING
MESSAGES
WITH DIALOG
BOXES
3. Inside the object literal, type modal: true:
$(document).ready(function() {
$('#hello').dialog({
modal: true
});
}); // end ready
Save the file and open it in a web browser. The rest of the screen around the
dialog box is darkened by a transparent, striped background. You have to close
the dialog box to see the page clearly again.
4. In the line you just typed, add a comma after true. Hit Return and add the
lines in bold below:
$(document).ready(function() {
$('#hello').dialog({
modal: true,
resizable: false,
draggable: false
});
}); // end ready
Remember, you must separate name/value pairs with commas. Every line with
a name/value pair should end in a comma, except for the last name/value pair
in the object. These two new lines prevent a visitor from moving or resizing the
dialog. Finally, it’s time to close the dialog with a little flair.
5. Add a comma after false in that last line you typed; hit Return and type
hide: 'explode' like this:
$(document).ready(function() {
$('#hello').dialog({
modal: true,
resizable: false,
draggable: false,
hide: 'explode'
});
}); // end ready
This code makes jQuery UI apply its explode effect when the visitor closes the
dialog box. Save the page and preview it in a browser. Watch what happens when
you close the dialog. Have fun with some of the other jQuery UI effects—replace
'explode' above with one of these: 'bounce', 'blinds', or 'drop'.
You’ll find a completed version of this tutorial in the complete_dialog_properties.html file in the Chapter09 folder.
312
JAVASCRIPT & JQUERY: THE MISSING MANUAL
Opening Dialog Boxes with Events
jQuery UI dialog boxes are easy to use and are an excellent replacement for a
browser’s boring alert box. However, you probably won’t want to see a dialog box
every time you visit a web page. Dialog boxes are much more useful when they open
in response to a visitor’s interaction. For example, when a visitor clicks a “Sign up
for our e-mail newsletter” button, instead of whisking the visitor off to another web
page, the browser could open a dialog box with a sign-up form on it.
ADDING
MESSAGES
WITH DIALOG
BOXES
You can open dialog boxes in response to any of the events you learned about on
page 152—a mouse click, a key press, or window resizing (but that would be weird).
In addition, you can always open a dialog box with your own programming. For
example, maybe you created a timed quiz. If the time runs out before the visitor
finishes the quiz, you could open a dialog box that says “Time’s up!”
There are a couple of things you need to do to open a dialog box. First, you must
tell the dialog box to not open when it’s first created—normally it pops right up (as
in the previous tutorial). Second, you need a way to trigger the dialog box to open
later; most commonly, you’ll do this with an event handler (page 152).
To hide a dialog box immediately when it’s created, you need to pass the dialog()
function the property autoOpen with a value of false. For example, say you added
a
to a page with the ID login. To turn that div into a jQuery UI dialog box but
initially hide it, you’d add this JavaScript code:
$('#login').dialog({
autoOpen: false
});
When the page loads, jQuery UI turns the div into a dialog box object and hides it
on the page. To make it visible, you need to give the open argument to the dialog
function. For example, say you had a button that said “Login to our site,” and you
want a dialog box to open when a visitor clicks that link. Assume the link has the
ID of loginLink. You could select that link, add a click event handler, and give it a
function that will open the dialog, like this:
$('#loginLink').click(function(evt) {
evt.preventDefault();
$('#login').dialog('open');
}); // end click
The second line of code—evt.preventDefault();—is needed to prevent the browser
from following the link and loading a new web page (see page 165 for a description
of the preventDefault() method).
In addition, while a visitor can always close a dialog box by clicking the Close button in its upper-right corner, you can also close the dialog programmatically. For
example, if you include a dialog box with a form in it, you might want to close the
dialog when the visitor submits the form, instead of making him submit the form
and then close the dialog box himself.
Chapter 9: Expanding Your Interface
313
ADDING
MESSAGES
WITH DIALOG
BOXES
NOTE
You’ll see an example of opening and closing dialogs in the next tutorial
Now suppose that the dialog box discussed in this section—a
tag with an ID
login—has a form in it. You want to close the dialog when the visitor submits that
form. Here’s how you could do that:
$('#login form').submit(function() {
$('#login').dialog('close');
}); // end submit
To close a dialog, just select the
, call the dialog() function, and pass 'close'
as the argument. Easy peasy.
NOTE
The above web form example is just part of the solution, however. When the form is submitted, you
would need to do some other things as well. Because submitting a form exits the current web page and leads to
a page that handles the form submission, you would need to stop the form from submitting and instead handle
the whole submission with JavaScript alone using a technology called Ajax. You’ll learn about that in Chapter 13.
Adding Buttons to a Dialog Box
Dialog boxes are good for more than just popping up messages for your visitors.
They’re also handy for receiving visitor input. For example, say you’ve built a web
application that lets people create to-do lists (as you’ll do in Chapter 14). If someone
added a to-do list item but then wanted to remove it, he could click a button to delete
the list item. To make sure she doesn’t accidentally delete a to-do item, you could
pop up a dialog box that asks her to confirm her choice (Figure 9-5).
jQuery UI’s Dialog widget lets you add buttons to any dialog box. In addition, you can
then run different programs based on which button the visitor clicks. For example,
if the visitor clicks Delete, the to-do list item is removed from the list, but if he clicks
Cancel, the list item is left alone.
To add buttons, you give the dialog() function a buttons property whose value is
itself an object literal containing each button’s name and action. For example, say
you wanted to add Confirm and Cancel buttons to a dialog box. You could do that
like this:
$('#dialog').dialog({
buttons : {
"Confirm" : function() {
// code executed when "Confirm" button is clicked
},
"Cancel" : function() {
// code executed when "Cancel" button is clicked
}
} // end buttons
}); // end dialog
314
JAVASCRIPT & JQUERY: THE MISSING MANUAL
That’s a lot of code and a lot of { and } symbols. But keep in mind that each button
you add is just an item inside an object literal with a name and a function value. For
example, here’s the code for just the Confirm button:
ADDING
MESSAGES
WITH DIALOG
BOXES
"Confirm" : function() {
// programming when "Confirm" button is clicked
},
The first part of the object—the name—is what will appear as the text on the button.
In this example, it’s Confirm. The second part of the object is a function (page 138),
which contains the code you want to run when that button is clicked. This could
be anything you want, from removing an item from the web page to beginning a
JavaScript-based game. In most cases, you’ll also want to close the dialog box after
the button is clicked. To do that, you can use the 'close' argument. For example, to
close the confirm button after it’s clicked and its code executes, you’d add $(this).
dialog('close'); to the end of the anonymous function, like this:
"Confirm" : function() {
// programming when "Confirm" button is clicked
$(this).dialog('close');
},
Your read about $(this) on page 139. In the context of the dialog object, $(this)
refers to the
that is the dialog box. You can then use the dialog() function on
that div to close it. Time for some practice adding buttons to a dialog box.
Mini-Tutorial: Adding Buttons to a Dialog Box
In this tutorial, you’ll let a visitor delete a photo from the web page by clicking it. To
make sure the photo isn’t accidentally removed, you’ll add a dialog box that asks
the visitor to confirm the action:
1. In a text editor, open the dialog_buttons.html file.
In this example, you’ve already linked the jQuery UI CSS and JavaScript files to
the page, so you’ll start right in by adding a dialog box.
2. Locate the empty line, just below the HTML comment and type:
Next, you’ll turn this div into a dialog box.
3. Click the empty line after the $(document).ready() function, and type:
$('#confirm').dialog({
});
Chapter 9: Expanding Your Interface
315
ADDING
MESSAGES
WITH DIALOG
BOXES
This code turns the div into a dialog box. The { and } indicate an empty object
literal (page 136) which will hold the dialog box’s options. First, you’ll make
it a modal dialog box so visitors can’t do anything else until they dismiss this
dialog box.
FIGURE 9-5
Want to make a dialog
box interactive? Put a
button on it! You can
program a button to do
anything you’d like when
a visitor presses it. For
example, the Confirm
button pictured here will
make the photo of the
robot explode!
4. Inside the object literal, type modal: true:
$('#confirm').dialog({
modal: true
});
You also want to make sure the dialog box is hidden at first. It’ll only appear
when the visitor clicks on the photo of the robot.
5. Add a comma after true in that last line you typed, hit Return, and type the
code in bold below:
$('#confirm').dialog({
modal: true,
autoOpen: false
});
316
JAVASCRIPT & JQUERY: THE MISSING MANUAL
You need to separate name/value pairs with commas, so don’t forget to add
a comma after true. You’ll add buttons to the dialog in a moment, but first
you’ll add the code required to open the dialog box when a visitor clicks the
robot photo. The photo has an ID of robot, so you can easily select it and add
a click event to it.
ADDING
MESSAGES
WITH DIALOG
BOXES
6. After the dialog function add three new lines of code, so your program
looks like this:
$(document).ready(function() {
$('#confirm').dialog({
modal: true,
autoOpen: false
});
$('#robot').click(function() {
}); // end click
}); // end ready
This code selects the photo and adds an event handler to it (page 152). Now to
open the dialog box: you simply select the dialog div, call the dialog() function,
and pass it the value 'open'.
7. Add one line of code to the click() function:
$(document).ready(function() {
$('#confirm').dialog({
modal: true,
autoOpen: false
});
$('#robot').click(function() {
$('#confirm').dialog('open');
}); // end click
}); // end ready
Now the dialog opens when the robot image is clicked.
8. Save the file and preview it in a web browser. Click the robot picture to see
your newborn dialog box.
The dialog doesn’t have any buttons on it yet. In the next few steps, you’ll add
them bit by bit, so you can really see how they work.
Chapter 9: Expanding Your Interface
317
ADDING
MESSAGES
WITH DIALOG
BOXES
POWER USERS’ CLINIC
Precise Positioning with jQuery UI
The dialog and tooltip widgets let you control the placement
of their boxes using a position property. The position
property is an object (page 136) that defines where the box
will be placed in relation to another element on the page. The
way you write it is a little weird, but with a little experience it
will seem pretty straightforward. There are several options,
but the two most important are my and at.
For example, if you wanted to place the dialog box in the
bottom-right corner of the window, you’d write this:
$('#dialog').dialog({
position: {
my: 'right bottom',
at: 'right bottom'
}
}); // end dialog
The my property refers to the dialog box; the at property
refers to the window. So my defines which part of the dialog is
placed at which position (at) on the window. In this example,
it’s saying put my (the dialog’s) bottom-right corner at the
window’s bottom-right corner.
You use the CSS positioning syntax (same as that used in
the background-position property). The first keyword is the
horizontal position: left, right, or center. The second is
vertical: top, center, or bottom.
Dialog boxes are placed in relation to the window. A tooltip
(page 321), on the other hand, is placed in relation to the triggering element—that is, the element you mouse over to open
the tooltip. However you can add a third property—of—to
tell the dialog or tooltip to place itself in relation to another
element on the page. This is handy for a “tour of the interface”
type presentation, where you introduce a visitor to different
elements of your web page. For example, you could pop up a
dialog box near the Login box to show visitors where to log in.
The of property takes a selector (page 119) or a jQuery element.
So, say the login box had an ID of login and you wanted the
dialog box to display directly below it; you could write this code:
$('#dialog').dialog({
position: {
my: 'center top',
at: 'center bottom',
of: '#login'
}
}); // end dialog
You can even provide an offset value to further control the
placement of the dialog or tooltip. For example, if you wanted
to place the dialog box so it overlaps the login box by 10 pixels,
you could do this:
$('#dialog').dialog({
position: {
my: 'center top-10',
at: 'center bottom',
of: '#login'
}
}); // end dialog
You can add or subtract using either a number (for pixel values)
or a percentage (for example, my: 'center top+25%'.
Make sure you don’t add any spaces between the keyword
(top, for example), the operator (+ or -) and the value (25%,
for example), or the position object won’t work.
Visit http://api.jqueryui.com/position/ to learn more about
jQuery UI’s position utility.
9. Return to your text editor and the dialog_buttons.html file. In the dialog()
function, in the last line of options passed to the function, type a comma
after false, hit Return, and then add the bolded code below:
$(document).ready(function() {
$('#confirm').dialog({
318
JAVASCRIPT & JQUERY: THE MISSING MANUAL
ADDING
MESSAGES
WITH DIALOG
BOXES
modal: true,
autoOpen: false,
buttons: {
}
});
$('#robot').click(function() {
$('#confirm').dialog('open');
}); // end click
}); // end ready
This passes another option to the dialog box—buttons. Its value is another object literal, which is made up of button items. First, you’ll add a Confirm button.
10. In the buttons object, add the code in bold:
buttons : {
"Confirm" : function() {
}
}
The word Confirm will be the label on the first button. When a visitor clicks
that button, the anonymous function runs. Save the file and try it out in a web
browser: click the robot picture and you’ll see the dialog box with a Confirm
button. Unfortunately, it doesn’t do anything yet. Return to your text editor.
11. In the anonymous function for the Confirm button, add one line of code:
buttons : {
"Confirm" : function() {
$('#robot').effect('explode');
}
}
This code selects the robot image and then applies jQuery UI’s explode effect
to it, like the one you saw in action on page 312. (You’ll also read more about it
and other jQuery UI effects on page 438.)
Time for another button.
12. Type a comma after the closing } for the Confirm button, press Return, and
then type the code in bold:
buttons : {
"Confirm": function() {
$('#robot').effect('explode');
},
"Cancel": function() {
}
}
Chapter 9: Expanding Your Interface
319
ADDING
MESSAGES
WITH DIALOG
BOXES
If you preview the page now, you’ll see two buttons in the dialog box. The Cancel
button doesn’t do anything, and it shouldn’t because it’s meant to cancel other
actions. However, you’ll notice that clicking it doesn’t even close the dialog box.
It should at least do that.
13. Inside the anonymous function for the Cancel button, type $(this).
dialog('close');:
buttons : {
"Confirm": function() {
$('#robot').effect('explode');
},
"Cancel": function() {
$(this).dialog('close');
}
}
Because the buttons are created inside the dialog() function which is applied
to the dialog - tag—matches.
NOTE
jQuery UI’s tabbed panels are fully keyboard navigable. Visitors can press the right arrow key to open
the next panel to the right and the left arrow key to open the panel to the left.
328
JAVASCRIPT & JQUERY: THE MISSING MANUAL
ADDING
TABBED
PANELS
FIGURE 9-8
Tabbed panels are common on sites that need to
present a lot of information. E-commerce sites
use panels extensively
on product pages, so
potential buyers aren’t
overwhelmed by a sea of
data, but can still quickly
access the information
they want.
To turn this collection of HTML into tabbed panels, you simply select the container
and then call the tabs() function, like this:
$('#tabbedPanels').tabs();
This creates the basic tabbed panel you see in Figure 9-9.
Chapter 9: Expanding Your Interface
329
ADDING
TABBED
PANELS
FIGURE 9-9
Tabbed panels are really
easy with jQuery UI: just a
little HTML and a dash of
JavaScript. If you don’t like
the way the tabs or panels
look, you can change their
appearance with jQuery
UI’s ThemeRoller (page
385).
Tabbed Panel Options
As with other jQuery UI widgets, the Tabs widget provides many options for customizing how it works. To change the options for the tabbed panels, simply pass an
object literal to the tabs() function containing the name of the property and the
value you’d like to set it to. Here are some of the options:
• show and hide. These two properties control how the panels appear and disappear from the screen. They take the same values as the properties of the same
name in the Dialog widget. For example, to make a panel slide into view when
it opens and slide out of view when it’s closed, you’d pass these two properties
to the tabs() function:
show: 'slideDown',
hide: 'slideUp'
• active. Normally, when a page with tabbed panels loads, the first tab is selected
and the first panel is visible. But you might want the second or last panel to be
visible first. You can set which panel is visible by setting the active property:
active: 1
As with JavaScript arrays (page 44), you count the panels starting at 0—so
setting panel 1 to active actually opens the second panel. Instead of a number,
if you give this property a value of false—active: false—you hide all of the
panels. A panel will only open when a visitor clicks one of the tabs. Note that
this option only works if you also set the collapsible property to true.
• collapsible. Set the collapsible property to true if you want to let users
hide all panels. Normally, at least one panel is visible at all times, but with this
330
JAVASCRIPT & JQUERY: THE MISSING MANUAL
property set to true, if you click the tab of an already open panel, the panel
itself closes completely and all you see are the tabs. You could use this option
if space on the screen is really limited, but, in general, this is an unusual choice
and won’t be familiar to most visitors to your site. However, you must set this
property to true if you set the active property (above) to false—this hides all
panels when the page loads.
ADDING
TABBED
PANELS
• event. When you click on a tab, its associated panel opens. At least that’s how
it normally works. If you want to make a different event trigger a panel, set the
event property to the name of an event (page 148). For example, to make a
panel appear when a visitor mouses over a tab, you could do this:
event: 'mouseover'
Be careful with this option, however. People are used to certain conventions on
the Web, the most common being if you click something on a web page, something happens. If people have to double click on a tab (the dblclick event) to
open a panel, they may never figure out how to access your panel’s contents.
• heightStyle. The heightStyle property controls the height of each panel and
has three possible values: content, auto, and fill. The normal setting is content,
which makes each panel only as tall as the content inside it. If one panel has
many paragraphs of text, and another panel has only a single sentence, when
you switch between panels, the overall height of the panel widget changes.
If there’s a really big difference in the amount of content in your panels, your
visitors might find this visual “yo-yo” effect distracting.
The auto option sets the same height for every panel, based on the panel that
has the most content. This option prevents the panel group from changing
height, but it also means that a panel without much content will have a lot of
empty space at the bottom. Finally, the fill option makes the panel group fill
to match the available area of the panel’s parent element. This option usually
creates a lot of empty space in each panel and wastes valuable screen real
estate, so it’s best avoided.
Mini-Tutorial: Add Tabbed Panels
This tutorial will take you through the process of adding tabbed panels to a page.
The most difficult part is getting the HTML in place; the JavaScript code is simple:
1. In a text editor, open the tabs.html file.
The jQuery UI CSS and JavaScript files are already linked to this web page. As
an added bonus, you won’t have to type all the HTML required to create tabbed
panels. (The required HTML components are described on page 327.) However,
there are a few things missing from this example code. In particular, an ID for
the tabbed panel container and the links that point from the tabs to the panels.
Chapter 9: Expanding Your Interface
331
ADDING
TABBED
PANELS
2. In the page’s HTML, locate
Are you sure you want to destroy the robot?
, $(this) refers to the dialog box itself. So, in this case,
$(this).dialog('close'); is the same as $('#confirm').dialog('close');.
Save the page and preview it in a web browser. Click the robot image to open
the dialog box, then click the Cancel button—the dialog box closes! Click the
robot image again, and this time, click Confirm: the robot image explodes and
disappears. Unfortunately, the dialog box doesn’t close. That’s an easy fix.
14. Add $(this).dialog('close'); as the last line of the anonymous function for
the Confirm button. Your final code should look like this:
$(document).ready(function() {
$('#confirm').dialog({
modal: true,
autoOpen: false,
buttons : {
"Confirm" : function() {
$('#robot').effect('explode');
$(this).dialog('close');
},
"Cancel" : function() {
$(this).dialog('close');
}
}
});
$('#robot').click(function() {
$('#confirm').dialog('open');
}); // end click
}); // end ready
320
JAVASCRIPT & JQUERY: THE MISSING MANUAL
Save and preview the page in a browser. Your finished page (when the dialog
box is open) should look like Figure 9-5. Try both buttons and see what happens.
You’ll find a finished version of this tutorial in the complete_dialog_buttons.
html file in the chapter09 folder.
PROVIDING
INFORMATION
WITH TOOLTIPS
Providing Information with Tooltips
Sometimes you need to give your visitors a bit more information. For example, say
you have a line of social media icons which lead off to different sites like Twitter,
Facebook, Reddit, Instagram, and so on. Someone unfamiliar with any of those sites
won’t recognize the icons and won’t know where clicking them will lead. To help
them out, you could add tooltips that pop up when they mouse over an icon: “My
Facebook Page,” for example.
jQuery UI provides a simple way to add these types of tooltips to any page element
(Figure 9-6). You can even add more elaborate tooltips that include entire chunks of
HTML including text, images, and links. The following steps outline the most basic
way to add tooltips to a page:
1. Follow the steps on page 304 to attach the jQuery and jQuery UI files to
your page.
You won’t get very far without the needed CSS and JavaScript.
2. Add a title attribute to any element you wish to have a tooltip:
Some browsers already display a tooltip when you add a title attribute to an
element. However, as with a browser’s alert box, you can’t style a browser’s
tooltips. In addition, not all browsers show tooltips, so using jQuery UI gives
you maximum control and effectiveness.
3. Select the elements and apply the tooltip() function:
$(document).ready(function() {
$('[title]').tooltip();
}); // end ready
Here, you use a simple attribute selector (page 123) to find every element with
a title, and then apply the tooltip() function to it. And, yes, you’re done.
jQuery UI takes care of the rest and creates attractive pop-up tooltips for every
element with a title.
You can be more specific if you’d like. For example, if you don’t want all elements
with a title to have tooltips, you could add a class—like tooltip—to each tag
and then use a class selector to add tooltips to just those elements:
$('.tooltip').tooltip();
Chapter 9: Expanding Your Interface
321
PROVIDING
INFORMATION
WITH TOOLTIPS
Mini-Tutorial: Adding Tooltips Quickly
jQueryUI gives you the easiest way to add tooltips to elements on a web page (and
your visitors will thank you for it):
1. In a text editor, open the tooltips.html file.
The jQuery UI CSS and JavaScript files are already linked to this web page.
You can start right in by adding title attributes to HTML tags. These titles will
become the text of the tooltips.
2. Locate the paragraph 
and add I am a map! as
a title:
One more tag and you’re done with the HTML edits.
4. Locate the paragraph and add Click this button! as a title:
About Me
Assuming you have a photo of yourself on the site, you could display that photo in
a tooltip, when someone mouses over the link like this:
$('#me').tooltip({
content: '
'
});
The $('#me') selects the link, and .tooltip() adds a tooltip to that link. The content
property then defines what HTML should appear inside that tooltip—in this example,
an ![]()
tag.
Another approach to adding HTML to a tooltip is to add the HTML to your page, then
use the content property to suck it up into a tooltip. But how would that work? If
you add HTML to a page, it shows up in the web browser, and you want that HTML
to appear only in a tooltip. One way would be to use jQuery's hide() method to
hide the HTML from view, and then use the tooltip() function to grab that hidden
HTML and display it inside a tooltip.
But there's another, simpler way that many JavaScript programmers have started
using: you can create a "template" by putting HTML inside of
Because you'll use it to select the template, the ID is important—but it doesn't have
to be tooltipTemplate. Use any ID you'd like. Likewise, the type="text/template"
is optional, but many programmers who use this template technique put the type
attribute in to clarify the purpose of the script tags. It's also common practice to put
these templates at the bottom of the page before the closing tag.
Once the template is in place, you can select it, pull out its HTML, and hand that over
to the Tooltip widget like this:
$('#me').tooltip({
content: $('#tooltipTemplate').html();
});
As you read on page 128, jQuery's html() method can extract the HTML from a
selection. In this example, you're selecting the , add the following HTML:
-->
You’re using the technique described on page 324 to hide HTML inside of
The ID is important. jQuery UI uses it to associate the tab with the proper
panel. In addition, it’s useful for browsers without JavaScript, because that
Chapter 9: Expanding Your Interface
327
ADDING
TABBED
PANELS
named anchor acts as a way to navigate from the link in the unordered list to
the associated div on the page. Inside the panel element, you can put any HTML
you’d like—images, text, lists, videos, and so on. The panel’s HTML will only be
displayed when its tab is clicked.
Here’s the basic HTML structure for a complete tabbed panel:
The names you use for the ID are up to you. You don’t need to use tabbedPanel for
the container element ID, and you can name the panels whatever you want instead
of #details, #reviews, and #order. Just remember that whatever ID you do choose
for a panel, the link in the associated tab—the
Some browsers already display a tooltip when you add a title attribute to an
element. However, as with a browser’s alert box, you can’t style a browser’s
tooltips. In addition, not all browsers show tooltips, so using jQuery UI gives
you maximum control and effectiveness.
3. Select the elements and apply the tooltip() function:
$(document).ready(function() {
$('[title]').tooltip();
}); // end ready
Here, you use a simple attribute selector (page 123) to find every element with
a title, and then apply the tooltip() function to it. And, yes, you’re done.
jQuery UI takes care of the rest and creates attractive pop-up tooltips for every
element with a title.
You can be more specific if you’d like. For example, if you don’t want all elements
with a title to have tooltips, you could add a class—like tooltip—to each tag
and then use a class selector to add tooltips to just those elements:
$('.tooltip').tooltip();
Chapter 9: Expanding Your Interface
321
PROVIDING
INFORMATION
WITH TOOLTIPS
Mini-Tutorial: Adding Tooltips Quickly
jQueryUI gives you the easiest way to add tooltips to elements on a web page (and
your visitors will thank you for it):
1. In a text editor, open the tooltips.html file.
The jQuery UI CSS and JavaScript files are already linked to this web page.
You can start right in by adding title attributes to HTML tags. These titles will
become the text of the tooltips.
2. Locate the paragraph A paragraph
and add Yes, I am a paragraph. as a title:A paragraph
You can add a title to any element in the body of a web page. (You can also get more creative with these titles if you wish.) 3. Locate the image tag and add I am a map! as
a title:
One more tag and you’re done with the HTML edits.
4. Locate the paragraph and add Click this button! as a title:
About Me
Assuming you have a photo of yourself on the site, you could display that photo in
a tooltip, when someone mouses over the link like this:
$('#me').tooltip({
content: ''
});
The $('#me') selects the link, and .tooltip() adds a tooltip to that link. The content
property then defines what HTML should appear inside that tooltip—in this example,
an Tabbed Panels
. In the tag following that headline, add id="tabContainer":
Tabbed Panels
jQuery UI tabs are applied to an element that contains the tabs and panels—usually a
tag. By adding an ID, you’ve got a way to select that
using
jQuery and apply the tabs() function. Now let’s add links.
3. Locate the unordered list (
- ) tag just below the opening
- Tab 1
- Tab 2
- Tab 3 These are named anchor links—links that point to other sections of the page that are identified with the matching ID. In other words, the first
- tag will
link to the for the first panel, the second
- tag to the second panel, and so on. In order to make these links work, you need to add the matching IDs to the panel divs. 4. Locate the
below the- tag you just edited (an HTML comment above the
makes it easier to identify. Add id="panel1" to the div, like this:You need to do this for the other panels as well. 5. Repeat step 4 for the last two panel divs (they are identified with HTML comments as well). Make sure you give each div an ID that matches the link from step 3. For example, the second panel’s div should be. Now let’s turn them into tabbed panels. 6. Inside the $(document).ready() function select the container and call the tabs() function: $(document).ready(function() { $('#tabContainer').tabs(); }); // end ready Save the file and preview it in a web browser. The page should look like Figure 9-10. If it doesn’t, check your browser’s console (page 18) and see if there are any JavaScript errors. If you don’t see any, check whether you typed the correct ID names for the container div and panels. Next, you’ll add some effects to the panel transitions by making them fade into view when they open and fade out when they close. 332 JAVASCRIPT & JQUERY: THE MISSING MANUAL 7. Add the following object literal (in bold) to the tabs() function: ADDING TABBED PANELS document).ready(function() { $('#tabContainer').tabs({ show: 'fadeIn', hide: 'fadeOut' }); }); // end ready This applies an effect to the panel transitions. You can try other effects like 'slideDown' and 'slideUp'. Save the page and preview it in a web browser. The tabbed panels work well, but there’s one problem with tabbed panels: the page always opens to either the first tab or one you specify using the active property (page 330). But what if you wanted to e-mail a link to the page and have a particular tab open from that link? For example, imagine you’re in customer service and a customer asks about the technical specs for a product your company sells. There’s a page for that product with the technical specs in a tabbed panel; the problem is that the “About this Product” panel appears whenever that page loads. What if you could just email a link like http://mycompany.com/productA. html#specs, and the tab with the technical specs opens when that link is followed. Well, you can, if you add a little JavaScript magic. The secret is pulling out that #specs from the URL and using it to trigger the panel. 8. After the tabs() function, add a new line and type var hash = location.hash;. The browser window provides what’s called a location object. This object holds lots of information about the URL of the current page, including the hostname (location.hostname), the entire URL (location.href), and other properties (visit https://developer.mozilla.org/en-US/docs/Web/API/Location for a complete list). The location.hash property returns just the part of the URL that includes the # part. For example, say you visited http://mycompany.com/productA.html#specs. The location.hash property for this URL is #specs. You’ll use the hash property to load a panel with a matching hash value. 9. After the code you just added, add a conditional statement, so your final code looks like this: $(document).ready(function() { $('#tabContainer').tabs({ show: 'fadeIn', hide: 'fadeOut' }); var hash = location.hash; if (hash) { $('#tabContainer').tabs('load', hash) } }); // end ready Chapter 9: Expanding Your Interface 333 ADDING TABBED PANELS This code first checks to see if a hash value exists—for example, if the visitor simply just visits the tabs.html page, there isn’t any hash value, so you can skip the rest of the code and just let the first panel load normally. However, if there is a hash value like #panel1, then the next bit of code runs. It simply selects the container again ($('#tabContainer')), calls the tabs() function, and passes two arguments. The first, load, is a command built into the jQuery UI program that tells the tabs function to load a panel. The second argument—hash—is the panel that should be loaded, either #panel1, #panel2, or #panel3 in this example. 10. Save the page and preview it in a web browser. The first panel should open. In the location bar, add #panel3 at the end of the URL (after the tabs.html). Then reload the page. The third panel should display. (If it doesn’t, try copying the URL in the location bar, opening a new tab or browser window and pasting it in.) A finished version of the file—complete_tabs.html—can be found in the chapter09 folder. FIGURE 9-10 The final web page showing the three tabbed panels. 334 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADDING TABBED PANELS POWER USERS’ CLINIC jQuery UI’s Custom Events You learned about browser events like click, mouseover, focus, and resize on pages 148-152. These events are built into browsers and triggered when visitors take certain actions on a page, like click a link or submit a form. Events are useful because they let you write programs that respond to things that are happening on the page. $('#tabContainer').tabs({ beforeActivate: function(evt) { location.hash=$(evt.currentTarget). attr('href'); } }); jQuery UI widgets are programmed with their own custom events—they’re not exactly like the kinds of browser events you’re used to, however. Widget events are simply moments during the creation, execution, or completion of a widget component. There’s a lot going on here, but in a nutshell, you find the href attribute of the tab the visitor clicked (#panel, #panel2, or #panel3) and store it to the location’s hash property (see step 8 on page 333 for more on the hash property). You can find a working copy of this code in a file named complete_tabs_with_custom_event.html in the chapter09 folder. For example, the tabs widget provides a beforeActivate event that lets you run some code right before jQuery UI makes a hidden panel visible. This would come in handy if you wanted to trigger some other action each time a tab is clicked. For example, you could use the beforeActivate custom event to update the URL in the browser’s location bar each time a tab is clicked, so the URL would add the # of the proper panel to the filename—tabs.html#panel3, for instance. Used in conjunction with a conditional statement like the one added in step 9 on page 333, you can provide a way for users to bookmark a custom URL that would display the proper panel each time that bookmark was loaded. To do that, you’d add the beforeActivate property to the tabs() function with a function as a value, like this: Like the tabs widget, each jQuery UI widget gives you lots of ways to do things as the widget is being created, modified, or destroyed. Programmers call these hooks because they let you attach your own programming to the programming already existing in jQuery UI. This is a complex topic, but fun to explore. The best way to learn about these custom events is to visit the API page for each widget (API stands for application programming interface and represents all the properties and functions that you can access as a programmer). At the top of each page there’s a QuickNav box that lists all the custom events the widget supports. For example, the dialog widget’s API page ( http://api.jqueryui.com/dialog/ ) lists 11 different events you can hook into! Tabs with Remote Panel Content jQuery UI even lets you pull in content for tabbed panels from other web pages. In other words, instead of creating an unordered list of links which link to divs within the page, you can create an unordered list of links that point to other pages (or to content that’s generated by a web server). You might want to take this approach if the content in each tab is constantly changing (stock prices, reviews, forum posts). By linking to dynamically created content—for example, information drawn from a frequently updated database using a technology like PHP, .NET, or Ruby On Rails— you can be assured that the content inside the panel is up-to-date. To load panel content from other pages or web server requests, simply create a containing div, an unordered list with links to other pages, and call the tabs() function. For example, say you wanted each panel to include content from a separate Chapter 9: Expanding Your Interface 335 ADDING TABBED PANELS web page. Those pages are named panel1.html, panel2.html, and panel3.html. You’d add this HTML to your page: If you’re linking to dynamic data, you might not be pointing to a web page, but to content generated by a server-side language like PHP: When linking to external web pages, you don’t need to include the panel divs as in step 3 on page 332. jQuery UI will automatically create those divs when the tabbed panels are created. To create the tabbed panels, simply select the container div and call the tabs() function: $('#tabContainer').tabs(); When this code runs, jQuery UI will fetch the HTML from the web page that’s linked to the first visible panel. For example, given the code on above, when the page loads, jQuery UI will load the HTML from the panel1.html file and display it in a panel below the tabs. When someone clicks the second tab, jQuery UI will request the HTML from the second link and create a new panel to place that HTML into. In most cases, you can even link to an external website like Google, Wikipedia, or a server other than the one the tabbed panel page comes from. However, sites can block this process, and then content like web fonts, images, and videos won’t load. There’s another problem with this approach: all of the content of the linked to the page will appear in the panel. So if you link to a complete HTML file with a, tag, and links to CSS and JavaScript files, all of that will be loaded as well. You end up with a page within a page. If all you want is a chunk of HTML content in a panel, there are two solutions. The easiest way is to create page fragments—HTML files that contain only the HTML you wish to appear in the panel. You can easily make a fragment if you’re loading data dynamically from the server—your server-side script only needs to spit out the content that should appear in the panel (and not all the other stuff like the <head> tag required by a full web page). 336 JAVASCRIPT & JQUERY: THE MISSING MANUAL Alternatively, you can let the panel load a full web page and extract only the content you want to appear in the panel using a custom event (see the box on page 335). Here’s how it works: jQuery UI tabbed panels include an event called load. This event lets you run a function immediately after jQuery UI loads content from a remote source. You can use jQuery to find just the content you want, extract it, and place it inside the panel. This method is a little complex, but it doesn’t require a lot of code. ADDING TABBED PANELS First, you need to make sure there’s a way to select specific content from the remote page. An easy way to do this is to wrap the content you want in the panel in a <div> tag with an ID—<div id="panelContent">, for example. With that in place, you now have a way to select just that content and not unnecessary HTML like the <head> or <title> tags. Then, you need to pass a load option to the tabs() function. The load option is the custom event, and you supply an anonymous function (page 138) that tells jQuery UI what to do when it’s received content from the remote page and placed it into a panel. When the load event is triggered, jQuery UI has already created a new tab and inserted the HTML from the remote page into it. At this point, the new panel has all the extra HTML you don’t want. However, you can use jQuery to quickly remove that new HTML and replace it with the stripped-down HTML. It happens so fast, this quick change of content isn’t even displayed in the browser. Here’s an example: $('#tabContainer').tabs({ load: function(evt,ui) { var newHTML = ui.panel.find('#panelContent').html(); ui.panel.html(newHTML); } }) Lines 2-5 are the load option. jQuery UI provides two pieces of information to its custom events (those are evt and ui in line 2). The first, evt, is a regular jQuery event object (page 164). You can use any of the event properties and methods discussed on pages 165-167. In this case, you’re interested in the second argument passed to the load event’s anonymous function: ui. The ui object represents the currently updated user interface element. For tabbed panels, there’s a ui.panel object and ui.tab object. The ui.panel object represents the newly created panel (the <div> that jQuery UI creates when it loads the external web page). In line 3, you create a new variable—newHTML—to hold the final panel content (without the extra HTML like <head>). When jQuery UI creates the new panel, it loads the entire HTML content from the requested page, so you can look inside that panel and get just the HTML you’re after. The ui.panel.find('#panelContent') part gets the new panel HTML and looks inside it for an element with the ID of panelContent (jQuery’s find() method is described on page 531). Then, the html() method (page 119) kicks in and extracts the HTML from just that one part of the page. In other words, you’ve just collected the small amount of HTML you’re interested in and stored it into a variable named newHTML. Chapter 9: Expanding Your Interface 337 SAVING SPACE WITH ACCORDIONS NOTE You can find an example of using separate web pages for panel content in the remote_tabs.html file located in the chapter09 folder. The file also uses the load custom event to strip out unwanted HTML. In line 4, you simply replace the HTML in the panel (that’s the old HTML, complete with <head>, <title>, and other unwanted tags) with the new HTML (only the HTML you need for the new panel). This code runs so quickly that the browser never even displays the full web page inside the panel—the visitor will only see the lean, stripped-down HTML you’re after. Saving Space with Accordions jQuery UI accordions, like tabbed panels, are another space-saving user interface device. See the bottom image in Figure 9-11 for an example. But instead of being controlled by a line of tabs along the top, each accordion panel has a clickable headline used to hide and close the accordion panel. The accordion headlines open the panel directly below it and close any currently opened panel. In other words, only one accordion panel is opened at a time. In general, accordions work much the same way as tabs. Most of the options are the same and work the same way as tabs, but the HTML structure is very different. With accordions, you need just three components: • Enclosing <div> that holds the accordion. You need to select the div with jQuery, so add an ID or class to the div so you can select it and apply the Accordion widget to it. • Headline containing text. This headline is the clickable control that opens and closes accordion panels (for example, the blue headline “What does the robot say” in Figure 9-11). It doesn’t matter which level of headline you use—<h2>, <h3>, and so on. Just use the same one for each accordion group. (Technically you don’t even have to use a headline tag—any block level tag works—but headlines are the most commonly used.) • Block-level element immediately following the headline. Usually this is a <div> tag filled with the content you wish to show and hide. This div must go directly after the headline. 338 JAVASCRIPT & JQUERY: THE MISSING MANUAL SAVING SPACE WITH ACCORDIONS FIGURE 9-11 Now you see it, now you don’t. jQuery UI can transform a simple collection of headlines and <div> tags (top) into an interactive presentation of collapsible panels (bottom). Chapter 9: Expanding Your Interface 339 SAVING SPACE WITH ACCORDIONS The headline and following div element represent one part of an accordion. To add more accordion elements, add more headline/div pairs. For example, the basic HTML structure of a three-panel accordion looks like this: <div id="accordion"> <h3>Trigger for first accordion panel</h3> <div> <!-- content for first accordion --> </div> <h3>Trigger for second accordion panel</h3> <div> <!-- content for second accordion --> </div> <h3>Trigger for third accordion panel</h3> <div> <!-- content for third accordion --> </div> </div> Once you’ve set up your HTML, attached the jQuery UI CSS, and the jQuery and jQuery UI JavaScript files (page 104), turning on the accordion widget is as simple as selecting the containing element and calling the accordion() function, like this: $('#accordion').accordion(); As usual, jQuery UI takes care of all the heavy lifting and transforms your basic HTML structure into an accordion like the one pictured in Figure 9-11. As with tabbed panels, the jQuery UI accordion can accept an object with a variety of options (many of which work the same way as tabbed panels): • active. The active option works just like the same option for tabbed panels (page 330). Provide a number, and that accordion panel will open when the page loads. For example, to open the second accordion panel, you’d supply this: active: 1 Like arrays, you count from 0 when counting accordion panels. If you supply the value of false for this option, and set the collapsible property to true, you can load the page with all accordion panels closed. • collapsible. Set this option to true, and the active option to false and all accordion panels will be closed when the page loads. In addition, if you set this option to true, then accordion headlines work like a toggle switch: click the headline, and if the panel below it is open, then that panel closes. If the panel is closed when you click the headline, the accordion panel opens. • animate. Normally, accordion panels slide open and slide shut. You can turn this behavior off and make the panels just blink open and close instantly by setting this option to false: animate: false 340 JAVASCRIPT & JQUERY: THE MISSING MANUAL You can also supply a few other values for different behaviors. If you supply a number, then you’re telling jQuery UI how long the animation should take to complete (in milliseconds). For example, to really bug your site’s visitors, you could force accordion panels to open and close painfully slowly over the course of 5 seconds, like this: SAVING SPACE WITH ACCORDIONS animate: 5000 You can also supply a string that matches the name of an easing function. As discussed on page 442, easing functions control how an animation plays out over its overall duration: you can make an animation start off very slowly, then finish really quickly. For example, to use the easeInElastic easing function, you’d set the animate property like this: animate: 'easeInElastic' However, anything but the default easing looks pretty awful. • event. Set the event that causes an accordion panel to open. Works just like the tabbed panels event option described on page 331. • heightStyle. Just like the tabbed panels option of the same name (page 331). • icons. As you can see in Figure 9-11, jQuery UI attaches small icons on the left side of accordion headers. A small down arrow appears in headlines whose accordion panel is open; a right-pointing arrow appears in headlines whose panels are closed. jQuery UI includes a large selection of icons as part of each theme (see http://api.jqueryui.com/theming/icons/ for a complete list). You can swap in new icons by supplying an icons option and a value that includes an object literal, like this: icons : { header: "ui-icon-plus", activeHeader: "ui-icon-minus" } The object literal defines the two icons jQuery UI should use. The header property sets the icon used in headers whose accordion panels are closed, and the activeHeader property defines the icon used for headers of opened panels. The above example uses + and – symbols to indicate the different header states. As with the other jQuery UI plug-ins, you can combine multiple options to the accordion widget to control how the accordion looks and functions. For example, say you wanted to change the event trigger so mousing over a headline opens an accordion panel, and you want to change the icons used in the headlines. You could do that when you call the accordion() function, like this: Chapter 9: Expanding Your Interface 341 SAVING SPACE WITH ACCORDIONS $('#accordion').accordion({ event: 'mouseover', icons : { header: 'ui-icon-circle-plus', activeHeader: 'ui-icon-circle-minus' } }); Mini-Tutorial: Create a jQuery UI Accordion Accordions are very much like tabbed panels. Most of the work required is formatting the HTML. But the HTML for accordions is even simpler than for tabbed panels. In this tutorial, you get to start with an already created HTML file and add an accordion to it: 1. First take a look at the HTML to see what’s there. In a web browser, open the accordion.html file. The page contains a headline—jQuery UI Accordion—and a simple collection of headlines, text, and images (see the top image in Figure 9-11). 2. Open the accordion.html page in a text editor and look at the HTML starting below the <h1> tag. Notice that there’s a <div> tag—that’s a container element that holds the items for the accordion. Inside that div you’ll see an <h3> tag followed by a <div> tag. The <h3> represents the accordion label and the <div>, the accordion panel. In the HTML for this page, there are three of these <h3>/<div> pairs, so once you add the programming, you’ll have three accordion panels. First, you need to give jQuery a “hook” for selecting the accordion container. 3. Locate the <div> tag below the <h1> tag and add an ID: <div id="accordion"> This is all the HTML you need to add accordions to the page. Now it’s time to add the programming. 4. Inside the $(document).ready() function, select the container and call the accordion() function: $(document).ready(function() { $('#accordion).accordion(); }); // end ready Save the file and preview it in a web browser. The page should look like the bottom image in Figure 9-11. See why it’s called a “mini” tutorial? jQuery UI makes it that simple. But you’re not done yet. You want to make it so that all of the accordion panels are closed when the page loads. 5. Add the following object literal (in bold) to the tabs function: $(document).ready(function() { $('#accordion').accordion({ 342 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADDING MENUS TO A PAGE active: false, collapsible: true }); }); // end ready Preview the page in a browser, and you’ll see that all of the accordion panels begin in the closed position. Click one of the headers to open a panel; click that same header again to close the panel. Accordion panels only close when their associated headline is clicked if the collapsible option is set to true. Let’s choose some different icons from jQuery UI’s large selection of icon elements (http://api.jqueryui.com/theming/icons/). 6. Add an icons property to the accordion options object. The value of this option will be another object literal with two properties: $('#accordion').accordion({ active: false, collapsible: true, icons : { header: 'ui-icon-circle-plus', activeHeader: 'ui-icon-circle-minus' } }); Don’t forget to add a comma after true on line 3. As you can see, JavaScript lets you nest object literals inside of other object literals. Sometimes this kind of code can get a little hard to read, but keep in mind that you can just treat an object literal like any other object—a variable, number or string, for example— and use it as a single value for a variable or object property. 7. Save the page and preview it in a web browser. The page should look like the bottom image in Figure 9-11. If it doesn’t, doublecheck your code against what’s printed in step 4 above. A finished version of the tutorial—complete_accordion.html—is located in the chapter09 folder. Adding Menus to a Page jQuery UI also includes a Selectmenu widget that makes it very easy to convert an unordered, nested list of links into a menu with fly-out submenus. It’s intended to present a vertical menu bar, with menu items listed on top of each other, and submenus appearing to the right (Figure 9-12). However, if you’ll settle for a single set of submenus, it’s possible to coax the Selectmenu widget to a horizontal orientation for the menu’s top level. As with all of the jQuery UI widgets, menus are really simple to use. The hardest part is structuring your HTML, and even that isn’t hard. In fact, you’ve already seen the same structure in the SmartMenus plug-in on page 241. You start with a simple Chapter 9: Expanding Your Interface 343 ADDING MENUS TO A PAGE unordered list of links—these are your top-level menu buttons, the ones that you see when the page loads. If you want to add a pop-out menu to one of those buttons, simply nest another unordered list inside the top-level button’s <li> tag. For example, here’s the HTML for a menu with three top-level menus and a submenu that appears when you mouse over the last menu item: <ul id="mainMenu"> <li><a href="about.html">About Us</a></li> <li><a href="contact.html">Contact Us</a></li> <li><a href="products.html">Products</a> <ul> <li><a href="a.html">Product A</a></li> <li><a href="b.html">Product B</a></li> <li><a href="c.html">Product C</a></li> </ul> </li> </ul> When this HTML is converted into a menu, visitors can mouse over the Products menu item, and a submenu with the three product options will pop into view. As with other jQuery UI widgets, it’s good to provide an ID to the widget’s containing element. In this case, it’s the first <ul> tag because that’s the container for all of the menu items and submenus. TIP If you want to visually organize the options in your menus, you can add a divider to separate submenu buttons. Just insert a <li> tag with no link and a dash in it like this: <li>-</li> jQuery UI will draw a line (instead of adding a button) to the menu. Using the menu widget is easy: 1. Attach the jQuery UI CSS file, jQuery JavaScript file, and the jQuery UI JavaScript file. These are the same basic steps for using any jQuery UI widget as described on page 104. 2. Insert an unordered list of links, with additional unordered lists for submenus as described above. It’s a good idea to make sure your top-level menu items link to pages on your site. 3. Add CSS to limit the size of the menu buttons and submenus. The out-of-the-box CSS for jQuery UI menus doesn’t limit the width of the menu buttons, so you can end up with extraordinarily wide buttons on your main navigation menu. To set a size for the main menu buttons, create a .ui-menu style with a width property, like this: 344 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADDING MENUS TO A PAGE .ui-menu { width: 10em; } The ui-menu class is applied automatically by jQuery UI when it creates a menu widget. That class is applied to each <ul> tag within the menu—the main menu and any submenus. You can use any measure you’d like—em, px, %—but be careful using percentage. A submenu takes its percentage value from its parent, so each submenu will get progressively thinner. To get around this, set the submenu (which is actually an <ul> inside an <ul>) to a 100% width (to match the parent menu). For example: .ui-menu { width: 25%; } .ui-menu .ui-menu { width: 100%; } Add this CSS to your site’s custom CSS file—not to the jQuery UI CSS file. If you decide to change the theme, or update jQuery UI to a newer version, any changes you make to the jQuery UI CSS file will be wiped out by the update. You’ll learn more about styling jQuery UI widgets in Chapter 11. FIGURE 9-12 jQuery UI’s menu widget makes it easy to create a multi-level menu that matches the look and feel of the other jQuery UI widgets. It’s great for adding a menu to a web application to make the application feel more like desktop software. Chapter 9: Expanding Your Interface 345 ADDING MENUS TO A PAGE 4. Select the outer <ul> tag and apply the menu() function: $('#mainMenu').menu(); NOTE You’ll find an example of the menu widget in the complete_menu.html file in the chapter09 folder. As with other jQuery UI widgets, the menu widget includes several options for customizing its behavior and appearance. Pass an object literal to the menu() function to control it: • icons. As you can see in Figure 9-12, jQuery UI attaches small icons on the right side of any menu button that has an attached submenu. The icon indicates to visitors that there’s another menu hidden away in that button. jQuery UI includes a large selection of icons as part of each theme (see http://api.jqueryui.com/ theming/icons/ for a complete list). You can swap in new icons by supplying an icons option and a value that includes an object literal, like this: icons : { submenu: "ui-icon-circle-triangle-e" } Unfortunately, you can only specify one icon, so the icon used for buttons on the main menu bar is also shared by submenus buttons that have their own submenus. • position. The position option controls where submenus are placed in relation to their parent. Normally submenus are placed directly to the right of their parent button, but you can change this using the jQuery UI position object discussed on page 318. For example, if you want to place the submenu directly below the button that opens it, you could set the option like this: position : { my: "center top", at: "center bottom" } This translates to place “my” (the submenu) center and top, and “at” center and bottom of my parent menu button. This technique is useful for creating drop-down menus in a horizontal navigation bar as described on page 349. Creating a Horizontal Navigation Bar The jQuery UI menus weren’t intended to create a classical navigation bar like the ones you see at the top of most websites. If that’s what you’re after, the SmartMenus plug-in discussed on page 241 is probably a better bet. However, you can coax the menu widget into a horizontal menu with a single drop-down menu with a little CSS like the one shown in the top image in Figure 9-13. 346 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADDING MENUS TO A PAGE FIGURE 9-13 If you want to keep your site’s user interface looking consistent by using jQuery UI’s CSS and widgets throughout your site, you can get a fully functional horizontal jQuery UI menu if you’re willing to settle for only one level of drop-down menus (top). jQuery UI’s Selectmenu widget doesn’t work very well if you’re interested in a multilevel horizontal menu (bot-tom). Because all submenus are placed in the same relationship to their parent, you end up with overlapping submenus. You can see examples of both types of menus in the chapter09 folder: complete_ horiz_menus.html and bad_horiz_menu_multilevel.html. Multi-level drop-down menus don’t work well because the jQuery UI menu widget places all submenus in the same position relative to their parents. With a vertical menu (Figure 9-12), that works well: the submenus pop out to the right of their parent menu button. But with a horizontal menu bar, the first submenu usually appears below its parent button (Figure 9-13, top) and sub-submenus appear to the right of their parent. Unfortunately, with jQuery UI, if you place one submenu below its parent all submenus are placed that way, so you end up with a confusing overlapping mess of submenus, as pictured in the bottom image in Figure 9-13: Chapter 9: Expanding Your Interface 347 ADDING MENUS TO A PAGE 1. To create a horizontal menu, start with an unordered list of links, but add only one level of nested unordered lists (the HTML example on page 344, for instance). Next, you need to add some CSS to make the main nav buttons sit horizontally. You should put this CSS in the main style sheet for your site and not in the jQuery UI CSS file. 2. Add CSS to float the top-level menu buttons so they appear side by side in a horizontal bar: #mainMenu > li { width: 10em; float: left; } This CSS selector—#mainMenu > li—selects all <li> tags that are a direct descendant of an element with the ID of mainMenu. (This assumes that you gave the containing <ul> tag that ID name as in the example code on page 344. If you use a different ID for that tag, then use that instead.) The > part is a child selector and only selects <li> tags that are directly children of the main <ul> tags, so all the <li> tags in submenus ignore this rule. The style sets each menu button to a set width, and then floats them side by side. Then you need to set the width of the submenus. 3. Add another CSS style: .ui-menu .ui-menu { width: 10em; } This style sets the width of the submenus. jQuery UI gives each menu—<ul> tag—the class of .ui-menu, so this selector—.ui-menu .ui-menu—selects only those <ul> tags that are inside another <ul> tag. In other words, the style only applies to nested menus and sets the width of those submenus. 4. Finally, add one last style to fix a problem with the main menu: #mainMenu { float: left; } This style fixes what’s called an escaping float—a situation where a parent element’s height collapses when its child elements are floated. In plain English, it just means that the border and background of the main menu don’t look right when all the buttons are floated. This is one technique for fixing the problem; just float the parent element. With the CSS out of the way, you can add the JavaScript. 348 JAVASCRIPT & JQUERY: THE MISSING MANUAL 5. Call the menu() function as described on page 346, but add a few options to control the placement of the submenu and icon used on the main menu: ADDING MENUS TO A PAGE $('#menu').menu({ position: { my: 'center top', at: 'center bottom' }, icons: { submenu: 'ui-icon-triangle-1-s' } }); The position option (described on page 346) controls the placement of the submenu. In this case, it puts the menu directly below the menu button that opens it. In addition, the menu widget normally shows a right-pointing arrow icon on menu buttons that have submenus. However, because the menu bar is now horizontal, and the submenu opens up below the main menu bar, you must use a down-pointing arrow ('ui-icon-triangle-1-s'). Chapter 9: Expanding Your Interface 349 CHAPTER Forms Revisited 10 F orms are the original interactive web element, and they’re a part of most web applications in one form or another. Forms can get input from visitors, let shoppers buy goods, let community members post their thoughts, and so on. Chapter 8 looked at ways to make web forms smarter and easier to use. jQuery UI lets you do even more with your forms and provides a consistent design to make your form elements look and function in similar ways. This chapter will show you how to use four jQuery UI widgets—Datepicker, Autocomplete, Selectmenu, and Button—that can really make your forms look great and work well. Picking Dates with Style Many forms require date input. Forms for adding an event to a calendar, booking a plane flight, and making a dinner reservation all require you to specify a date for an activity. Many forms provide instructions, like “Type a date, like 12/10/2014,” but simply asking visitors to type a date into a field can generate a wide variety of results. First of all, you’re relying on your visitors never to make typos. In addition, because people often write dates in different ways (in the United States, for example, dates are specified in the order month, day, year, but many other places the order is day, month, year), hand-typed dates may be misleading or inaccurate. Fortunately, jQuery UI’s Datepicker widget makes selecting a date straightforward. Instead of typing a date, visitors just click a form field, and then use a visual calendar to pick the desired date (Figure 10-1). This widget is simple to use and customize. 351 PICKING DATES WITH STYLE FIGURE 10-1 jQuery UI’s Datepicker widget provides a simple method to accurately specify dates in a web form. As with most jQuery UI widgets, Datepicker is extremely easy to use: 1. Follow the steps on page 304 to attach jQuery UI’s CSS and JavaScript files to your web page. You’ll need to attach the jQuery file as well, so that whenever you use a jQuery UI widget, you’ll have the jQuery UI CSS, jQuery JavaScript, and jQuery UI JavaScript files attached to your page (in that order, too). 2. Add a form to a page, and include a text <input> field for capturing a date. Provide a way to identify that input field, so you can select it with jQuery. For example, you might give it an ID like this: <input type="text" name="birthdate" id="birthdate"> Or, if the form has several fields for capturing dates (like fields for arrival and departure) you might use a class name to identify all fields that should use the datepicker widget like this: <input type="text" name="arrival" class="date"> <input type="text" name="departure" class="date"> 3. Add jQuery’s $(document).ready() function to your page: $(document).ready(function() { }); // end ready 352 JAVASCRIPT & JQUERY: THE MISSING MANUAL 4. Use jQuery to select the input element(s) and call the datepicker() function: PICKING DATES WITH STYLE $(document).ready(function() { $('#birthdate').datepicker(); }); // end ready Or, if you’ve used a class to identify more than one input like in the example in step 2, you could write this: $(document).ready(function() { $('.date').datepicker(); }); // end ready These are the only steps you need to create a date picker like the one you can see in Figure 10-1. And if that’s all the Datepicker widget did, it’d be good enough. But the Datepicker widget provides many different options for customizing its display and how it works. NOTE HTML5 includes a special date field that’s intended to provide some of the functionality that Datepicker provides, but without any JavaScript. However, it’s not supported that well on all browsers, and doesn’t provide any way to customize the look of the pop-up calendar. In addition, jQuery UI’s Datepicker provides many additional features that you won’t get if you use the HTML5 date field. Setting Date Picker Properties You can set properties of the Datepicker widget—like the date format jQuery UI will use when writing the date into the form field—by passing an object to the datepicker() function. This object literal contains datepicker options and values to control those options. For example, one option—numberOfMonths—lets you specify how many months should appear when the date picker opens. Normally that’s just 1 as pictured in Figure 10-1, but it’s possible to display three months at a time, as shown in Figure 10-2, by setting this value to 3: $('.date').datepicker({ numberOfMonths : 3 }); Here are some of the most useful options: • changeMonth. Normally, visitors can change the month displayed by the Datepicker pop-up calendar by clicking either the left or right arrows in the top of the calendar (Figure 10-1). These buttons display either the previous (left) or next (right) month. However, this is a tedious way to select a date that’s nine months away. Set the changeMonth option to true, and a drop-down menu appears in the calendar, letting visitors quickly choose a new month (Figure 10-2). changeMonth : true Chapter 10: Forms Revisited 353 PICKING DATES WITH STYLE FIGURE 10-2 jQuery UI’s Datepicker widget is highly customizable. You can change the number of months visible at a time, place the year before the month name, and supply different names for months to match different languages. • changeYear. Like changeMonth, this option, when set to true, tells jQuery UI to display a drop-down menu for selecting a new year for the calendar. You’ll frequently use this option with the yearRange option (page 346) to set the number of years to display in the drop-down menu. changeYear : true • dateFormat. Lets you supply a string that defines the format you want jQuery UI to use when writing the selected date to the input field. You use predefined codes to define different outputs. For example, dd is used to indicate day of the month, mm the month of the year, and yy the year. You can also insert characters like space, /, or - as part of the string. For example, say someone selects January 27, 2015 from the pop-up calendar, and you want this to appear in the actual form as 01-27-2015. You’d set the dateFormat option like this: dateFormat : 'mm-dd-yy' jQuery UI supplies many different codes for formatting the date. For some useful examples, see Table 10-1. You can find a complete list of formats jQuery UI’s Datepicker widget accepts for the dateFormat option at http://api.jqueryui. com/datepicker/#utility-formatDate. NOTE There are other options, events, and methods for jQuery UI’s datepicker widget. To see them all, visit http://api.jqueryui.com/datepicker/. • monthNames. Provide an array of 12 strings to use names other than English months. For example, to make datepicker display French names of the month, you’d add this to the object literal passed to datepicker() function: monthNames: [ "Janvier", "Février", "Mars", "Avril", "Mai", "Juin", "Juillet", "Août", "Septembre", "Octobre", "Novembre", "Décembre" ] 354 JAVASCRIPT & JQUERY: THE MISSING MANUAL • numberOfMonths. Assign a number to this option to determine the number of months visible in the pop-up date picker. Normally it’s a single month, but you can specify whether you want to display more months. If you go beyond three months (pictured in Figure 10-2), the datepicker pop up begins to be a bit unwieldy. The months always appear side by side, so if there are more than three or four, you’ll have to scroll sideways to see the other months and make a selection in them. Stick to 1, 2, or 3. PICKING DATES WITH STYLE • maxDate. Sets the latest date that a visitor can select from the datepicker popup calendar. For example, you could use this for a hotel reservation system. Many hotels don’t let you reserve a room more than one year in advance, so you could limit the datepicker to no further than one year from the current date. One way is to assign a number specifying a number of days in the future. For example, to limit a visitor from picking a day that’s later than 30 days in the future, you could set the maxDate option like this: maxDate : 30 Alternatively, you can give this option a string containing special characters that indicate amounts of time—y for years, m for months, w for weeks, and d for days. For example, to limit a selection to one year out or less, set the maxDate option like this: maxDate : '+1y' Separate each time character by a space. So, for example, if you want to limit the date selection to three months, two weeks, and five days into the future, you’d do this: maxDate : '+3m +2w +5d' You’ll find an example of the maxDate option in action in the tutorial on page 359. • minDate. The opposite of the maxDate option. It sets the earliest selectable date from the datepicker. This setting is very useful for a scheduling form—after all there’s no point in letting a visitor schedule a reservation that’s before today (unless time travel has been discovered since this book was written). You use the same characters as maxDate to specify the earliest date. For example, to prevent people from selecting a date earlier than today, set this option to 0, like this: minDate : 0 Positive values for this option mean the visitor has to select a day in the future. For example, if the hotel is booked for the next three weeks, you can prevent a visitor from selecting a date in that time like this: minDate : '+3w' Chapter 10: Forms Revisited 355 PICKING DATES WITH STYLE Use negative values to set the earliest selectable date in the past. For example, say you’ve created a form for searching your company’s database of archived email. To keep the database from bursting at the seams, your company only stores the past two years’ worth of email records, so there’s not point in letting people search three, four, or five years in the past—those emails were erased a long time ago. Here’s how to limit the search to just the past two years: minDate : '-2y' You can combine dates, months, and years as well. For example, here’s how to specify a date that’s one year, two months, and three days in the past: minDate : '-1y -2m -3d' NOTE The minDate and maxDate options also accept a JavaScript date object as an acceptable value. For example, say your company started business on March 13, 2010. You could set the minimum selectable date for a datepicker calendar to that date like this: minDate : new Date(2010, 2, 13) See page 568 to learn how to create date objects using JavaScript. • yearRange. This option is used with the changeYear option (page 354), and determines how many years are displayed in the drop-down year menu. For example, say you want to collect someone’s date of birth. You set the changeYear option to true so it’s easy for a visitor to jump back 20, 30, or 50 years. Normally, the changeYear option forces that drop-down menu to show 10 years in the past and 10 years in the future. It would be better to list a lot of years in the past and no years in the future (unless, again, time travel has been perfected). To do that, you give the yearRange option a positive or negative number, followed by a colon, followed by another positive or negative number. The first number represents the first year listed in the menu, and the second number is the last year in the menu. Back to the birth year example, you’d want to be able to list perhaps 120 years back, but no years in the future. Here’s how: yearRange : '-120:0' This setting tells jQuery UI to display a drop-down menu to select a year, with the first year on the list 100 years before this year and the last year on the list the current year. If you’re getting confused, check out the tutorial on page 359 for an example. 356 JAVASCRIPT & JQUERY: THE MISSING MANUAL TABLE 10-1 Useful strings for supplying to the dateFormat option. EXAMPLE WHAT IT MEANS EXAMPLE OUTPUT 'yy-mm-dd' Complete year, dash, 2 digit month, dash, 2 digit day. This is the format used for a date in MySQL databases. 2015-02-05 'm/d/y' 1 or 2 digit month, forward slash, 1 or 2 digit day, forward slash, 2 digit year 2/5/15 'D, M d, yy' Abbreviated day-of-theweek name, comma, space, abbreviated month name, space, 1 or 2 digit day, comma, space, complete year. Thu, Feb 5, 2015 'DD, MM dd, yy' Full day-of-the-week name, comma, space, full month name, space, 1 or 2 digit day, comma, space, complete year. Thursday, February 5, 2015 '@' Unix timestamp. The number of milliseconds since midnight on January 1, 1970 (see page 570). 1423123200000 PICKING DATES WITH STYLE Tutorial: Adding a Birthdate Picker It’s time to try out the Datepicker widget. In this tutorial, you’ll turn a text field into an intelligent device for easily selecting a person’s birthdate. NOTE See the note on page 12 for information on how to download the tutorial files. 1. In your text editor, open the file birthdate.html in the chapter10 folder. This file already contains a link to all of the jQuery and jQuery UI files and the $(document).ready() function (page 160). The first step is selecting the input element. 2. Inside the $(document).ready() function, type: $('#dob') If you look at the HTML for this page, you’ll see an input element for collecting a birthdate: <input type="text" id="dob" name="birthdate">. It has an ID of dob, so this code selects that form field. Now you need to apply the Datepicker widget. Chapter 10: Forms Revisited 357 PICKING DATES WITH STYLE 3. Type a period, followed by datepicker(); so the code now looks like this: $('#dob').datepicker(); That’s all there is to it! 4. Save the file and preview it in a web browser. Click the input field. A calendar pops up like magic. This calendar uses jQuery UI’s UI Lightness theme, but you’ll learn how to change the widget’s appearance in the next chapter. If you try to select your birthdate, you’ll see it’s kind of a pain. You have to hit the left arrow button at the top of the calendar 12 times just to go back one year! So you’ll make it easier to select an older date by adding drop-down menus for the month and year. 5. Return to your text editor, and in the datepicker() function, add an object literal, like this: $('#dob').datepicker({ }); To change options, you pass the datepicker() function an object—{ }—filled with options, names, and values. First, add a drop-down menu for selecting months. 6. Add changeMonth : true to the object: $('#dob').datepicker({ changeMonth : true }); If you save the page now, preview it in a web browser, and click inside the form field, you should see a drop-down menu in the calendar’s header that lets you select any of the 12 months of the year. This menu provides a much faster way to select a date that happened 9 months ago. Next you’ll create a drop-down for the year. 7. Type a comma after the line you just typed, hit Return, and type changeYear : true: $('#dob').datepicker({ changeMonth : true, changeYear : true }); This adds another drop-down menu to the calendar. Unfortunately, that menu only goes back 10 years and also includes the next 10 years, which isn’t what you want. Unless your visitor is younger than 10 or owns a time machine, the choices in this drop-down menu aren’t going to be of much use. Fortunately, you can change the range of years that appear in the menu. 358 JAVASCRIPT & JQUERY: THE MISSING MANUAL 8. Type a comma after the line you just typed, hit return and type yearRange : '-120:+0': PICKING DATES WITH STYLE $('#dob').datepicker({ changeMonth : true, changeYear : true, yearRange : '-120:+0' }); This changes the years displayed in the year drop-down menu. It now goes back 120 years and doesn’t display any years after the current one. Much better. However, if you give this latest change a try, you’ll notice that it is possible to select tomorrow, or a date next week or next month. At the very least, you want to limit this form to babies that were born today. 9. Type another comma after the line you just typed, hit return and type maxDate : 0 like this: $('#dob').datepicker({ changeMonth : true, changeYear : true, yearRange : '-120:+0', maxDate : 0 }); Now you can’t pick a date beyond the current one. Finally, you’ll change the format of the date, so birthdates are written like this: 1-27-2015. 10. Type another comma after the line you just typed, hit Return, and type dateFormat : 'm-dd-yy' like this: $('#dob').datepicker({ changeMonth : true, changeYear : true, yearRange : '-120:+0', maxDate : 0, dateFormat : 'm-dd-yy' }); Now you have a highly customized date picker, perfect for selecting birthdates. 11. Save the file and preview it in a web browser. When you click in the input field the final date picker appears (see Figure 10-3). You can find a complete version of this tutorial in the complete-birthdate.html file in the chapter10 folder. Chapter 10: Forms Revisited 359 STYLISH SELECT MENUS FIGURE 10-3 jQuery UI’s Datepicker widget is a must-have for any form that requires inputting a date. You can customize it in almost infinite ways to select dates in the future, or limit a selection to just dates in the past. In this case, any date after July 12, 2014 is grayed-out and therefore not selectable, but drop-down menus make it easy to select a year long in the past and a month far from July on the calendar. Stylish Select Menus jQuery UI’s themes let you add a unified design to your user interface elements. For example, the date picker looks similar to tabbed panels, which look similar to dialog boxes. Select menus—those form elements that let you pick an option from a dropdown menu—are notoriously hard to style with CSS. Each browser has its own way of displaying select menus—which is often dictated by the operating system (Windows, Mac, Linux)—and browsers don’t let you apply every CSS property to select menus. Fortunately, jQuery UI provides a handy Selectmenu widget which takes a regular HTML select menu and converts it into a much more attractive menu that matches the look of other jQuery UI widgets (see Figure 10-4). The Selectmenu widget literally re-creates the select menu as an unordered list and a series of <span> tags, which 360 JAVASCRIPT & JQUERY: THE MISSING MANUAL are more accepting of CSS styling. Using clever JavaScript programming, this widget hides the real menu, while letting visitors select an option from a JavaScript-powered drop-down menu. The visitor’s selection is mirrored by the real form element, so when the visitor submits the form, the visitor’s selection is correctly passed to the web server. STYLISH SELECT MENUS Behind the scenes, jQuery UI is performing some sophisticated programming magic, but for you, turning a select menu into a jQuery UI select menu couldn’t be simpler: 1. Follow the steps on page 304 to attach jQuery UI’s CSS and JavaScript files to your web page. You’ll need to attach the jQuery file as well, so whenever you use a jQuery UI widget, you’ll have the jQuery UI CSS, jQuery JavaScript, and jQuery UI JavaScript files attached to your page (in that order, too). 2. Add a form to a page, and include a select menu: that’s a <select> tag containing <option> tags: <select name="meal" id="meal"> <option>No meal</option> <option>Vegan</option> <option>Gluten Free</option> <option>Vegetarian</option> <option>Meat eater</option> </select> You should include a way to select the menu using jQuery. Either apply an ID to the menu, or if you have multiple select menus in a form, apply the same class to each: class="select", for example. 3. Add jQuery’s $(document).ready() function to your page: $(document).ready(function() { }); // end ready You only need to do this if you’re placing your JavaScript programming in your page’s <head>, as described on page 161. 4. Use jQuery to select the menu and call the selectmenu() function: $(document).ready(function() { $('#meal').selectmenu(); }); // end ready Or, if you’ve used a class to identify more than one menu, you could write this: $(document).ready(function() { $('.select).selectmenu(); }); // end ready Chapter 10: Forms Revisited 361 STYLISH SELECT MENUS Unless the options in the menu are very short, jQuery UI’s Selectmenu widget often doesn’t display the first option completely. In other words, the widget isn’t wide enough to display the first option. This looks weird, so you should always set the width of the menu. 5. Pass an object literal to the selectmenu() function with a width property: $(document).ready(function() { $('#meal').selectmenu({ width: 200 }); }); // end ready As with other jQuery UI widgets (see the Datepicker on page 353, for example), you can set various options for the Selectmenu widget by passing an object literal containing option/value pairs. The width option is almost always required and accepts a numeric value that indicates the number of pixels wide the menu should be (see the next section for more options for the width property). These are the only steps you need to create a menu like the one in Figure 10-4. FIGURE 10-4 The normal appearance of a form’s select menu is controlled by the browser and operating system (left). However, using jQuery UI, you can turn drab menus into stylish interface elements that match the overall appearance of other jQuery UI widgets. Setting Select Menu Properties The Selectmenu widget doesn’t have many options. It’s mainly a tool to make select menus look more like other jQuery UI widgets. However, there are a few options that you may find useful: • width. This option is almost never optional. Normally, jQuery UI creates a menu that’s not wide enough to display all of the text for a single select menu option. You’ll want to set this wide enough that you can read an entire menu option. In addition, if the menu isn’t wide enough to display an option that’s more than one word long, then jQuery UI will display the option on two lines. You can use a number if you want to set the width in pixels like this: width : 300 362 JAVASCRIPT & JQUERY: THE MISSING MANUAL You can also specify a width in percentages or ems by using a string containing a number with either % or ems following. For example, to make the menu fit its parent element (like a containing div), you could set its width to 100% like this: STYLISH SELECT MENUS width : '100%' Or, if you prefer em units, you could set the width of a menu to 6 ems like this: width : '6em' • icons. You can also display one of jQuery UI’s icons to the right of the menu, like the triangle in Figure 10-4. jQuery UI includes a large selection of icons as part of each theme (see http://api.jqueryui.com/theming/icons/ for a complete list). You can add an icons by supplying an icons option and a value that includes an object literal like this: icons : { button: "ui-icon-circle-triangle-s" } NOTE You may be wondering why the icons option requires another object literal with a name/value pair. After all, it would be a lot easier to assign the icon name to the icons property. That would make sense if selectmenu were the only widget you can assign an icon to. Other widgets also can display icons, and some widgets, like the accordion widget (page 338), let you assign more than one icon. For that widget, you have to pass an object literal containing multiple name/value pairs to display more than one icon. To remain consistent with other jQuery UI widgets, the Selectmenu widget also requires an object value for the icons option. • position. You can control the position of the pop-up menu using this option. Normally, the menu appears directly under the menu control—that’s how select menus normally work. However, you can make the pop-up list of menu options appear to the left or right of the control if you want. To do this, you can set the position option using jQuery UI’s position object. Because positioning a select menu anywhere other than directly below the form control is unexpected behavior, be careful with this property as you might end up confusing visitors. (This specialized utility is discussed in the previous chapter in the box on page 318.) Performing an Action When a Visitor Selects an Option When a visitor makes a selection from a menu, usually something should happen as a result. For example, say you have an online clothing order form with a select menu listing all available colors. When a visitor selects a color from the menu, you may want to update the picture of the clothing item to show the item in that color. In other words, selecting an item from the menu changes an image on the page. jQuery UI lets you call a function whenever a new selection is picked from the menu. To do so, you use the change option. It works like the other options discussed in this chapter in that you put it inside an object literal that you pass to the selectmenu() function. For the option value, you supply a function to the change option. For Chapter 10: Forms Revisited 363 STYLISH SELECT MENUS example, say you had a select menu with the ID colors. You would turn this menu into a jQuery UI Selectmenu widget and add a change option to it like this: $('#colors').selectmenu({ width : 300, change : function (event, ui) { // put your programming here } }); Whenever a visitor makes a new selection from the menu (that is, changes the menu), the function will run. The function has two parameters—event and ui. The event parameter contains a jQuery UI event object (page 164). You probably won’t need to use that parameter in the function—it only contains event information, like the mouse’s X and Y positions and other things that aren’t useful for working with menu selections. However, the ui parameter contains useful information about the select menu. In particular, it can tell you the index value of the newly selected option; that is, its place in the menu, with the first option having an index of 0. The ui parameter also knows the label and value of the selected option. The ui parameter is an object itself, composed of different properties that you can access using dot notation (page 55). • ui.item.index contains the index value of the selected menu option. Menu options are numbered like arrays: the first item in the menu is 0, the second is 1, and so on. • ui.item.label contains the label of the selected menu option. The label is the word or words the visitor sees in the select menu. It appears in the HTML inside the <option> tag. So if you had this menu on a page: <select id="colors"> <option>Red</option> <option>Green</option> <option>Blue</option> </select> the labels for the items in this menu are “Red,” “Green,” and “Blue.” • ui.item.value contains the value of the selected menu option. The value is set using the option tag’s value attribute. Often, the label and value are the same thing. If that’s the case, you don’t need to specify a value attribute in your HTML. But sometimes you want to submit a different value to the server that processes the form input. For example, a company might have special codes that indicate a precise stock color. A visitor might want a “red” shirt, but to the clothing company, which might have multiple shades of red for different clothing types, that red shirt color might have a special code like “R785”. 364 JAVASCRIPT & JQUERY: THE MISSING MANUAL In this case, the form will include values in addition to labels like this: STYLISH SELECT MENUS <select id="colors"> <option value="R785">Red</option> <option value="G101">Green</option> <option value="B498">Blue</option> </select> For this menu, the values are "R785", "G101", and "B498", while the labels are still “Red,” “Green,” and “Blue.” Now think about how you might change an image on a page when a visitor makes a change to a menu. Say you use the HTML for the menu above, with the three color options—Red, Green, and Blue. When a visitor makes a selection, the browser should load an image of a shirt that matches the color selected. Assume there’s the following HTML on the page when it loads: <img src="red_shirt.jpg" id="shirt" alt="Buy our shirts!"> As you read on page 209, by changing an image’s src attribute, you can tell a browser to load a new image in that spot. So for example, to load a picture of a blue shirt to the page, you could select this image and change its src attribute like this: $('#shirt').attr('src', 'blue_shirt.jpg'); Putting all of this together, you could then change the image each time a new menu option is selected like this: $('#colors').selectmenu({ width : 300, change : function (event, ui) { var newImage; if (ui.item.label === 'Red') { newImage = 'red_shirt.jpg'; } else if (ui.item.label === 'Green') { newImage = 'green_shirt.jpg'; } else { newImage = 'blue_shirt.jpg'; } $('#shirt').attr('src', newImage); } }); You can do all sorts of things with the change option, like updating HTML, adding a second select menu with another set of options related to the original menu’s selected option, and so on. NOTE There are other options, events, and methods for jQuery UI’s Selectmenu widget. To learn them all, visit http://api.jqueryui.com/selectmenu/. Chapter 10: Forms Revisited 365 STYLING BUTTONS Styling Buttons jQuery UI also includes a widget to make a variety of button-like form elements look and behave similarly. The Button widget can be used to style a submit button, a reset button, or an <input> element with the type of button: <input type="button">. In addition, you can use it to style the HTML <button> element to match the look of a jQuery UI CSS theme (Figure 10-5): 1. Follow the steps on page 304 to attach jQuery UI’s CSS and JavaScript files to your web page. You’ll need to attach the jQuery file as well, so that whenever you use a jQuery UI widget you’ll have the jQuery UI CSS, jQuery JavaScript, and jQuery UI JavaScript files attached to your page (in that order). 2. Add a button to the page. It can be either a reset, submit, or input button or <button> element. For example: <input type="submit" id="submit" value="Submit form!"> <input type="reset" id="reset" value="Reset form."> <input type="button" id="inputButton" value="An input button."> <button id="button">A button element</button> You also need to include a way to select the menu using jQuery. You can either apply an ID to the element, or if you have multiple buttons in a form, apply the same class to each: class="button", for example. 3. Add jQuery’s $(document).ready() function to your page: $(document).ready(function() { }); // end ready You only need to do this if you’re placing your JavaScript programming in the <head> of your page, as described on page 160. 4. Use jQuery to select the button and call the button function: $(document).ready(function() { $('#submit').button(); }); // end ready Or, if you’ve used a class to identify more than one button, you could write this: $(document).ready(function() { $('.button').button(); }); // end ready When applied, the widget simply styles the element to match the jQuery UI theme that’s in use (Figure 10-5). 366 JAVASCRIPT & JQUERY: THE MISSING MANUAL STYLING BUTTONS FIGURE 10-5 jQuery UI’s button widget provides a quick and simple way to turn drab form elements like radio buttons, checkboxes, submit, and HTML buttons (top) into elegant looking interface elements that provide a consistent presentation (bottom). Customizing Buttons The jQuery UI button widget doesn’t provide many options for customization. The text you see on the button is provided by the value attribute, in the case of <input> elements like the submit and reset buttons. In the case of the <button> element, which includes an opening and closing tag—<button>I'm a button</button>—the text you see in the button comes from the text between the tags. However, you can customize buttons in a few ways by passing option settings to the button() method. • icons. You can also display one of jQuery UI’s icons to the left of a button and another icon on the right (see the <button> element in Figure 10-5 for an example). jQuery UI includes a large selection of icons as part of each theme (see http://api.jqueryui.com/theming/icons/ for a complete list). You can add an icon by supplying an icons option and a value that includes an object, like this: icons : { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } The “primary” icon appears on the left, while the “secondary” icon appears to its right. You don’t have to specify two icons—in fact, that usually looks pretty Chapter 10: Forms Revisited 367 IMPROVE RADIO BUTTONS AND CHECKBOXES weird. Usually, you’ll just specify one of the two. For example, to display a right-pointing arrow on all <button> elements on a page, you could write this: $('button').button({ icons : { secondary: 'ui-icon-circle-arrow-e' } }); NOTE You can’t use the icons option on any button created using the <input> element—that is, submit or reset buttons—only on the <button> element. • text. If you’re using <button> elements, and applying icons to those buttons, you can completely hide the text on that button and just display the icon. By setting the text option to false, you hide the button’s label and only display the icon. For example, say you had a button with the label “Next” on it: <button id="next">Next</button> You could turn that button into a jQuery UI button, add a right-pointing arrow icon to it, and remove the word “Next” from the button like this: $('#next').button({ icons : { secondary : 'ui-icon-arrowthick-1-e' }, text : false }); NOTE The jQuery UI button widget has a couple other options, methods, and events, which you can read about at http://api.jqueryui.com/button/. Improve Radio Buttons and Checkboxes Radio buttons and checkboxes are more form elements that don’t look so great in their native format (see Figure 10-5, top). Browsers use the native look for operating system buttons and checkboxes, which don’t allow the same amount of CSS customization as other HTML elements. Fortunately, jQuery UI provides a widget to make radio buttons and checkboxes share the look and feel of other jQuery UI elements (see Figure 10-5, bottom). The really good news is that it takes almost no work on your part to take advantage of this improved appearance. The jQuery UI .buttonset() method does all of the work. In fact, it simply applies the .button() method to each radio button or checkbox in a group. All you have to do is a little bit of HTML setup: wrap the group of buttons in some kind of container element like a <div> tag so you can select it with jQuery. For example, say you’re creating an airline reservation form where customers can indicate 368 JAVASCRIPT & JQUERY: THE MISSING MANUAL the number of bags they will check—either 0, 1, or 2 bags. You might have HTML organized like this: IMPROVE RADIO BUTTONS AND CHECKBOXES <div id="radio"> <p class="label">Number of bags to check</p> <input type="radio" id="none" name="bags" checked="checked"> <label for="none">0</label> <input type="radio" id="one" name="bags"> <label for="one">1</label> <input type="radio" id="two" name="bags"> <label for="two">2</label> </div> There are three radio buttons—<input type="radio">—which are enclosed by a div with an ID of radio. To turn these into a jQuery UI radio button group, just follow steps 1–3 on page 304 to download and attach the jQuery and jQuery UI CSS and JavaScript files, and add a $(document).ready() function to the page. Then add the following JavaScript code: $('#radio').buttonset(); It’s as easy as that. The $('#radio') part selects the div containing the radio buttons; the .buttonset() code looks for every radio or checkbox element inside the div and turns each of them into a button. The unique part about the buttonset() function is that it groups all of those elements so they appear as a unit (see Figure 10-6). TIP By default, jQuery UI’s CSS formats a group of buttons or checkboxes as a single unit (Figure 10-6). That is, they sit side by side and touch each other. If you prefer to have the buttons not touch, and appear as separate buttons sitting side by side, just apply the button() function to each element individually. For example, given the HTML above and the group of radio buttons, you could add this JavaScript code to create individual buttons: $('#radio input').button(); This applies the button() function individually to each radio button inside the div. The same technique applies to checkboxes. Just group the adjoining checkboxes in some kind of selectable container like <div id="check">, select that container, and apply the buttonset() function. Whether it’s a group of radio buttons or a group of checkboxes, jQuery UI formats them the same way, as shown in Figure 10-6. However, the two types of controls behave differently: With radio buttons, only one button in the group can be selected at a time. With checkboxes, you can select any number of checkboxes in the group (or none at all). jQuery UI highlights selected buttons or checkboxes. Chapter 10: Forms Revisited 369 PROVIDING HINTS WITH AUTOCOMPLETE FIGURE 10-6 You can only select a single button in a group of radio buttons (top). In this example, the middle button—“1”—is selected (and highlighted by jQuery UI). You can, however, select any number of boxes among a group of checkboxes (bottom). Here, the first (“Aisle”) and third (“Exit Row”) checkboxes are selected. The buttonset() function doesn’t take any arguments. However, behind the scenes, it just applies the button() method to each button or checkbox in the group. This means you can customize the buttons further using the options discussed on page 366. Providing Hints with Autocomplete Many sites with a search box provide a helpful feature that provides suggestions matching what you’ve started to type. For example, visit Amazon and type light, and a drop-down menu appears suggesting categories of products that include the word “light”—light bulbs, LED lights, light switch covers, and so on (Figure 10-7). Instead of typing the rest of the word, you can click one of the suggestions, or even use the keyboard up and down arrow keys to make a selection from the menu. This suggestion feature is called autocomplete, and jQuery UI includes a helpful widget that lets you provide this feature on your own site. You can add autocomplete to any text field on a form. For example, say you’re building an airline reservation system, and a customer needs to type the airport he’s flying from. When he starts typing the name of her airport, a helpful drop-down menu appears suggesting airports that match the first few letters that he types. He can then just click one of the airports that appears in the menu instead of typing out the entire name. 370 JAVASCRIPT & JQUERY: THE MISSING MANUAL PROVIDING HINTS WITH AUTOCOMPLETE FIGURE 10-7 Don’t your fingers hurt from typing all of the time? Many websites try to make it easier on your fingers by suggesting search terms that match what you’ve begun to type. Even better, you can use the autocomplete feature to place different content in the text field. Using the airline reservation example, a customer could type in the name of the city she’s flying out of, and when she picks the name from the list, the airport code is added to the form instead. For example, typing Portland might provide a list of airport names including “Portland International Airport.” When the customer picks that option, the airport code—PDX—is written in the text field instead. You could use this feature to locate the product number of an item in a catalog. When someone types the name of a product and selects that name from the pop-up autocomplete menu, the product number is added to the text field. To use the Autocomplete widget, you need to provide data to jQuery UI that it can use to try to find matches to display in the pop-up autocomplete menu. For example, you need a list of airport names, so that jQuery UI can try to find a match to whatever the visitor types in the airport form field. There are two ways you can do this: provide an array of information using JavaScript, or send the search term Chapter 10: Forms Revisited 371 PROVIDING HINTS WITH AUTOCOMPLETE to the web server using Ajax, and have the web server send back a list of matching terms. You’ll see both approaches later in this chapter, but first here’s the basic method for adding autocomplete to a form: 1. Follow the steps on page 304 to attach jQuery UI’s CSS and JavaScript files to your web page. You’ll need to attach the jQuery file as well, so that whenever you use a jQuery UI widget you’ll have the jQuery UI CSS, jQuery JavaScript, and jQuery UI JavaScript files attached to your page (in that order, too). 2. Add a form to the page, and include a text input field: <input type="text" id="airport" name="airport"> You should also include a way to select the menu using jQuery. For example, apply an ID to the field. 3. Add jQuery’s $(document).ready() function to your page: $(document).ready(function() { }); // end ready You need to do this only if you’re placing your JavaScript programming in your page’s <head>, as described on page 160. 4. Use jQuery to select the text field and call the autocomplete function: $(document).ready(function() { $('#airport').autocomplete(); }); // end ready At the very least, you need to pass the autocomplete() function an object containing a property named source, and either an array of items or a URL of a server-side program that can return a list of possible matches to the visitor’s typed input. The following sections cover the two ways to do this—you’ll either use an array or a server-side script. Using Arrays for Autocomplete The Autocomplete widget requires a list of terms that jQuery UI uses to search for matches to the visitor’s typed input. The simplest way to do this is to provide an array of items that jQuery UI will use. For example, maybe you have a question like “What’s your favorite shade of red?” You could provide an array of color names, and supply that to the autocomplete() function like this: var colors = ['Barn Red', 'Beetroot', 'Brick', 'Bright Maroon', 'Burgundy']; $('#redInput').autocomplete( { source : colors } ); In other words, you start by creating an array—colors. Then you pass an object to the autocomplete() function with a property named source and a value that’s the array: { source : colors }. 372 JAVASCRIPT & JQUERY: THE MISSING MANUAL After this code runs, and a visitor types the letter B into the text field, a menu appears listing all the items in the array: “Barn Red,” “Beetroot,” “Brick,” “Bright Maroon,” and “Burgundy” (Figure 10-8, top). However, if the visitor next types r so “Br” is listed in the field, he’d see only the two colors that have “Br” in their names: “Brick,” and “Bright Maroon” (Figure 10-8, bottom). PROVIDING HINTS WITH AUTOCOMPLETE FIGURE 10-8 jQuery UI’s Autocomplete widget makes typing common search terms easier by providing hints to words that match what the visitor types. An array of only five items, however, doesn’t really provide a lot of value. After all, if those were the only options, you might as well just use a select menu with those choices listed. Autocomplete is really most useful when you can provide your visitors lots of suggestions—more than would be comfortable in a normal drop-down menu. With lots of options, it’s a good idea to create a separate JavaScript file that only contains the data you want to use as the source option for the widget. For example, say you wanted to provide autocomplete for a text field requiring an airport name. You could create a separate JavaScript file—airports.js, for example—that creates an array and assigns values to it, like this: var airports = [ 'Aberdeen Regional Airport, Aberdeen, South Dakota', 'Abilene Regional Airport, Abilene, Texas', 'Abraham Lincoln Capital Airport, Springfield, Illinois', 'Adak Airport, Adak Island, Alaska', 'Adirondack Regional Airport, Saranca Lake, New York' ]; // lots more airports would go in here Chapter 10: Forms Revisited 373 PROVIDING HINTS WITH AUTOCOMPLETE NOTE This is just the beginning of the list for U.S. airports! In real life, you would have a very long list—a very large array—of airport names in the above code. This file would be large, and you wouldn’t need to use this array on every page in your site, so it’s best to put it into its own file and link to it only on the page that uses the autocomplete widget. You’d attach this file just as you would attach any JavaScript file to a page (page 15). For example: <script src="airports.js"></script>--> You need to make sure that this file is attached to the page before you use the autocomplete widget because you need to load the array before calling the autocomplete() function. For example, the JavaScript-related code in the web page’s would look something like this: <link href="css/jquery-ui.min.css" rel="stylesheet"> <link href="css/site.css" rel="stylesheet"> <!--<script src="js/jquery.min.js" type="text/javascript"></script>--> <!--<script src="js/jquery-ui.min.js" type="text/javascript"></script>--> <!--<script src="js/airports.js" type="text/javascript"></script>--> <!--<script type="text/javascript"> $(document).ready(function() { $('#airport').autocomplete( { source : airports} ); }); // end ready </script>--> Notice that the airports.js file loads before the autocomplete() function runs so as to make sure the airports array is created first and can then be passed to the widget. Using Separate Labels and Values Choosing an option from the pop-up autocomplete menu instructs jQuery UI to write that item into the text field. For example, in the form pictured in Figure 10-8, if, after typing B, the visitor clicked “Bright Maroon” from the menu, then jQuery UI would fill out that text field with the words “Bright Maroon.” You can also instruct jQuery UI to write something different from what appears in the pop-up autocomplete menu. For example, with the airport example, say someone typed Ab in the text field. The Autocomplete widget would then display a list of three airports—Aberdeen Regional Airport, Abilene Regional Airport, and Abraham Lincoln Capital Airport. You can tell jQuery UI to write the airport code instead of the actual name, so if the visitor selected “Abilene Regional Airport,” you could have jQuery UI write “ABI” in the text field. To do this, you supply an array of objects. Each object contains two properties—label and value. The label is what the visitor sees in the pop-up autocomplete form, and the value is what jQuery UI actually adds to the form field after the visitor makes a selection. For example, in the airport example, the label will be the airport name, 374 JAVASCRIPT & JQUERY: THE MISSING MANUAL and the value is the airport code. For example, the object to identify the Abilene Airport would look like this: PROVIDING HINTS WITH AUTOCOMPLETE { label : 'Abilene Regional Airport, Abilene, Texas', value : 'ABI' } And the array of airport values would start off like this: var airports = [ { label : 'Aberdeen Regional Airport, Aberdeen, South Dakota', value : 'ABR' }, { label : 'Abilene Regional Airport, Abilene, Texas', value : 'ABI' }, { label : 'Abraham Lincoln Capital Airport, Springfield, Illinois', value : 'SPI' }, { label : 'Adak Airport, Adak Island, Alaska', value : 'ADK' }, { label : 'Adirondack Regional Airport, Saranca Lake, New York', value : 'SLK' } ]; // lots more airports would go in here NOTE Again, this is an incomplete list of U.S. airport names and codes. The actual airports.js file would be huge. Each of the objects in this array has two properties. You still pass the array to the autocomplete() function the same way—jQuery UI is programmed to adjust how it works when it gets an array of objects like this. $('#airport').autocomplete( { source : airports} ); When passed an array of objects, the Autocomplete widget now tries to match the visitor’s input to a matching label in each object. However, when the visitor actually makes a choice from the drop-down menu, the second property in the selected object—the value property—is inserted into the form. You’ll see an example of this on page 383 in step 12 of the tutorial. Chapter 10: Forms Revisited 375 PROVIDING HINTS WITH AUTOCOMPLETE Getting Autocomplete Data from the Server The Autocomplete widget is most useful when you have lots of data that it can search through. Remember the example on page 372, where you supplied just six shades of red? That small number of options won’t help a user’s search much. Creating a file with a very large array isn’t that easy, and in many cases, not realistic. For example, Amazon’s autocomplete feature certainly doesn’t rely on one large JavaScript file containing a list of every single product category and description on its site: that file would be immense, and loading it from the Web would take a really long time. Many sites that include an autocomplete feature (like Google and Amazon) use server-side programming to send a much smaller list of autocomplete hints. Here’s how it works: 1. A visitor begins typing into a text field. 2. The visitor’s input is sent to the server. Using Ajax, the browser sends data to the server and waits for a response. In this case, the browser sends the text the visitor has typed so far. 3. The server sends back an array of terms that match what the visitor has typed so far. The server provides a list of matching terms. Usually, this is accomplished using server-side programming that searches a database, gets results, and formats those results into an array that’s sent back to the browser. 4. The list of matching terms appears in the autocomplete menu. As you can see, a lot of this magic happens thanks to Ajax, which lets you use JavaScript to send and receive information to a web server without needing to reload a new web page (you’ll read all about Ajax in Chapter 13). The server-side programming part of this equation isn’t what this book is about—to create server-side programs in PHP, Ruby, Python, and even in JavaScript (using Node.js), you’ll need to turn to another source. However, here’s how you use jQuery UI’s autocomplete widget to talk to the server: instead of providing an array of possible search terms for the source property, you provide a URL pointing to a server-side script. For example, say you had a text field that visitors use to search your company’s catalog of 250,000 products. To make it easier for visitors to search, you want to add autocomplete to that field; however, your catalog of products is way too big to stuff into a single array in one JavaScript file. So instead, you set up a server-side program named products.php located in the root of your site. You could then specify the path to that file using the source property. Let’s assume that you gave the input field an ID of "productSearch" like this: <input type="text" id="productSearch" name="productSearch"> In the JavaScript for your page, you could then apply the autocomplete widget to this element and point to the server-side page like this: $('#productSearch').autocomplete( { source : '/products.php'} ); 376 JAVASCRIPT & JQUERY: THE MISSING MANUAL You can also provide a complete URL including protocol and domain name like this: PROVIDING HINTS WITH AUTOCOMPLETE $('#productSearch').autocomplete( { source : 'http://myCompany.com/products. php'} ); When you supply an array of elements for the source option (described on page 372), jQuery UI filters that array to find items that contain the text the visitor has started typing; jQuery UI displays only those matching items from the array. The autocomplete widget behaves a little differently when supplying a URL for the source option. jQuery UI displays all of the data the server returns and doesn’t filter that data for matches. For example, if a visitor typed Light, and the server returned an array containing “Dark,” “Artichoke,” and “Ostrich,” jQuery UI would pop-up the autocomplete menu listing “Dark,” “Artichoke,” and “Ostrich.” In other words, it’s entirely up to the server to return the correct data. That means you (or another programmer) needs to write all of the logic to generate the proper list and send it back to the browser. To help in that task, jQuery UI adds on a URL parameter to tell the server what it needs to search for. The parameter is named term, and its value is whatever the visitor has typed into the field. In the product search example, if the visitor typed light, jQuery UI would send a request to the server like this: http://myCompany.com/products.php?term=light It’s up to the products.php page to then do something with that data—for example, search the database for products that somehow relate to light. This could be a literal search that displays only products with the name “light” in them: “light bulb,” “lightning rod,” and so on. Or, the program might be more complete and return products related to the concept of light, such as “fluorescent bulb,” “antigravity machine,” and so on. It’s up to the programmer to decide how to process this search term and what data to send back. NOTE It’s also possible to use the autocomplete feature to point to another domain and web server. However, due to Ajax’s security limitations, that server must be set up to respond using a special format called JSONP. See page 483 for more about Ajax security and JSONP. The server-side program needs to return this list of items formatted as an array: [ "lightbulb", "lighter", "lightning rod" ] Alternatively, the server can return data as an array of objects containing a label and a value as described on page 374. However, the data must use the JSON format discussed on page 477; that is, all property names and strings must get doublequotes like this: Chapter 10: Forms Revisited 377 PROVIDING HINTS WITH AUTOCOMPLETE var airports = [ { "label" : "Aberdeen Regional Airport, Aberdeen, South Dakota", "value" : "ABR" }, { "label" : "Abilene Regional Airport, Abilene, Texas", "value" : "ABI" }, { "label" : "Abraham Lincoln Capital Airport, Springfield, Illinois", "value" : "SPI" }, { "label" : "Adak Airport, Adak Island, Alaska", "value" : "ADK" }, { "label" : "Adirondack Regional Airport, Saranca Lake, New York", "value" : "SLK" } ]; Autocomplete Options There aren’t a lot of options for controlling how the Autocomplete widget works. The most important (and required) option is source, as discussed on pages 372-378. However, there are a couple of other options that can come in handy. As with other widget options, the autocomplete options should be passed as part of an object to the autocomplete() function. For example: $('#airport').autocomplete({ source : '/airportSearch.php', delay : 500, minLength : 2 }); Here are the most useful options: • source. The most important and only required option. Used to pass either an array or a URL of a server-side page. The array is either an array of values or an array of objects with label and value properties (page 374). If it’s a URL, the server-side program must return data formatted like an array (page 372). • delay. When using a server-side program as the source for the autocomplete data, jQuery UI sends a request to the server each time a visitor types into the autocomplete field. Multiple, fast requests can slow down the server and the autocomplete widget’s response. You can build in a slight delay, so your web server isn’t hit by so many requests from the widget, by setting this option to 378 JAVASCRIPT & JQUERY: THE MISSING MANUAL a number in milliseconds. For example, to wait half a second before sending a request, you can set the delay option like this: JQUERY UI FORM WIDGET TUTORIAL delay : 500 • minLength. This option specifies the minimum number of letters required before the autocomplete widget begins making suggestions. If the autocomplete data sources could be hundreds of thousands of records, you might want to set this minimum length to three characters. After all, if a visitor types a into the field, you could potentially get thousands of autocomplete suggestions from a large data source. NOTE You can find a complete list of options, plus additional features for the autocomplete widget, by visiting http://api.jqueryui.com/autocomplete/. jQuery UI Form Widget Tutorial In this tutorial, you’ll start with a basic flight reservation form: it contains text fields, radio buttons, and the <button> element (Figure 10-9, top). By adding jQuery UI to the page and applying jQuery UI’s form widgets to the page, we’ll get a more attractive, interactive, and functional form (Figure 10-9, bottom). NOTE See the note on page 12 for information on how to download the tutorial files. 1. In your text editor, open the file form.html in the chapter10 folder. This file already contains a link to all of the jQuery and jQuery UI files and the $(document).ready() function (page 160). The HTML for the form on this page looks like this: <form></form> <div> <label for="departure" class="label">Pick a departure date</label> <input type="text" id="departure" name="departure"> </div> <div> <label for="airport" class="label">Find an airport</label> <input type="text" id="airport" name="airport"> </div> <div> <label for="meal" class="label">Meal Options</label> <select name="meal" id="meal"> <option>No meal</option> <option>Vegan</option> <option>Gluten Free</option> Chapter 10: Forms Revisited 379 JQUERY UI FORM WIDGET TUTORIAL <option>Vegetarian</option> <option>Meat eater</option> </select> </div> <div id="bags"> <p class="label">Number of bags to check</p> <input type="radio" id="none" name="bags" checked="checked"> <label for="none">0</label> <input type="radio" id="one" name="bags"> <label for="one">1</label> <input type="radio" id="two" name="bags"> <label for="two">2</label> </div> <div id="seatTypes"> <p class="label">Type of seat you'd like</p> <input type="checkbox" id="aisle" name="aisle"> <label for="aisle">Aisle</label> <input type="checkbox" id="window" name="window"> <label for="window">Window</label> <input type="checkbox" id="exit" name="exit"> <label for="exit">Exit Row</label> <input type="checkbox" id="any" name="any"> <label for="any">Any seat</label> </div> <div> </div></button><button id="next">Continue reservation process</button> </div> The important form elements—the one’s you’ll apply jQuery UI to—are in bold. You’ll start by adding a data picker to the first field. For the next step, note that the <input> element has the ID departure. 2. Inside the $(document).ready() function, select the input element: $('#departure') Now you need to apply the Datepicker widget. 3. Type a period, followed by datepicker(); so the code now looks like this: $('#departure').datepicker(); That’s all that’s needed to add a pop-up calendar date picker to the page. However, if you save the file and view it in a web browser now, you’ll see that you can pick dates prior to today. Obviously, you can’t exactly get on a flight that happened last week, so you want to make sure you can’t make a reservation earlier than today’s date. 380 JAVASCRIPT & JQUERY: THE MISSING MANUAL JQUERY UI FORM WIDGET TUTORIAL FIGURE 10-9 jQuery UI can make a drab form, match the look and feel of your entire application. It can transform form controls like select menus, radio buttons, and check boxes (which are normally styled by your browser) into attractive and attention-grabbing user interface elements. 4. Click inside the datepicker() function and type a {. Press return twice and type } so that the code looks like this: $('#departure').datepicker({ }); The { } is an empty object literal, and you’ll specify options for the widget by adding properties inside it. First, set the minimum date for making a reservation. 5. On the blank line, inside the object literal type minDate : 0. The value for the minDate option indicates the number of days from today: 0 days from today is today; -7 days from today would be last week, and 7 days from today would be next week. You can also specify the maximum date allowable by the date picker. In this case, the airline doesn’t keep track of flights past 1 year from the current day, so you’ll prevent someone from selecting dates later than that. Chapter 10: Forms Revisited 381 JQUERY UI FORM WIDGET TUTORIAL 6. Type a comma at the end of the last line you typed, hit Return, and type maxDate : '+1y' so the code looks like this: $('#departure').datepicker({ minDate : 0, maxDate : '+1y' }); Both minDate and maxDate let you use a number to indicate a specific number of days, but you can also use a string value that includes a number and a letter to indicate a length of time: '+1y' means 1 year in the future, '-2w' means 2 weeks in the past, and '+1m +10d' means 1 month and 10 days in the future. 7. Save the page and preview it in a web browser. Click inside the “Pick a departure date” field. A pop-up calendar appears. Notice that you can’t select a date earlier than today’s date or more than one year from today’s date (if you want to see for yourself, click the forward arrow to go forward 12 months). Next, you’ll use the Autocomplete widget to make selecting an airport easier. But first, take a look at the data source you’re going to use. As mentioned on page 372, the autocomplete() function can accept either a JavaScript array of data, or data sent back from a server-side script running on a web server. To keep this example easier, you’ll use a small amount of data stored in a separate JavaScript file. 8. In a text editor, open the file airports.js . This is a simple JavaScript file containing an array assignment: it creates an array named airports filled with objects made up of two properties: label and value. The label will appear in the pop-up autocomplete menu, while the value will be written to the text field when the visitor selects an item from the list. Obviously this file is not a complete list, just a small amount of data to try this widget out. To access the data in this file, you’ll need to link it to the page. 9. In your text editor, open the form.html file. Below the last <!--<script type="text/javascript"> line— <script src ="../_js/jquery-ui.min.js"></script>-->—add one other script tag linking to the data file: <!--<script src="airports.js" type="text/javascript"></script>--> This line loads the external JavaScript file, and once it’s loaded, the JavaScript will run. In this case, the file just creates an array full of data, which you can then use in the autocomplete widget. 10. Add an empty line after the datepicker widget code you added earlier, and type: $('#airport').autocomplete({ source : 'airports.json'}); 382 JAVASCRIPT & JQUERY: THE MISSING MANUAL The text field for collecting an airport name has an ID of airport, so $('#airport') selects that field, and .autocomplete() applies the widget to that fields. JQUERY UI FORM WIDGET TUTORIAL 11. Save the page and preview it in a web browser. Click inside the “Find an airport” field and type Port . An autocomplete menu appears listing suggestions for airports that might be what you’re looking for. Notice that the widget matches items that have “Port” anywhere in their label: “La Guardia Airport,” for example. 12. Click the “Portland International Airport, Portland, OR” item. Notice that “PDX” appears in the text field. That’s because you supplied an array of objects with labels and values. The label that appears in the drop-down menu was “Portland International Airport, Portland, OR”, but the value added to the text field by the jQuery UI widget is “PDX,” the airport code. Next, you’ll change that drop-down menu into a thing of user interface beauty. 13. Return to your text editor and the form.html file. Add the following code after the last line of code you added in step 10: $('#meal').selectmenu(); You may have the urge to type more code, but that’s all you need to do to transform the select menu. If you save and preview the page, however, you’ll notice that the menu looks a bit weird. Actually, the first item on the menu isn’t listed completely! Unless the labels in your select menu are very short, you’ll need to set a width for this widget. 14. Inside the parentheses for the selectmenu() function, type { width : 200 } so the line of code looks like this: $('#meal').selectmenu( { width : 200 } ); The selectmenu widget’s width option (page 362) lets you set the width of the menu on the page. In this case, 200 means 200 pixels wide, though you can use other dimensions and types of measurement such as percentages or ems, as described on page 363. Save the page and check it out in a web browser. Who says programming’s hard? Next, you’ll convert the radio buttons and checkboxes into something that more closely resembles the rest of your form. 15. In your text editor, add the following two lines after the code you added in the last step: $('#bags').buttonset(); $('#seatTypes').buttonset(); The buttonset() function works for both radio buttons and checkboxes. The last step is to convert the <button> element into a jQuery UI button. Chapter 10: Forms Revisited 383 JQUERY UI FORM WIDGET TUTORIAL 16. Add one more line of code to your program: $('#next').button(); This converts the drab HTML button to something that looks a lot more like this form and matches the look of the radio buttons and checkboxes. You can also add jQuery UI icons to </button><button> elements, as described on page 367. Let’s do that next. 17. Inside the parentheses in the button() function add: { icons : { secondary : 'ui-icon-circle-arrow-e' } } The final JavaScript code for the page should look like this: $(document).ready(function() { $('#departure').datepicker({ minDate : 0, maxDate : '+1y' }); $('#airport').autocomplete({ source : airports}); $('#meal').selectmenu({width : 200}); $('#bags').buttonset(); $('#seatTypes').buttonset(); $('#next').button({ icons : { secondary : 'ui-icon-circle-arrow-e' } }); }); // end ready In just a few lines of code, you’ve completely transformed the look and functionality of a web form. 18. Save the page and preview it in a web browser. The page should look like the bottom image in Figure 10-9. If your page doesn’t look like this one, make sure the code you have matches the code in step 17. You can also check the JavaScript console (page 18) for any errors; however, be aware that jQuery often hides errors from the console, so it can make it harder to find errors in your jQuery code. You can find a completed version of this tutorial in the complete_form.html file in the chapter10 folder. 384 JAVASCRIPT & JQUERY: THE MISSING MANUAL CHAPTER Customizing the Look of jQuery UI 11 j Query UI widgets share a unified appearance—the date picker looks similar to tabbed panels, which looks similar to a dialog box, which looks similar to a tooltip. If you pieced together a bunch of separate jQuery plug-ins by different authors to get these same widgets, you’d spend a lot of time messing around with CSS to get the different plug-ins to look related. The consistent presentation throughout the different jQuery UI widgets means you can build a web application with a unified look without spending countless hours handcrafting CSS. However, what if you already have a look for your site and you want to make jQuery UI fit in with your existing design? For this situation, the jQuery UI team has put together lots of helpful advice as well as a cool online tool for even more assistance. This chapter covers how to override or modify existing jQuery UI styles and how to create new ones. Introducing ThemeRoller There are a lot of moving pieces in jQuery UI: creating all of the CSS to make each widget look great (and visually related) is a big task. Fortunately, the jQuery UI team put together an online tool called ThemeRoller. This tool lets you choose among 24 themes developed by designers for use with jQuery UI. It also provides tools to modify an existing theme, letting you pick fonts and colors that match the look of your site. To use ThemeRoller, visit http://jqueryui.com/themeroller/ (Figure 11-1). You can look at the collection of pre-designed themes by clicking the Gallery tab in the lefthand sidebar (circled). The main body of the page provides demonstrations of the different jQuery UI widgets: selecting a theme from the lefthand 385 INTRODUCING THEMEROLLER list immediately applies that theme to the widgets on the page, providing an instant preview of their design. FIGURE 11-1 jQuery UI’s ThemeRoller page lets you download a pre-created design for jQuery UI. You can choose from among 24 different designs. Click the Download button to download that theme. You can also use a pre-created theme as a jumping-off point for your own design explorations. To do so, click the Edit button below the theme, and ThemeRoller will load that theme’s design; you can then use the Roll Your Own options to tweak the colors and fonts. If you like the look of a theme in the gallery, click the Download button below its thumbnail preview in the sidebar at left to go to the jQuery Download Builder described on page 302. On that page, select the widgets, interactions, and effects you want to include and then click the Download button at the bottom of the page to download the files. NOTE Turn to page 302 for a complete description of how to download and organize the jQuery UI files to use in your site. If you want to add jQuery UI to a website you’ve already built, you can use ThemeRoller to create a custom theme that matches your site’s design. Click the Roll Your Own tab in the left sidebar (circled in Figure 11-2): this tool provides access to settings for fonts, colors, and other options. Settings are grouped into categories, which you can open 386 JAVASCRIPT & JQUERY: THE MISSING MANUAL or close by clicking the disclosure arrow to the left of the category name. Here’s a list of categories and their options: INTRODUCING THEMEROLLER • The Font Settings category lets you specify fonts, along with font size and weight. Type the name of the font(s) you want to use into the Family field. Fonts are usually specified as a group of three options: the font you want to load first, a fallback font, and then a fallback font type. If the first font isn’t available on your visitor’s computer, then the second font is used; if that font is unavailable, then a generic font type (serif, sans-serif, monospace, or fantasy) is picked. FIGURE 11-2 To open a category of settings, click the disclosure arrow next to the category name. Normally all of the categories are closed, but here they’re shown open and (to fit on this page), side by side. On the ThemeRoller site, the categories are actually stacked on top of each other. Use the same list of fonts that you’re currently using on your site. For example, if your site uses Helvetica Neue as its primary font, you could type the following: “Helvetica Neue”, Arial, sans-serif.” (When you use a font name with more than one word—Helvetica Neue, for example—you must place quotes around the font name.) jQuery UI applies the same font to all widgets and their parts, including the font used for tabs and panels. Otherwise, you can specify different fonts for different components, as described on page 392. NOTE If you’re using a web font that’s on your site or delivered by a service like TypeKit or Google Fonts—or any font that’s not on your computer—that font won’t display in the ThemeRoller preview. The font weight can be either “normal” or “bold.” Selecting “bold” doesn’t make all of the text inside jQuery UI widgets bold—it applies boldface to certain Chapter 11: Customizing the Look of jQuery UI 387 INTRODUCING THEMEROLLER elements like the text in tabs, buttons, select menus, and accordion headers. Other text is left as “normal.” The font size is the base font for all jQuery UI widgets. Text inside some widgets will be larger. For example, the header text in dialog boxes and the text in tooltips are larger than the text in other widgets. • Corner Radius. Most jQuery UI widgets have corners, and the corner radius setting lets you make these corners more or less rounded. Setting the value to 0 creates square corners; progressively higher values make the corners more rounded. Type different values in ThemeRoller until you find a look you like. • The Header/Toolbar category lets you set colors and patterns for the header in a date picker or dialog box, or the color in a progressbar or slider. This category provides six different settings: background color, background texture, background texture opacity, border color, text color, and icon color. These same six settings appear in most of the other categories as well, so it’s good to be familiar with them: • Background color. Click this box, and a color picker pops up. Use the color picker to select a hue (click on the outer wheel) and then a specific color (click inside the inner box). See Figure 11-3. • Background texture. jQuery UI can insert different patterns into the background of an element, such as horizontal or diagonal stripes. Click the text box to open a palette of textures. Click the one you like, or click the solid pattern in the upper-left corner to assign no texture. The texture is achieved by using a small image file in the background. See Figure 11-3. • Background texture opacity determines how strongly the pattern shows. Set the opacity to 0 and the pattern won’t show at all; a value of 10 adds a very subtle pattern; and values above 75% make the pattern really stand out. See Figure 11-3. • Border color sets the color of the border that appears around the header or toolbar. Click the box for this setting, and a color picker appears. If you don’t like having a border, just set this color to match the background color, and the border will blend into the background. (The same color picker that appears for all color settings, and it’s shown in Figure 11-3.) • Text color. Click this button to open a color picker to select a color for the text inside in the header or toolbar. • Icon color. Some widgets display icons. For example, the datepicker widget includes “Previous month” and “Next month” icons in its pop-up calendar. To set the colors of those icons, click the icon color box and use the color picker to select a color that fits in well with your site. NOTE For all color settings, you can also click inside the color setting box and type a hexadecimal color value, like #e64c4c. 388 JAVASCRIPT & JQUERY: THE MISSING MANUAL • Content. The Content category lets you set background, border, and text colors for the content areas of widgets. These include the panels in accordions and tabbed panel widgets, the menu items in the Selectmenu widget, and the calendar in the datepicker widget. The options are the same as for the Header/ Toolbar category—background color, background texture, background texture opacity, and border, text, and icon colors. INTRODUCING THEMEROLLER FIGURE 11-3 Many of jQuery UI’s ThemeRoller categories let you set the same three properties: background color, texture, and texture opacity. Get used to these controls and you’ll be able to style the backgrounds of each of jQuery UI’s widgets. • Clickable items. ThemeRoller provides three categories for clickable elements, which include any part of a widget that you click to make the widget work: accordion headers, tabs, buttons, dates on a Datepicker calendar, icons, buttons in a dialog box, and the select menu. The three categories map to the three states of a clickable item: the “default state” (this is how the clickable item looks when the page first loads), the “hover state” (when a visitor mouses over a clickable item), and the “active state.” The active state refers to a selected tab in a group of tabbed panels, the currently selected accordion header in an accordion widget, the selected date in a datepicker widget, or a selected button widget (for example, a selected radio button on a form). You have the same six styling options for each category of clickable items: the same ones you’ll use for the Header/Toolbar category as described on page 388: background color, background texture, background texture opacity, and border, text, and icon colors. • The Highlight and Error categories don’t actually format any of the widgets out of the box. However, they do create two CSS classes—.ui-state-highlight and .ui-state-error—that you can apply to widgets or to any element on a Chapter 11: Customizing the Look of jQuery UI 389 DOWNLOADING AND USING YOUR NEW THEME page. For example the dialog widget (page 305) lets you assign a class name to a dialog box. So if you wanted to open a special dialog box with the Highlight styling, you just pass the class name (without the period) to the dialog() function like this: $('#dialogDiv').dialog({ dialogClass : 'ui-state-highlight' }); Likewise, you could use the .ui-state-error style to format an element on a page that you want to stand out. For example, if someone incorrectly filled out a form field, you could select the label for that field and dynamically apply the error class to it: $('#userNameLabel').addClass('ui-state-error'); In this case, you’re not even using a jQuery widget—just the class style created by ThemeRoller. In fact, you can apply any jQuery UI class to other elements on the page. (You’ll read about that on page 392.) • Modal Screen for overlays. You can use the Dialog widget (page 305) to create modal dialog boxes. A modal dialog prevents the visitor from interacting with anything else on the page until the modal box is closed. It’s used for important messages and actions like “Are you sure you want to delete your Facebook profile forever?” jQuery UI darkens the rest of the screen when it opens a modal dialog by placing a semi-transparent “overlay” between the modal dialog and the rest of the page. You can control how that screen looks by changing the background color, texture, and opacity (the same settings used for the background of the Header/Toolbar category described on page 388). • Drop shadows. Ignore this category: it isn’t used for any of the jQuery UI widgets—even the Tooltip widget, which does have a drop shadow. Strange, but true. TIP As you use jQuery UI’s ThemeRoller to create a new jQuery UI design, the URL in the location bar of the browser changes: each change you make to the theme is replicated by a change in the URL. Why? Because ThemeRoller is cleverly creating a URL that will exactly duplicate your custom theme. This means you can bookmark that URL so it’s easy to return to ThemeRoller with all your theme’s settings in place. You can also copy the URL and email it to a friend or colleague so he can quickly replicate the theme you designed. Downloading and Using Your New Theme Once you’ve crafted a new jQuery UI theme, click the Download Theme button at left on the ThemeRoller page. This button takes you to the Download Builder page (Figure 11-2). If you want all of the widgets and functionality that jQuery UI offers, simply click the download button at the bottom of the page. However, if you want just a subset—just the Dialog, Datepicker, and Tabs—then uncheck the widgets, effects, and interactions you’re not interested in, and then click the Download button. 390 JAVASCRIPT & JQUERY: THE MISSING MANUAL Adding a New Theme to an Existing Website If you’re already using jQuery UI on a site, and just want to update the look with a new theme, all you need are new styles. You can go through the same process described in the previous section to create and download the new theme. This time, however, when you get to the Download Builder page (Figure 11-2) make sure you select all the same options—widgets, interactions, and effects—that you’re currently using. If you don’t, you’ll get either more or less CSS than you need. DOWNLOADING AND USING YOUR NEW THEME For example, if you’re using all of the jQuery UI widgets on your site, but turn off, say, dialog in the download builder, you won’t download the CSS required to style the dialog widget. Likewise, if you’re only using the dialog widget, but download the entire jQuery UI feature set, the new CSS you get will have way more CSS than you actually need, which means visitors will have to waste time downloading unneeded CSS. Once you download the new copy of jQuery UI, you’ll have files you don’t need (for example, if you’re already using jQuery UI, then you don’t need to replace the JavaScript files already in place). The only things you need to replace are the images folder and the CSS files: 1. Replace the old jQuery UI CSS file or files with the new theme. As mentioned on page 304, jQuery UI includes six CSS files. Most of these are duplicates in different formats. In a nutshell, the only one you really need is the jquery-ui.min.css file. This file contains all of the CSS jQuery needs in a smaller (minified) file. In general, you should use files that have .min in their name, because they’re the smallest. Place the new CSS file wherever you had the old one—in a css folder in the root of the site, for example. 2. Replace the old jQuery UI images folder with the new images folder. Different themes use different color icons, as well as different styles of background patterns. The icon and graphics for the new theme probably won’t match your old theme so you need to replace the old images. The jQuery UI images folder should be located wherever you placed the jQuery UI CSS file or files—this could be in a css folder in the root of your site, or a jquery-ui folder. Regardless, whichever folder you place the jQuery CSS file in, place the images folder there too. NOTE When downloading a new theme, check to make sure the version of jQuery UI hasn’t changed. jQuery UI changes frequently, so if you decide to update your theme, jQuery UI JavaScript might have changed. In this case, you should replace the CSS, images, and the jQuery UI JavaScript file (jquery-ui.min.js) in your site. More About the jQuery UI CSS Files When you download jQuery UI, you get six CSS files. These are actually two groups of three files: one group is a minified or compressed version ( jquery-ui.min.css, for example), and the other set contains easy-to-read CSS files (jquery-ui.css, for example). Chapter 11: Customizing the Look of jQuery UI 391 OVERRIDING JQUERY UI STYLES As mentioned earlier, the minified versions are the best for production (going onto your web server) because they download more quickly. The other files are great for opening in a text editor so you can see how the jQuery UI CSS is put together. The largest of the three files—jquery-ui.css—is just a combination of the two others ( jquery-ui.structure.css and jquery-ui.theme.css). The jQuery UI team split the full code into two separate files because there are certain CSS rules that apply to all widgets regardless of the font or colors used. These rules provide the “structure” of the jQuery UI widgets and interactions, including properties like the z-index of a dialog box, or position property of a tooltip. These rules are in a file named jqueryui-structure.css. But other styles change depending on the theme. For example, the font family used for widgets and the background color of an accordion header are specific to a particular theme. These styles are in the jquery-ui-theme.css file. You can open this file and see the specific properties that affect text and backgrounds. Accordingly, you should link to the jquery-ui.min.css file on your site’s pages, but use the jquery-ui-theme.css file as a way to investigate the style names and properties for the various jQuery UI widgets. Overriding jQuery UI Styles jQuery UI’s themes look good, but they may not always work for you. For example, when you use ThemeRoller (page 385) to set up the font-family, you get just one choice for dialog boxes, date pickers, tabbed panels, and so on. What if you want to use one font for the tabs in a panel, and another for the panel content? There are several different approaches to solving this problem, but there’s one thing you should definitely not do—edit the jQuery UI CSS files themselves. The jQuery UI CSS styles change when new versions of jQuery UI come out, so if you edit the jquery-ui.css file, and then need to update jQuery UI, you’ll have the difficult task of replicating every change you made to the original CSS file in the new jquery-ui.css file. Even if you don’t update jQuery UI, you won’t be able to use the ThemeRoller to create a new design without again painstakingly copying over your original changes to the new theme file. Instead, you should create new jQuery UI styles in a separate CSS file. This file could be a separate CSS file just for your updates to jQuery UI, or it could be the main style sheet for your site. It’s probably easiest to just add new styles to your site’s main style sheet. As you’ll read in a moment, there are a few techniques for overriding jQuery UI styles, but they all rely on using the CSS specificity concept. You’ll see more about that in a moment, but for now, keep this in mind: link the style sheet you’ll use to override jQuery UI’s styles after you load the jQuery UI style sheet: <link href="css/jquery-ui.min.css" rel="stylesheet"> <link href="css/site.css" rel="stylesheet"> 392 JAVASCRIPT & JQUERY: THE MISSING MANUAL By placing your site-specific style sheet after the jQuery UI style sheet, you can freely create a style with the exact same name as a style in the jQuery UI style sheet. The style you create will take precedence because it’s created after the same style in the jQuery UI style sheet. OVERRIDING JQUERY UI STYLES Understanding Specificity CSS styles often interact and conflict. You can have more than one style apply to the same page element and the browser determines which properties from which styles to apply. This is the cascade part of Cascading Style Sheets, and one really important concept in CSS is specificity. In CSS, the more specific rule always wins out. Here are some of the most important specificity rules: • ID selectors are more specific than classes, and classes are more specific than element selectors. Here’s an example: <p id="susan" class="person">Susan Jones: CSS Superstar</p> In this HTML, the <p> tag has an ID and a class. Now, suppose this is the CSS: #susan { color: green; font-size: 24px; } .person { color: blue; text-align: center; font-weight: bold; } p { color: orange; font-weight: normal; font-family: Arial, sans-serif; } All three styles apply to the paragraph, and all three have a color property. But, because ID selectors are more specific, this paragraph will use the color green, as the ID selector overrides the other two styles. However, when there is no conflict—for example, the text-align property in the .person class style—that property applies no matter which style it comes from. In this example, the paragraph’s text will be 24px in size and have a green color (from the #susan selector), be bold and centered (from the .person selector), and use the font Arial (from the p selector). Because jQuery UI uses class styles to apply formatting, knowing how specificity works with different types of selectors is important. • Rules that are defined later win. If the same rule name appears in two different style sheets (or even in the same style sheet), the one that’s defined last wins. That’s why you should link the jQuery UI style sheet first. You can add Chapter 11: Customizing the Look of jQuery UI 393 OVERRIDING JQUERY UI STYLES new styles with the same name as jQuery UI classes in a second style sheet and override those from jQuery UI. For example, in the jQuery UI style sheet, you’ll find a style like this: /* in jquery-ui stylesheet */ .ui-widget-content a { color: #222222; } If you link your site-specific style sheet after the jQuery UI style sheet, you could add this style to that site-specific style sheet and completely override the jQuery UI styling for this element: /* in the site-specific stylesheet */ .ui-widget-content a { color: #FF0; } • Specificity adds up. Using descendant selectors is a powerful way to create very specific styles. A browser adds up all of the selectors listed in a descendant selector to come up with a sum total for that rules specificity. A simple way to calculate this is to consider ID selectors as being worth 100 points, class selectors worth 10 points, and element selectors worth 1. For example, a style with the selector #main a will override a style named .ui-state-default a because the first is worth 101 points (one ID and one element) and the second just 11 points (one class and one element). In other words, you can override a jQuery UI rule by using a descendant selector that provides more points. • In dire times, use the !important rule. CSS includes a sort of “nuclear option,” called the !important rule. If you add !important after the value in a CSS declaration that value overrides any other style no matter how specific. For example, say in the CSS listed in the first bullet point above, you had another p style like this: p { color: orange !important; font-weight: normal !important; font-family: Arial, sans-serif !important; } Because each of the properties in this style has the !important rule, those properties override the values in the more specific #susan and .person rules. Using !important should really just be used as a last resort. If you use it really frequently, you’ll end up with styles full of !important rules, and it will be difficult for you to then sort out the specificity among your styles. (If every property in every style had an !important rule, then the normal specificity rules would apply: that is, IDs trump classes, which trump element selectors.) 394 JAVASCRIPT & JQUERY: THE MISSING MANUAL How jQuery UI Styles Widgets jQuery UI uses a modular approach to styling its widgets: instead of creating a single .ui-dialog style with all of the styling for jQuery dialog boxes, the look of a widget is built up from multiple class styles. For example, there’s a .ui-widget style that’s applied to all the widgets. It contains some very basic styling: OVERRIDING JQUERY UI STYLES .ui-widget { font-family: Verdana,Arial,sans-serif; font-size: 1.1em; } Because this class is applied to all widgets, they all share the same basic font and font size. But for the dialog widget, jQuery applies many other classes as well. For example, for the dialog box alone, you’ll find these classes applied to the outer container: class="ui-dialog ui-widget ui-widget-content ui-corner-all ui-front ui-draggable ui-resizable" Each of those classes contributes one small aspect of the overall look of the dialog box. By combining multiple classes like this, jQuery UI is able to re-use them to build up the look of different widgets. For example, here are the classes used on the outer container for a jQuery UI menu (page 343): class="ui-menu ui-widget ui-widget-content" Notice that two of the classes—ui-widget and ui-widget-content—are also used in the dialog box. These two styles include some basic formatting shared by these two widgets. As you’ve seen, it’s really easy to turn a simple </p><div> element into a complex dialog box (page 305), or a nested list into a drop-down menu (page 343). Behind the scenes, jQuery UI takes your simple HTML and adds layers of divs, spans, and other HTML objects to create the final onscreen appearance. As a result, you can’t tell how the styling occurs by looking at your HTML or even the jQuery UI style sheets. You have to dig into the rendered HTML (that is, the HTML, after jQuery UI has done its fancy magic on it) to see how jQuery UI formats its widgets. The best way to analyze how jQuery UI applies classes to widgets is to use your browser’s built-in inspection tools. Most browsers have a way to see the rendered HTML. In Chrome, for example, right-click a jQuery UI widget and choose Inspect Element. The console opens at the bottom of the browser window and displays the rendered HTML in the Elements tag (Figure 11-4). Chapter 11: Customizing the Look of jQuery UI 395 OVERRIDING JQUERY UI STYLES FIGURE 11-4 Once the Elements tab is open in the console, you can place your mouse over the HTML you’re curious about. The elements in the browser window that match the HTML are highlighted as you mouse over them. At a glance, you can match up the HTML code with its visual representation in the browser. Clicking the magnifying glass icon (circled in Figure 11-4) activates the inspection tool. With the magnifying glass selected, you can clik any element on the page and the corresponding HTML is selected in the Elements tab. This is a great way to identify the header in a dialog box, for example, and see which classes are applied to it. Once you’ve identified the classes, you can create styles of the same name in your own style sheet. For example, using the inspector in Chrome, you can see that the HTML used to create the title of a dialog box includes a class named .ui-dialogtitle (Figure 11-5). To change the headline in dialog boxes to red, you can add a style to your site’s style sheet like this: .ui-dialog-title { color: red; } 396 JAVASCRIPT & JQUERY: THE MISSING MANUAL OVERRIDING JQUERY UI STYLES FIGURE 11-5 Using the Inspector tool (the magnifying glass), you can quickly identify the rendered HTML associated with elements in the browser window. Here’s the HTML that jQuery UI produces to create the title for a dialog box. Chapter 11: Customizing the Look of jQuery UI 397 CHAPTER jQuery UI Interactions and Effects 12 j Query UI has more to offer than just user interface widgets. It also provides a handful of useful features for adding interactivity to your web pages and web applications. These jQuery UI interactions provide the tools to let visitors move elements on a page. For example, some widgets are draggable and droppable, which means visitors can drag an element and drop it onto another element—think dragging a file to the trash, or dragging a product to a shopping cart. You can also make lists of sortable items that the user can rearrange by simply dragging an item to a new position in the list—think to-do lists or music playlists. In addition, jQuery UI includes a suite of effects that you can use to add visual flair to your site with high-quality animations. For example, you can grab a visitor’s attention by making an element’s background color flash, make a page element bounce, shake, scale, or explode. You’ll learn about effects on page 438. The Draggable Widget Dragging is second nature when you’re on a computer—dragging files into folders or the trash, dragging windows to make room for more windows, and so on. These interactions are natural for a generation who has grown up with personal computers and mice. jQuery UI brings this same type of interaction to web pages with its draggable widget and its companion, the droppable widget (discussed on page 412). The Draggable widget lets you make any page element movable. You’ve already seen it in use in jQuery UI’s dialog widget (page 305): jQuery UI’s dialog boxes pop onto the screen but can be freely dragged to another spot. You can use the draggable widget in conjunction with the droppable widget to create an interactive shopping 399 THE DRAGGABLE WIDGET cart. Shoppers drag images of products onto a shopping cart on the page, and those items are added to the cart. Adding the Draggable Widget to a Web Page You can turn anything on a page into a draggable element. Of course, it should make sense that a visitor would move that element. For example, making paragraphs of text movable won’t make a page more readable and won’t benefit your visitors. But making pop-up dialog boxes movable makes sense, and movable game pieces are a must for any web-based checkers game. Getting started with the draggable widget is easy: 1. Follow the steps on page 304 to attach the CSS and JavaScript files. Remember that jQuery UI has its own CSS and JavaScript files, and that the jQuery UI JavaScript file should be linked to after the jQuery JavaScript file. 2. Add jQuery’s $(document).ready() function to your page or to another external JavaScript file: $(document).ready(function() { }); // end ready As discussed on page 160, this step is necessary only if you’re putting your JavaScript code in the page’s , before the majority of the HTML. Some programmers put their JavaScript code at the bottom of the page, before the closing tag; in that case, you can skip the $(document).ready() function. 3. Use jQuery to select a page element and apply the draggable widget to it: $(document).ready(function() { $('#dialog').draggable(); }); // end ready In this example, you’re selecting a single item using an ID selector. However, if you want to make a bunch of elements on the page draggable, you can apply a class to each of their HTML tags—<div class="draggable">, for example—and then use a class selector to apply the draggable function to all of those tags in one step: $('.draggable').draggable(); 4. Save your files and preview them in a browser. That’s all there is to it. However, you’ll probably want to customize the dragging experience. Fortunately, jQuery UI provides many different options for configuring this widget. You’ll learn about those on page 402. 400 JAVASCRIPT & JQUERY: THE MISSING MANUAL Draggable Mini-Tutorial Time to take this widget out for a spin, and see how easy it is to make any element on a page draggable. NOTE THE DRAGGABLE WIDGET See the note on page 12 for information on how to download the tutorial files. 1. In a text editor, open the file draggable.html in the chapter12 folder. This file already contains a link to the required jQuery UI and jQuery files as well as the $(document).ready() function (page 160). Look at the HTML and find a <div> with an ID of note and a little bit of content. You’ll turn this into a draggable item. 2. In the empty line inside the $(document).ready() function add the bolded line below: $(document).ready(function() { $('#note').draggable(); }); // end ready This selects the <div> and makes it movable. 3. Save the page and preview it in a web browser (Figure 12-1). Click anywhere in the div with the headline “You can drag me” and drag it around the screen. There are many ways to configure this widget, which you’ll look at next. NOTE You’ll find the finished version of this tutorial in the complete_draggable.html file. FIGURE 12-1 In just one line of code, you can turn a static <div> into a draggable on-page box. The Draggable widget is also used by the jQuery UI Dialog widget (page 305). Chapter 12: jQuery UI Interactions and Effects 401 THE DRAGGABLE WIDGET Draggable Widget Options jQuery UI’s draggable widget is very powerful and includes many options. You can control a dragged element’s direction and distance, how it behaves when you drag it, and even what portion of the element you can grab. As with other jQuery UI widgets, you can set options by passing an object to the draggable() function. For example, to change the cursor to a pointing finger and to set the <h2> element inside the dragged item as the “handle” that a visitor must grab, you’d pass an object with those two options set like this: $('#controls').draggable({ cursor : 'pointer', handle : 'h2' }); Here are the most common options: • axis. You can limit the movement of a draggable element to just left and right or up and down using the axis property. For example, say you wanted to drag an item along a timeline. The dragged item needed to stay positioned along that line, so you wouldn’t want someone to drag the element to the bottom of the page off the line. Use either 'x' (to constrain the dragged item to just left and right movement) or 'y' (to make sure the dragged item can only be moved up and down the page): axis : 'x' • cancel. This option lets you prevent dragging when a specific element is clicked on. For example, say you created an announcement box that visitors could drag around the screen. The announcement has a headline, but also several paragraphs of text that includes important information like a street address and phone number. Normally, if a visitor tried to select the street address (to copy and paste into Google Maps, for instance), she’d end up dragging the announcement around the window instead. You could turn off the dragging action of those paragraphs, by setting the cancel option: cancel : 'p' Now, if someone clicked on a paragraph inside the announcement, she wouldn’t trigger the dragging action and could freely select and copy text. The handle option discussed on page 405, can also let visitors select content within a draggable item. • connectToSortable. Lets you specify a collection of sortable items that the dragged item can be added to. jQuery UI offers a sortable interaction which lets you group a collection of items that can be sorted, such as a To-do list (you’ll learn about sortable items on page 426). To use this option, just specify an ID for an element you’ve already turned into a sortable group (as described on page 426): connectToSortable : 402 '#toDoList' JAVASCRIPT & JQUERY: THE MISSING MANUAL • containment. You can prevent a visitor from dragging an element outside a container element. For example, say you create a “Refrigerator magnet” activity where a visitor can drag words around to form a sentence. You can add a bunch of small, draggable divs with words in them and include an area of the page where the visitor can construct the sentence. You want to make sure that he doesn’t drag words all over the place, like into the navigation bar, headline, or footer. The containment options let you limit the interaction to a smaller area of the page. It accepts several possible values: THE DRAGGABLE WIDGET • A selector. If you provide a selector name, then jQuery UI will keep the draggable item confined to the boundaries of that element. For example, if you had a <div> on the page with an ID of refrigerator, you could keep the draggable element inside that div by setting the containment option like this: containment : '#refrigerator' • parent, document, or window. To keep the draggable item contained inside its parent element, use parent as the value. For example, if the draggable item is a <div> inside another <div> and you want to limit the dragging to within that outer div, use parent like this: containment : 'parent' The document and window values are nearly the same, except document keeps the entire draggable area contained within the document area and window lets you drag the element partly outside the window. • An array of coordinates. Lastly, you can supply an array of coordinates that represent the top-left and bottom-right points of a containing box. You provide pixel values that are in relation to the top-left of the browser window. For example, say you wanted to limit dragging to an area that starts 50 pixels from the left and 100 pixels from the top and ends 500 pixels from the left and 600 pixels from the top. You’d assign those values like this: containment : [50, 100, 500, 600] Because using coordinates like this requires precise values, it’s not very good for a fluid design. You’re better off using a containing element and specifying a selector. • cursor. When an element is dragged, you can change the appearance of the cursor. Normally, the cursor will look like either an arrow (if you click on an empty space in an element) or a text selection bar (if you click on text in a headline, for example). However, you can tell jQuery UI to use a different cursor as the visitor drags an element by setting the cursor option with a valid CSS cursor value. You can find a list of values at https://developer.mozilla.org/en-US/docs/ Web/CSS/cursor, but common cursors used when dragging include pointer, crosshair, and default (which is an arrow): cursor : 'pointer' Chapter 12: jQuery UI Interactions and Effects 403 THE DRAGGABLE WIDGET • cursorAt. You can control where the cursor appears as the visitor drags the element. Usually the cursor remains wherever the visitor first grabs the element. For example, if you grab a draggable div at the bottom, the cursor will remain at the bottom of the div as you drag it around the screen. However, maybe you want the cursor to appear in a specific spot—maybe a visual handle that you’ve added to the draggable element. To do so, provide an object for the cursorAt option. The object can contain values using left, right, top, and bottom properties. For example, to position the cursor at the top-left of an element as the visitor drags it, set the left and top properties like this: cursorAt : { left : 5, top : 5 } You can’t set both left and right because they’re different locations on the same axis; and you can’t set both top and bottom for the same reason. However, you can use one value from each axis (left or right and top or bottom). Likewise, you can set just one value if you prefer. For example, if you only care that the cursor appears inside a bar at the top of a draggable element, you can set just the top value. The horizontal value will be set to the horizontal position from which the visitor grabbed the element in the first place: cursorAt : { top : 5 } • disabled. Determines whether the item is draggable. If this property is set to true, then you can’t drag the item. You’re probably thinking that if you wanted to not make an element draggable, you’d just avoid the draggable() function. True, you probably wouldn’t use the disabled option when you first apply the draggable widget to an element. However, it can come in handy after someone has dragged the item. For example, you might want to let a visitor drag an item into a shopping cart, but not let them drag it out. In this case, you can apply this option after the dragging operation is complete (you’ll see an example of this on page 418). • grid. Normally, when you drag an element it moves freely across the window. However, you might want to force an element to move a specific number of spaces horizontally and vertically when dragged. For example, imagine an online checkers game. You have a grid of 8 squares by 8 squares. The checker pieces can be dragged around the border, but it would look sloppy if you could just drag those pieces anywhere. You want the pieces to move the same distance as a square on the board. jQuery UI lets you force an element to move in specific horizontal and vertical increments. The grid option takes an array of two numbers. The first number is the horizontal increment, and the second is the vertical increment. For example, say you wanted an element to move in increments of 50 pixels when dragged 404 JAVASCRIPT & JQUERY: THE MISSING MANUAL left or right. You also wanted the element to move in 100 pixel increments when dragged up or down. You can set the grid option to do that like this: THE DRAGGABLE WIDGET grid : [50, 100] • handle. You can limit the area that a visitor clicks to drag an element. Normally, you can click anywhere inside a draggable element to drag it. However, you might want to limit that to just one area such as a headline or a visual drag bar in the element. Use the handle option to identify a selector within the draggable item that will act as the handle for dragging. For example, you can make it so you can only drag an element by clicking its headline—an <h2> element, for instance—like this: handle : 'h2' • helper. You may not want the user to move the actual draggable element on the page. For example, say you create a shopping cart page. Pictures of products appear on the page and visitors can add items to the cart by dragging a picture of a product onto a shopping cart icon. In this case, you don’t want the shopper to actually move the product photo into the cart—that would move the picture on the page. You’d rather have the shopper just drag a copy of the picture while leaving the original photo unmoved. You can do this by setting the helper option to 'clone' like this: helper : 'clone' A more complex option is to pass the helper option a function that generates the HTML that jQuery UI should display as the user drags her mouse. For example, to display a generic helper div (instead of dragging the actual HTML element), you could set the helper like this: helper: function( event ) { return $( "<div class="ui-widget-header">I'm a custom helper</div>" ); } Whatever you provide for the return statement is what jQuery UI will display under the user’s mouse cursor. Note that you must return a jQuery object, so use the $() function to create the helper. A plain string of HTML won’t work. • opacity. When an element is dragged, you can make its opacity change. For example, you can fade the element to 50% opacity to give it a ghost-like appearance. This technique is a popular way to indicate that you’re moving an item from one place to another. Use a value between 0 (completely invisible) to 1 (completely opaque). This works just like the CSS opacity property. For example, to make the dragged element appear 50% transparent, set the opacity value to 0.5: opacity : 0.5 • revert. This option dictates whether the dragged item returns to its original position after the user stops dragging it. Normally, this is set to false, which Chapter 12: jQuery UI Interactions and Effects 405 THE DRAGGABLE WIDGET means that when you drag the element and let go, it stays where you left it. For draggable windows or dialog boxes, that’s generally a good approach: you drag the window out of the way of something else on the page. However, there are times when you want to make the dragged element return to its starting position. For example, if you’re using the droppable widget (page 412), you might want a dragged item that’s not dropped in a specific spot to return to where it came from. For example, say you created an app for organizing images. You can drag thumbnails of the images into different folders on the page, or into a trashcan icon. However, a user might drag an image up into a headline on the page, or down into the footer, and not into one of the intended folders or the trashcan. In that case, you’d want the image to move back to where it was on the page and not sit there obscuring the headline or footer. The revert option accepts several different values: true makes the dragged item always return back to its starting point (great for your next prank website); 'invalid' makes the dragged item return only if it’s not dropped on a valid droppable item (page 412). In the case of the photo-organizing app mentioned above, you’d use the invalid option like this: revert : 'invalid' Lastly, you can pass a function to this option. If the function returns true, then the element reverts back to its original position. You could use a function in a JavaScript checkers game, for example: if a player moves his piece and drops it on another square on the board, a function could check if the move was invalid (if that square is already occupied by another piece, or if the piece moved farther than allowed, for instance). In that case, the function would return the value true, and jQuery UI would move the piece back to its original position. revert : function() { // do some kind of test in this function and return either // true to make the element revert to its original position // or false if the element can stay where the user dropped it } • revertDuration. When jQuery UI reverts a dropped element (moves it backs to its original position), it animates this movement. The default value is 500 milliseconds or half a second. It looks really cool, but you can make the animation happen faster (a number less than 500) or slower (a number greater than 500). To do that, set the revertDuration option, which accepts a number indicating the number of milliseconds the animation should take. For example, for a quarter of a second animation (250 milliseconds) you’d set the revertDuration option like this: revertDuration : 250 • scope. The scope option lets you group sets of draggable and droppable items. For example, say your page has a calendar. Users can drag an event from one 406 JAVASCRIPT & JQUERY: THE MISSING MANUAL day on the calendar to another. All the draggable events in the calendar belong to the calendar, so you can set the draggable item’s scope to calendar like this: scope : THE DRAGGABLE WIDGET 'calendar' The string 'calendar' here doesn’t refer to a selector or element on the page. It’s just a name used to group draggable and droppable items together. You could use any term you want; just make sure you use the same name for the scope option on the droppable item (page 412). You need to set the scope option only if there’s a chance that a page has different types of draggable and droppable items. For example, if you have a jigsaw puzzle on the same page as the calendar, you wouldn’t want people dragging events from the calendar onto the puzzle and puzzle pieces onto the calendar. By specifying different scopes for each group, you can control which draggable items can be dropped on what other elements (see page 412 for more on the droppable widget). NOTE You can try out these options on the tutorial file—draggable.html—you programmed on page 401. If you didn’t complete that tutorial, open the complete_draggable.html file and add some of these options to the draggable() function in that file. • snap. You can make a draggable item snap to another page element or another draggable item. For example, say you create a jigsaw puzzle game. A dozen square fragments of a photo need to be re-assembled to create the original photo. You can make one puzzle piece snap to another piece by setting this option. Use one of two possible values for this option: • true tells jQuery UI to make the dragged item snap to any other draggable item on the page. This is good in the case of a jigsaw puzzle because you’ll have lots of individual tiles. • A selector name. The name of any selector on the page. For example, if you want the dragged item to snap to a div with the ID of photoholder, you could do this: snap : '#photoholder' How the item snaps to another element is controlled by the snapMode and snapTolerance options, discussed next. • snapMode. This option only works if you’ve also set the snap option. This option takes one of three keywords: inner, outer, or both. If you want the dragged element to snap only when its inside the element, use inner, which makes the dragged element snap to any of the inner edges of the element specified by the snap option. Use outer when you want the element to snap to the outside edge of an item. This option is ideal for things like the jigsaw puzzle because you want the pieces to snap next to each other. Chapter 12: jQuery UI Interactions and Effects 407 THE DRAGGABLE WIDGET Finally, you can make the dragged item snap to either the outer or inner edges using the both option: snapMode : 'both' • snapTolerance determines how close the dragged item should be before it snaps to an element. The larger the number, the farther away the dragged item can be before it tries to snap to an element. Specify a pixel value for this option: snapTolerance : 30 • zIndex. This option lets you set a z-index for the dragged element. The CSS z-index property determines the stacking order of elements on the page. An element with a higher z-index will appear on top of any page elements it overlaps. This property comes in handy when you want to make sure that, as the visitor drags an item around the page, that item appears on top of surrounding content. (You’ll see an example of this option in the tutorial on page 423.) zIndex : 100 NOTE You’ll find even more options for the draggable widget at http://api.jqueryui.com/draggable/. See Figure 12-2. Draggable Widget Events The droppable widget supports several different events, each of which is triggered at a different moment of the dragging process. You add a function to an event to make your program do something in response to the item being dragged. Say you’ve created a game that requires a player to quickly drag an item to a target. The faster he can drag the item, the higher the score. You could check the time when the player first starts to drag the item, then check the time when the player stops. Three events deal with the various points in the dragging process. THE CREATE EVENT This event fires whenever you use the draggable() function to create a new draggable item. You could use this event to pop up a dialog box with the instructions “Drag this product to your shopping cart.” It only runs once, when the draggable widget is created. You use this event by passing a create property with a function to the draggable method like this: $('.product').draggable({ create : function (event){ // programming here } }); 408 JAVASCRIPT & JQUERY: THE MISSING MANUAL THE DRAGGABLE WIDGET FIGURE 12-2 jQuery UI’s documentation is extensive. The page dedicated to the draggable widget lists multiple options, methods, and events that you can tap into to customize how this widget works. THE START EVENT This event triggers as soon as a user begins dragging an element. You assign this event as a property of the draggable widget’s options object. The name of the event—start—is the property name, and the value should be a function that runs when the visitor starts dragging the item. For example, say you have a <div> tag with an ID of raceCar. You turn that div into a draggable item, and assign it a start event like this: $('#raceCar).draggable({ start : function (event, ui) { // programming goes here } }); Chapter 12: jQuery UI Interactions and Effects 409 THE DRAGGABLE WIDGET The function assigned to the start event has two parameters—event and ui. The event parameter is a jQuery event object and provides details about which element is receiving the event, the screen coordinates of the mouse, and other information. (You can read about the event object and how to use it on page 164.) The ui parameter is an object with three properties: • The ui.helper property is a jQuery object containing a reference to the item that’s visibly dragged across the screen. This is usually the same as the element to which you applied the draggable() method. However, that’s not always the case. If you set the draggable widget’s helper option to 'clone' or passed it a function to generate the helper HTML (page 405), ui.helper refers to an element other than the original draggable element: either a copy of that element or a jQuery object created as a helper (as described on page 405). This arrangement is helpful in a shopping cart, for example, when dragging a product from one place on the page to the shopping cart will disturb the page’s layout. Instead, the shopper should drag a copy of the product into the cart. Use the ui.helper property whenever you want to perform an action on the item that’s visibly dragged across the page. For example, say you wanted to make an item double in size when the user starts to drag it. You could set a CSS property on the ui.helper object like this: $('#photo').draggable({ start : function (event, ui) { ui.helper.css('transform', 'scale(2)'); } }); This uses jQuery’s css() method (page 134) and sets the CSS transform property to scale the element by 2 (doubling it size). You could also use jQuery’s addClass() method to add a class to the item as the user starts dragging it—a style that highlights the item, for example. Then remove the class using removeClass() when the visitor stops dragging the item (see the stop event on page 411). NOTE To learn more about CSS transforms, visit https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/ Using_CSS_transforms. • ui.position provides the x and y position of the top-left corner of the helper item (the item that is visibly dragged across the screen). This is the element’s CSS position value, and it can be affected by the position of its parent element (or any other positioned ancestor). For example, if you have a draggable item inside a <div>, and that <div> is absolutely positioned on the page, the draggable element’s left and top position values will be in relation to the left and top corner of the positioned ancestor. The ui.position property is a JavaScript object composed of two properties top and left. The top property is the element’s top position as measured in 410 JAVASCRIPT & JQUERY: THE MISSING MANUAL a number of pixels from the top of its nearest positioned ancestor (that is, a tag with either absolute or relative positioning that wraps around the dragged element). The left property is the helper’s position relative to the left edge of the nearest positioned ancestor. Accessing this property can be useful for determining where the helper is when the visitor stops dragging (or while he’s dragging the element) (see the drag and stop events next). THE DRAGGABLE WIDGET You can access those values like this: ui.position.top and ui.position.left. • ui.offset also provides an object with two properties top and left. The position is calculated relative to the top left of the browser window. ui.position and ui.offset will be the same if the dragged element is not inside any other elements that have CSS position property of absolute or relative. The ui.offset.top property identifies how far the top of the helper element is from the top of the window. The ui.offset.left property identifies how many pixels the draggable item is placed from the left side of the browser window. • ui.originalPosition contains the same two properties—top and left—as ui.position and ui.offset. However, ui.originalPosition indicates the draggable element’s starting position—the spot the element was in just before the user started dragging it. Like the ui.position property, ui.originalPosition is based on any positioned ancestors. THE DRAG EVENT Draggable items also fire off a drag event as they are dragged around the screen. You can create a function that runs repeatedly while the object is being dragged. You could use this event to leave a trail of sparkles as the dragged object is moved across the window, for example. Because this event fires off numerous times while dragging an element, try to limit the amount of work the function does. If you perform lots of complicated operations in response to the drag event, the browser may slow to a crawl. The drag event function accepts the same two parameters as the start event described on page 409—event and ui. Say you wanted to display the current position of a dragged item as it’s dragged across the screen. Assume the page has a couple of <span> tags with the ID of left and top to display these values. You could continuously update the values as the element is being dragged like this: $('#raceCar').draggable({ drag : function (event, ui) { $('#left').text(ui.position.left); $('#top').text(ui.position.top); } }); THE STOP EVENT The Draggable widget’s stop event works just like the start event, except it’s triggered when the user stops dragging the item and releases the mouse button. This Chapter 12: jQuery UI Interactions and Effects 411 THE DROPPABLE WIDGET doesn’t necessarily mean that the user dropped the item on a droppable target (like the ones discussed in the next section). It doesn’t even mean that the user has completely finished dragging the element. For example, a user could click a draggable element and begin moving it (the start event fires); keep moving it around the page (the drag event fires continuously); then stop dragging (the stop event fires); then click and drag the same element again repeating all of the same events. You use the stop event following the same structure as the start event. For example, say you used the code above to make the draggable element scale up to twice its size while being dragged. You could return the element to normal size when the user stops dragging it using this code: $('#photo').draggable({ stop : function (event, ui) { ui.helper.css('transform', 'scale(1)'); } }); The Droppable Widget The Draggable widget, by itself, is useful for dialog boxes or other page elements that you’d move around the screen (like tool palettes, for example). However, when you add the droppable widget to the mix, you can build highly interactive applications, where dragging one item onto another item can make something else happen. For example, a photo sharing application might let a user drag a thumbnail image to a trashcan to delete that photo from the site. A language-learning website could test students by having them drag a word onto a corresponding picture to show their mastery of vocabulary. Using the Droppable Widget Droppable widgets aren’t useful without draggable widgets. A droppable widget acts like a “drop zone” for draggable items. When an item is dropped on it, a droppable widget can also trigger additional programming. You can turn anything on a page into a droppable element. Of course, it should make sense that a visitor would drag something on to it: for example, icons of shopping carts and trashcans are visual metaphors that clearly indicate that items can be dropped into them. But you can also turn divs into droppable widgets as long as you clearly indicate to the visitor what they can drag and where they can drag it to. Using the droppable widget is very easy: 1. Follow the steps on page 304 to attach the CSS and JavaScript files. Remember that jQuery UI has its own CSS and JavaScript files, and that the jQuery UI JavaScript file should be linked to after the jQuery JavaScript file. 412 JAVASCRIPT & JQUERY: THE MISSING MANUAL 2. Add jQuery’s $(document).ready() function to your page or to another external JavaScript file: THE DROPPABLE WIDGET $(document).ready(function() { }); // end ready As discussed on page 160, this step is only necessary if you’re putting your JavaScript code in the page’s , before the majority of your HTML. Some programmers put their JavaScript code at the bottom of the page, before the closing tag; in that case, you can skip the $(document).ready() function. Droppable widgets don’t make sense without something you can drag into them, so always add at least one draggable item to the page. 3. Use jQuery to select one or more page elements and apply the Draggable widget to it: $(document).ready(function() { $('.product').draggable(); }); // end ready In this example, you have a catalog page with a bunch of products on it. Each product photo has the class product applied to it, so this code will make each of those photos draggable. 4. Use jQuery to select a drop zone and make it droppable: $(document).ready(function() { $('.product').draggable(); $('#cart').droppable(); }); // end ready The item on the page with an ID of cart is now a drop zone. But this is just the start. You have to set various options of the droppable element in order to make something happen: such as calculate a sales total each time a product is added to the cart. You do this by passing an object containing options and functions to the droppable() function. 5. Add options to the droppable() function: $(document).ready(function() { $('.product').draggable(); $('#cart').droppable({ activeClass : 'highlight', drop : function (event,ui) { alert('Product added'); } }); }); // end ready Chapter 12: jQuery UI Interactions and Effects 413 THE DROPPABLE WIDGET You’ll learn about the various options for this widget next, but as a sneak preview, you’ll take a look at what the code above does. First, the activeClass option tells jQuery UI to add a class named highlight to the drop zone element, which you use to apply a CSS rule to the droppable element. The CSS can visually identify the drop zone by adding a bold background color to the drop zone, or outlining it with a bright red border. The second option, drop, is an event handler. It lets you run a function when an item is dropped onto the drop zone. In this case, an alert box pops open with a message. Droppable Widget Options The droppable widget doesn’t provide as many options as the draggable widget (the droppable widget’s main role is to receive items, and, most importantly, run functions when that happens): • accept. Dictates which draggable items can be added to the droppable widget. You can assign either a selector or a function. The selector indicates the selector for the draggable item. For example, if you had a bunch of images all with the class photo on them, and wanted to be able to drop them on a droppable item, you’d set the option like this: accept : '.photo' • activeClass. You can highlight a droppable element when any acceptable draggable element is being dragged. For example, say you created a filesystem app that let users view files on the server, move them to different folders, rename the files, and so on. You could also drag a file to the trash to delete it. The trashcan would be a droppable widget, and a file a draggable widget. When a visitor started to drag a file, you could apply a class that highlights the trashcan in some way (for example, changes the background image to display a trashcan with an open lid, ready for the file). Just assign a class name (without a period) to this property, and jQuery UI will add the class to the droppable item, when an acceptable draggable item is dragged: activeClass : 'highlight' • disabled. Determines whether the item is an active drop zone. If this property is set to true, then you can’t drop anything on the element. You can use this property after creating the drop zone as a way to turn off the ability. For example, say you had a drop zone but you only wanted users to be able to drop 5 items into it. Once the five items were in place, you would then turn off the drop zone, so users could no longer drop anything into it (you can use the drop event described on page 416 to trigger a function that disables the drop zone): $('#dropZone').droppable({ disabled : true }); 414 JAVASCRIPT & JQUERY: THE MISSING MANUAL You’re probably thinking that if you wanted to turn an element into a drop zone, then just avoid the droppable() function altogether. True, you probably wouldn’t use the disabled option when you first apply the droppable widget to an element. THE DROPPABLE WIDGET However, it can come in handy after someone has dropped an item into the droppable widget. For example, you might want to let a visitor add only five items to a shopping cart. Once the shopper drops in the fifth item, you can disable the drop zone so he can no longer add items to the cart. • hoverClass. You can also apply a class when an acceptable draggable item is dragged over a droppable item (Figure 12-3). For example, you could add a class to the trashcan element mentioned earlier only when the file is dragged on top of the trashcan: hoverClass : 'openTrashcan' FIGURE 12-3 Using a Droppable widget’s hoverClass option, you can apply a class to a droppable element when another element is dragged over it. Here, the large box lights up in bright yellow when the smaller box is dragged over it (the color change is provided by a CSS class style). The style adds both a background color and background image, but you could create a class style that added a bold outline to the drop zone, or even added a CSS animation to make the drop zone’s color pulsate between white and another color. • scope. Works like the draggable property of the same name (page 406). Lets you group related draggable and droppable widgets. scope : 'calendar' The name you use—'calendar' in this example—doesn’t matter. Use any name that makes sense—just make sure to use the same scope name for the related Draggable widgets and Droppable widgets. Chapter 12: jQuery UI Interactions and Effects 415 THE DROPPABLE WIDGET • tolerance. This option determines when a draggable item is considered to be hovering over a droppable item. There are four possible values for this option: • 'fit'—the draggable item must fit entirely within the droppable item. • 'intersect'—the draggable item must overlap the droppable item by at least 50% in both directions. In other words, the draggable item needs to be mostly inside the droppable item, but not entirely. This is the normal setting for droppables. • 'pointer'—only the mouse cursor needs to be inside the droppable item. • 'touch'—the draggable needs only to touch the droppable item on one side. The 'fit' option is good for confirming that the user really wants to place the draggable item onto the droppable item, but requires that the draggable item be smaller than the droppable item. The most common choice is 'intersect' because it doesn’t require extreme precision on a user’s part: tolerance : 'intersect' NOTE For a complete list of droppable widget options, methods, and events, visit http://api.jqueryui.com/ droppable/. Droppable Widget Events The real fun with droppable widgets comes when you make something happen when an item is dropped onto it…or dragged over it…or dragged off it. For example, you could calculate and display a sales total each time a shopper drops a product into a shopping cart, then recalculate that total if the shopper drags the product out of the cart. The droppable widget supports several different events, each of which is triggered by a different interaction with the droppable widget. You add a function to an event to make your program do something in response to dragging an item, moving an item over or out of the drop zone, or dropping an item onto the drop zone. For example, say you created a to-do list application: when a visitor drags an item from the list and drops it onto a trashcan icon, the item is removed from the to-do list and from the page. The event in this example is the drop event. Next, we’ll look at each event, starting with the most commonly used one. THE DROP EVENT This event triggers a function when an item is dropped onto the droppable item. The dropped item must be an acceptable item—that is, one that’s specified by the accept option (page 414) or within the same scope (page 406) as the droppable widget. The event is assigned as a property sent to the droppable widget as part of the options object. For example, say you have a <div> tag with an ID of trashcan. You turn that div into a droppable item, and assign it a drop event like this: 416 JAVASCRIPT & JQUERY: THE MISSING MANUAL $('#trashcan').droppable({ drop : function (event, ui) { // programming goes here } }); THE DROPPABLE WIDGET The function assigned to the drop event has two parameters—event and ui. The event parameter is a jQuery event object (page 164) that provides details such as which element is receiving the event, the screen coordinates of the mouse, and other information. The ui parameter is like the parameter used in draggable widget events (page 408). • The ui.helper property is a jQuery object containing a reference to the item that’s visibly dragged across the screen and is the same as the ui.helper property described for draggable items on page 410. Use the ui.helper property whenever you want to perform an action to the item that’s visibly dragged across the page. For example, if you wanted to make an element “explode” when it was dropped onto a trashcan, you could use this code: $('#trashcan').droppable({ drop : function (event, ui) { ui.helper.hide('explode'); } }); The 'explode' value here is actually a cool jQuery UI effect, that you’ll learn about on page 440. • The ui.draggable property is a jQuery object containing a reference to the element the draggable() method is run on. In many cases, this is the same as ui.helper. However, if you’ve set the draggable item’s helper property (page 405) to 'clone', the cloned item is dragged across the screen, while the original item is left in place. This property could also come in handy in the case of a shopping cart page. Say you’ve built a shopping cart system that tracks inventory as well as products. A catalog page might show a photo of a product plus a label indicating how many of those products are in stock—10, for example. When a shopper clicked on the product, she’d drag a clone of that product to the cart. When she dropped the clone on the cart, the drop function could update the ui.draggable item to lower the stock number by one (and at the same time, use Ajax—Chapter 13—to send the shopping data to the server). • ui.position provides the x and y positions of the top-left corner of the helper item when it’s dropped onto the target. It’s the same as the ui.position property described for draggable items on page 410. Chapter 12: jQuery UI Interactions and Effects 417 THE DROPPABLE WIDGET • ui.offset provides the top and left position of the draggable item in relation to the browser window. It’s the same as the draggable item’s ui.offset property described on page 411. • ui.originalPosition provides the top and left position of the draggable item just before a user starts dragging it. It’s the same as the draggable item’s ui.originalPosition property described on page 411. When using drop zone, you’ll probably end up using the drop event frequently. One task you might wish to perform is to prevent an item from being dragged out of the drop zone. Going back to the checkers example, you could make it so once a player moves a piece, she can’t take the move back. In other words, you want to “lock” the piece in place when it’s dropped onto a square. You could do that by disabling the dragged item, when it’s dropped on the drop zone: $('.square').drop({ drop : function (event, ui) { ui.helper.draggable({ disabled : true }); } }); You’re using the ui parameter’s helper object (the thing that was dragged onto the drop zone) and then calling the draggable() method to turn off dragging by setting that item’s disabled property to true. Keep in mind this is the disabled property of the draggable item (page 404) not of the drop zone. You'll need to set the disable property of the draggable item back to false to make the element draggable again (see page 404). THE ACTIVATE EVENT When a user starts dragging an element that’s acceptable to the drop target (see the droppable widget’s accept and scope options above), an activate event is triggered. You can add programming to respond to this event. Say, for example, you’re creating a web application that lets a user drag one or more photos into a div and then click a Send button to email those photos to a friend. You could add a label like “Drop photo here” to the drop zone, but only when the user starts dragging a photo. You could add a function to the activate event to write “Drop photo here” to the drop zone. Assuming the droppable item is a div with an ID of photoZone, here’s how you could add a message to the drop zone when the user started dragging a photo: $('#photoZone').droppable({ activate : function (event, ui) { $(this).append('<p id="dropMessage">Drop photo here</p>'); } }); 418 JAVASCRIPT & JQUERY: THE MISSING MANUAL The $(this) refers to the drop zone element (see page 139 if you need a refresher on what $(this) is and how it works). The append() method just adds HTML inside a tag as the last child of the element (page 127). THE DROPPABLE WIDGET The activate function accepts the same two parameters—event and ui—as the drop event (page 416). THE DEACTIVATE EVENT The deactivate event is the flip side of the activate event. It triggers a function when a user stops dragging an acceptable item—meaning the user has released the mouse button. You could use this to undo an action performed by the activate event. For example, to add a message to the drop zone while the user drags an item and then remove that message when he stops dragging the item, you could use this: $('#photoZone').droppable({ activate : function (event, ui) { $(this).append('<p id="dropMessage">Drop photo here</p>'); }, deactivate : function (event, ui) { $('#dropMessage').remove(); } }); THE OVER EVENT You can even run a function when a visitor drags an item over a droppable element. The over event is triggered as soon as a draggable item is over the drop zone, but before it’s dropped. You could use this event, for example, to add an encouraging message as a hesitant shopper pauses before dropping a product into a shopping cart: “You know you’ll look fabulous in those shoes. Just buy them!” Or, say you’ve created a trashcan drop zone for users to delete photos from their page. The trashcan is normally closed, but when the droppable item is over the can, the can’s lid comes off; when the item is dropped in the can, you could then use the drop event to replace the empty can with an image of a can full of trash. You program the over event just like any other Droppable widget event—just assign a function to the over property: $('#trashcan').droppable({ over : function (event, ui) { $('#trashCanImage').attr('src','images/open-lid-can.png'); } }); In this example, you’re just swapping out an image for another file, but you could make a much more elaborate function for this (or any) event. NOTE The tolerance property (page 416) determines when jQuery UI thinks a draggable item is over, dropped on, or out of the droppable zone. Chapter 12: jQuery UI Interactions and Effects 419 DRAGAND-DROP TUTORIAL THE OUT EVENT Finally, you can trigger a function when a visitor drags an item out of a drop zone. For example, say a shopper dragged a product into a shopping cart and you calculate the sales total when the product was dropped into the cart. Then, when the shopper decides he’s no longer interested in the product, he drags it out of the cart. The out event gives you a chance to deduct the cost of the removed product from the sales total: $('#shoppingCart').droppable({ drop : function (event, ui) { // perform math to update sales total }, out : function (event, ui) { // perform math to remove product cost from sales total } }); These few examples demonstrate that you’ll often use events in pairs to trigger opposite actions. For example, the out event with the drop event, and the deactivate event with the activate event. Drag-and-Drop Tutorial This example combines the draggable and droppable widgets into one program. You’ll build a simple drag-and-drop application that demonstrates the basic components of each widget. The final project will let you drag a photo to a trashcan, removing the photo in a dramatic fashion, as shown in Figure 12-4. NOTE See the note on page 12 for information on how to download the tutorial files. 1. In a text editor, open the file to-the-trash.html in the chapter12 folder. This file already contains a link to the proper CSS and JavaScript files as well as the $(document).ready() function (page 160). If you preview this page, you’ll see that there’s an image of a trashcan on the left and a row of photos on the right (Figure 12-4). The HTML for the trashcan and photos looks like this: <img src="../_images/trashcan-empty-icon.png" id="trashcan"> <div id="photos"> <img src="../_images/small/slide1_h.jpg"> <img src="../_images/small/slide2_h.jpg"> <img src="../_images/small/slide3_h.jpg"> <img src="../_images/small/slide4_h.jpg"> <img src="../_images/small/slide5_h.jpg"> <img src="../_images/small/slide6_h.jpg"> </div> 420 JAVASCRIPT & JQUERY: THE MISSING MANUAL The trashcan image has an ID of trashcan, and the photos are all inside a div with an ID of photos. You’ll start by making the photos draggable. DRAGAND-DROP TUTORIAL 2. In the empty line inside the $(document).ready() function, add the bolded line below: $(document).ready(function() { $('#photos img').draggable(); }); // end ready This selects all the img elements inside the photos div and turns them into draggable items. Because the goal of this project is to add an image to the trashcan, you want to make sure that if the visitor drops the photo anywhere but in the trashcan, the photo snaps back to its original location. FIGURE 12-4 Adding drag-and-drop elements to a page can create a fun, immersive and interactive experience for your site’s visitors. In this tutorial, you’ll learn how to create draggable items and make them disappear when dropped onto the proper target. 3. Add an object literal to the draggable() function, with the revert property set to 'invalid': $('#photos img').draggable({ revert : 'invalid' }); The revert option (page 405) can return a dragged item to its original starting place. By setting this option to 'invalid', you’re basically saying “Return this item to its original spot (revert), if its dropped in an 'invalid' spot.” What’s Chapter 12: jQuery UI Interactions and Effects 421 DRAGAND-DROP TUTORIAL invalid? Any element that isn’t specified as a droppable widget. Because you haven’t added a Droppable widget yet, the photos will always snap back to their original spot when dropped. 4. Save the page and preview it in a browser. Drag a photo around the page and drop it. The photo should snap back to where it started. If it doesn’t, double check your code and look in the JavaScript console for any errors (page 18). Next, you’ll use draggable events to make something happen when you start dragging a photo on the page. Specifically, you’ll apply a CSS transformation to the dragged photo. 5. Type a comma after invalid in the code you just added, hit Return and add a start event handler like this: $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { } }); The start option requires a function as its value. The function is an event handler just like the ones you used for jQuery’s click() and mouseover() functions (page 152). “Start” isn’t a real browser event, though. It’s a custom event programmed by the jQuery UI team, and it fires the moment someone starts to drag an item. The function here is empty, so you’ll need to add some programming to it next. In this case, you’ll just apply some simple CSS using jQuery’s css() function (page 134.) 6. Inside the function you just added, type the following code (in bold): $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); } }); As you read on page 409, the function assigned to draggable events accepts two parameters: an event object, and an object representing the draggable item— that’s the ui parameter. You can use the ui parameter to select the dragged item and do something to it. The ui.helper (page 410) is the actual element the user drags across the screen, and because it’s a jQuery object, you can apply any of jQuery’s many functions to it. In this case, the css() function applies the CSS transform property to the element, rotating it slightly and enlarging it 1.5 times. In other words, the image will rotate and grow bigger when it’s dragged. 422 JAVASCRIPT & JQUERY: THE MISSING MANUAL Next, you’ll make the photo return the photo back to normal when the visitor stops dragging it. NOTE DRAGAND-DROP TUTORIAL To learn more about the CSS transform property, visit www.sitepoint.com/css3-transformations-2d- functions/. 7. Add the stop event option to the option’s object: $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); } }); Don’t forget the comma after the start function. This function simply undoes the CSS that was applied at the start of the drag, returning the photo to its regular size and removing the rotation. If you save the file and preview it in a browser, you’ll notice something a little strange: if you click and start to drag a photo, you’ll notice that it appears underneath the photo to the right of it (Figure 12-5). The reason for this phenomenon is explained in Figure 12-5. The solution is simple; just increase the z-index value of the dragged element. 8. Add one last option, zIndex, to the options object. $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); }, zIndex : 100 }); Don’t forget the comma after the stop function. The zIndex option (page 408) simply adjusts the dragged element’s CSS z-index property. The higher the z-index value, the higher up the element is in the stacking order. A value of 100 is high enough to assure that the dragged element won’t appear behind any other items on the page. Chapter 12: jQuery UI Interactions and Effects 423 DRAGAND-DROP TUTORIAL FIGURE 12-5 An element’s z-index is affected by several factors. For example, the order of HTML can affect the stacking order of elements. In this case, the <img> tag for the selected hotel photo (circled) appears in the HTML of the page before the <img> tag of the golf tees (see the HTML snippet in step 1 on page 420). Accordingly, the hotel image is displayed underneath the photo of the tees. 9. Save the file and preview it in a web browser. Drag a photo around the page. The photo should rotate and grow slightly when you drag it, then snap back into place and revert to its normal size and rotation when released. In addition, when you first start to drag the photo, it should appear above any other photos around it. That’s enough work on the photos. Next, you’ll turn the trashcan image into a drop zone. 10. After the draggable() function, create a new line and add the following code: $('#trashcan').droppable(); This turns the trashcan image into a droppable widget. If you save the page and preview it now, you’ll see you can drop photos on the trashcan. The photos don’t move back to their original spot on the screen, however, because the trashcan is a valid drop zone. To make things more exciting, you’ll highlight the trashcan when a visitor starts to drag one of the photos. You’ll also make the trashcan appear brighter, alerting visitors that they can drag the photo to the trash. 11. Add an options object to the droppable() function: $('#trashcan').droppable({ activeClass : 'highlight' }); 424 JAVASCRIPT & JQUERY: THE MISSING MANUAL The activeClass option (page 414) simply adds a class name to the droppable widget as soon as someone drags a valid draggable on the screen. In this case, the highlight class, defined in the interactions.css file, changes the opacity of the trashcan image to 1 (100% opaque). Another rule in that CSS file sets the opacity of the trashcan to .6 (60% transparency) when the page loads. By changing the opacity from .6 to 1 with CSS, the trashcan appears brighter when a photo is dragged. DRAGAND-DROP TUTORIAL While this slight change looks cool and adds guidance for people viewing the page, you haven’t yet done anything when the photo is dropped in the trash. To do that, you need to use the droppable widget’s drop event. 12. Type a comma after 'highlight' in the code you just added, hit Return, and add a drop event handler like this: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { } }); The drop option requires a function as its value, just like the start and stop events on draggable items. This function is empty and doesn’t do anything yet, but you can make it do something—like make the dropped photo explode! 13. In the drop function, add the code in bold below: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); } }); ui.helper refers to the dragged item (page 410). The hide() method is a jQuery function you’ve used earlier in this book (page 184); however, jQuery UI gives additional effects for hiding and showing elements. The explode option creates a fun, animated effect—a playful way to make the photo disappear from the page. (You’ll read more about these effects on page 438.) One last thing: swap in a new image for the trashcan after a photo has been dropped on it, showing a trashcan full of trash. 14. Add one last line of code inside the drop function: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); $(this).attr('src','../_images/trashcan-full-icon.png'); } }); Chapter 12: jQuery UI Interactions and Effects 425 SORTING PAGE ITEMS $(this) refers to the trashcan—the <img> element on the page with the ID of trashcan. You’re simply changing that element’s src attribute to point to a new graphic. (You learned how to do that back in Chapter 7.) The finished code should look like this: $(document).ready(function() { $('#photos img').draggable({ revert : "invalid", start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); }, zIndex : 100 }); $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); $(this).attr('src','../_images/trashcan-full-icon.png'); } }); }); // end ready 15. Save the file and preview it in a web browser. You can drag photos onto the trashcan, and they explode and disappear from the page (Figure 12-4). There’s a lot more programming you could add to the drop event in this example. For example, you could send an Ajax request to a server and instruct the server to remove the photo from the user’s account (you’ll learn about Ajax in Chapter 13). But this quick tour hopefully has you thinking of many possible uses for the draggable and droppable widgets. NOTE You’ll find the finished version of this tutorial in the complete-to-the-trash.html file. Sorting Page Items jQuery UI also provides a widget for working with lists such as to-do lists, music playlists, and even lists within lists like folders inside of folders. The sortable widget makes it easy to re-order items within a group simply by dragging an item to a new position. This widget is useful for managing a list of songs, for example—users can create their own playlist by dragging songs into a playlist and even re-ordering those songs by dragging them to new spots in the list (Figure 12-6). 426 JAVASCRIPT & JQUERY: THE MISSING MANUAL The sortable widget works with any grouped collection of items. While it’s a natural option for an unordered or ordered list, you can also turn a group of divs, paragraphs, or images into a sortable group. SORTING PAGE ITEMS Using the Sortable Widget Sortable widgets are a collection of elements that can be dragged into a different position within a group: for example, in a to-do list, each to-do item can be dragged to a different position in the list. The list, then, is the sortable widget, and the list items inside it are the elements you can sort. In other words, the sortable widget must be a container element such as an unordered list (<ul>), ordered list (<ol>), or a <div> element containing other items such as additional divs, paragraphs, or images. FIGURE 12-6 jQuery UI’s sortable widget makes re-ordering list items a breeze. Drag items from one list—like My Favorite Songs—to another list—My Playlist. This kind of interaction is common in many desktop programs like iTunes, or even in a directory listing of files. Using the sortable widget is easy: 1. Follow the steps on page 304 to attach the CSS and JavaScript files. Remember that jQuery UI has its own CSS and JavaScript files, and that the jQuery UI JavaScript file should be linked to after the jQuery JavaScript file. 2. Add containing element to your web page. This might be an unordered list or a <div> tag: <ul id="playlist"> </ul> Chapter 12: jQuery UI Interactions and Effects 427 SORTING PAGE ITEMS It’s a good idea to add an ID or class to the tag, so you have a way to select that item with jQuery. 3. Add items inside the containing element. In the case of an unordered or ordered list, that would be a series of <li> tags. The items in the containing element represent the things that you can drag around and place in a new order within the list. In the case of a <div>, you could place images, paragraphs, or other divs inside (those items will be the sortable elements of the widget): <ul id="playlist"> <li>My Way -- Frank Sinatra</li> <li>Like a Rolling Stone -- Bob Dylan</li> <li>Respect -- Aretha Franklin</li> </ul> 4. Add jQuery’s $(document).ready() function to your page or to another external JavaScript file: $(document).ready(function() { }); // end ready As discussed on page 160, this step is only necessary if you’re putting your JavaScript code in the of the page, before the majority of your HTML. Some programmers put their JavaScript code at the bottom of the page, before the closing tag. In that case, you can skip the $(document). ready() function. 5. Use jQuery to select the containing element you added in step 2: $(document).ready(function() { $('#playlist').sortable(); }); // end ready This code selects the containing element (the <ul> element represented by the code in step 3) and makes all the items inside sortable. You can customize the sortable widget with many different options, described later. 6. Add options to the sortable() function: $(document).ready(function() { $('#playlist').sortable({ opacity : 0.5, placeholder : 'ui-state-highlight' }); }); // end ready You’ll learn about the various options for this widget next, but you can get a sneak preview by taking a look at what this code does. First, the opacity option tells jQuery UI to reduce the opacity of an element while it’s being dragged. The 428 JAVASCRIPT & JQUERY: THE MISSING MANUAL second option, placeholder, tells jQuery to apply a style to the empty space where a dragged item can be dropped onto. NOTE SORTING PAGE ITEMS You’ll get to try out the Sortable widget in the web app you’re going to build in Chapter 14. Sortable Widget Options jQuery UI’s sortable widget includes many options. You can control a sortable item’s direction and distance, how it behaves when you drag it, and even what portion of the element you can grab. Like other jQuery UI widgets, you can set options by passing an object to the sortable() function. For example, to change the cursor to a pointing finger and to set the <h2> element inside the item as the handle that a visitor must grab, you’d pass an object with those two options set: $('#playlist).sortable({ cursor : 'pointer', handle : 'h2' }); Here are some commonly used options: • axis. You can limit the movement of a sortable element to just left and right or up and down using the axis property. For example, say you created a horizontal group of divs that a visitor could re-order as part of a game (Figure 12-8). You could limit motion of those items to just left and right. Use either 'x' (to constrain the dragged item to just left and right movement) or 'y' (to make sure the dragged item can only be moved up and down the page): axis : 'x' • cancel. This option lets you prevent dragging an item if a specific element is clicked on. For example, say you had a playlist of songs (an unordered list). Next to the name of each song is a trashcan icon; users could click this icon to remove the song from the list. However, if a user grabbed that icon, he could drag the song to new spot on the list instead of delete the song. To prevent an element inside a sortable item from acting as handle, provide a selector to the cancel option: cancel : '.trashcan' Now, if someone clicked on the trashcan icon (assuming that icon had a class name of trashcan applied to it), she wouldn’t trigger the dragging action. You can even specify multiple elements—just separate them by commas: cancel : '.trashcan, .addToFavorites' The handle option, discussed on page 431, lets you specify a particular element to act as the “grabbable” part of the item. • connectWith. Lets you specify a selector of other sortable items—another list—that you can drag a list item to. For example, say you had two lists on a page: a wish list of products that you’d like to buy, and a shopping cart list that Chapter 12: jQuery UI Interactions and Effects 429 SORTING PAGE ITEMS includes all the products you’re going to buy. You might want to re-order your wish list—put your most desired products at the top of the list, for example— but also be able to drag an item from the wish list to the shopping cart list. In this case, you’d have two different lists, and apply the sortable() function separately to each. However, using the connectWith option, you can let users drag an item from one list to another: $('#wishList').sortable({ connectWith : '#shoppingCart' }); The connectWith option is a one-way connection. In other words, in the above code, you could only drag items from the group of items within the wish list to the shopping cart, but not from the shopping cart to the wish list. To connect both lists, you need to use the connectWith option on both lists: $('#shoppingCart').sortable({ connectWith : '#wishList' }); The value you supply the connectWith option should be a selector that matches an element to which you’ve applied the sortable() function. • containment. You can prevent a visitor from dragging a list item outside a container element. This works just like the containment option for the draggable widget (page 403). In fact, a sortable item is really just a draggable item that you can insert within a list of items. The containment option accepts several possible values: • A selector. If you provide a selector name, then jQuery UI will keep the list item confined to the boundaries of that element. For example, if you had a <div> on the page with an ID of mainContent, you could keep the draggable element inside that div by setting the containment option like this: containment : '#mainContent' • parent, document, or window. To keep the list item contained inside its parent element, use parent as the value. For example, if the list item is an unordered list and you want to limit the dragging to within that list: containment : 'parent' The document and window values are nearly the same, except document keeps the entire draggable area contained within the document area and window lets you drag the element partly outside the window (this doesn’t look very good, so think twice before using window). • cursor. Same as the cursor setting for draggable items (page 403) • cursorAt. Same as the cursorAt setting for draggable items (page 404) 430 JAVASCRIPT & JQUERY: THE MISSING MANUAL • delay. An amount in milliseconds to delay dragging the sortable item. This delay is handy if you find it easy to accidentally drag a list item as you’re mousing around the page. The delay indicates how long someone needs to hold down the mouse button before the dragging is allowed: SORTING PAGE ITEMS delay : 100 • distance. A pixel distance that a list item must be dragged before sorting begins. This is useful if visitors need to click on a sortable item other than to drag it. For example, if the sortable item includes a button to delete that item, you could set the distance option to prevent the item from being dragged when a visitor accidentally moves the mouse when clicking on the Delete button. Use a small number for this setting (otherwise, visitors will have to drag the item a fair distance before seeing the sortable behavior): distance : 10 • grid. Snaps the list item to a grid. This option could work well if you have a group of equally sized photos or divs: you can snap the list item to move exactly the width of the other list items when you drag it. It works just like the grid option for the draggable widget (page 404). • handle. Indicates the part of the item the user must click to drag the item to another place in the list. Normally, users can drag by clicking on any spot of a sortable item. However, you might want to force users to click on a specific part of the item—like a tab. This option works like the handle option for draggable options described on page 405. • items. You can limit which items within the sortable group can be sorted. For example, say you applied the sortable function to a nested list—a list containing indented lists or sublists (Figure 12-7). You don’t want to make the top-level list items sortable (in Figure 12-7, the top-level list items are Folder A and Folder B). You do want nested list items to be sortable, so they can be dragged into other nested lists or rearranged in their current nested list. In this case, you can use the items option and set it to 'li li', which means only a list item inside another list item (a nested list item) can be sorted. The top-level lists aren’t nested, so they can’t be sorted: items : 'li li' • opacity. When dragging an element you can make its opacity change. For example, you can fade the element to 50% opacity to give it a “ghost-like” appearance. Opacity is a common way to indicate that an item is moving from one place to another. Use a value between 0 (completely invisible) to 1 (completely opaque). This works just like the CSS opacity property. For example, to make the dragged element appear 50% transparent, set the value to 0.5: opacity : 0.5 Chapter 12: jQuery UI Interactions and Effects 431 SORTING PAGE ITEMS • placeholder. A class name jQuery UI applies to the empty spot where a list item can be dragged to. You can use one of jQuery UI’s own classes (page 395) to highlight this spot: placeholder : 'ui-state-highlight' FIGURE 12-7 You can create nested lists (lists within lists) in HTML by adding an unordered (<ul>) or ordered (<ol>) list tag inside a list item: <li>Folder A <ul><li>Sublist<!-- li--></li></ul></li>. jQuery UI lets you control which elements inside the sortable widget can be dragged and sorted, so you can limit sorting to just items inside nested lists. NOTE You’ll find even more options for the sortable widget at http://api.jqueryui.com/sortable/. Sortable Events As a visitor interacts with a sortable list, jQuery UI fires off all sorts of events—like when a visitor starts dragging an item in the list and when he stops dragging that item. jQuery UI provides over a dozen different sortable widget events, each of which you can respond to with your own programming. Some of these events fire off very close to each other and, in practice, are indistinguishable. As with the draggable and droppable widgets, you assign functions to a sortable event as part of the options object passed to the sortable() function. For example, to open an alert box after a user has moved an item in the list, you could write the following: $('#playList').sortable({ stop : function (event, ui) { alert('Well sorted, my friend!'); } }); Some events apply to all lists, and two only apply when you have two (or more) sortable lists on the same page and are dragging items between the lists. Suppose 432 JAVASCRIPT & JQUERY: THE MISSING MANUAL you start with a list of events that apply to all sortable widgets. These events are triggered in a specific order, so you’ll list them that way: SORTING PAGE ITEMS • create. This event fires whenever you use the sortable() function to create a new sortable list. You could use this event to pop up a dialog box with instructions “Drag the songs around to re-order your playlist.” It only runs once—when the sortable widget is created. NOTE Unlike all other Sortable widget events, the create event doesn’t receive the ui object (described on page 409). • start. Fired as soon as a user starts dragging a list item. The function you assign to this event accepts two arguments: an event object (page 164); and a ui object, which contains information about the widget. The ui object contains seven other objects, each with important information about the widget: • ui.helper. The helper object is a jQuery object that represents the item the user drags. jQuery UI makes a clone of the original item, so as you drag a sortable item, there are two different HTML elements in play: the helper clone and the actual element that’s part of the list. When the visitor stops dragging the item, the helper element is removed from the document. Because helper is a regular jQuery object, you can use jQuery methods such as css() , animate(), or find() on it. • ui.item. Represents the actual sortable item that the visitor clicked to drag, like an <li> element. It’s the real HTML element, and will be inserted into the proper spot in the list once the user has finished dragging the helper element. It’s also a jQuery object, so all the regular jQuery methods apply to it. • ui.position provides the x and y position of the top-left corner of the helper item (the item that is visibly dragged across the screen) in relation its nearest positioned ancestor. If the sortable widget is inside a relative or absolutely positioned element, then the ui.position property will provide the top and left position values for the help in relation to the top-left of the positioned element. You can access those values like this: ui.position.top and ui.position. left. • ui.originalPosition. The original position of the sortable item; where it was before the user started to drag it. This is an object like ui.position with two properties—top and left. • ui.offset is an object with two properties top and left. But, in this case, the position is calculated relative to the top left of the browser window. The ui.offset.top property identifies how far the top of the helper element is from the top of the window. The ui.offset.left property identifies how many pixels the draggable item is placed from the left side of the browser window. Chapter 12: jQuery UI Interactions and Effects 433 SORTING PAGE ITEMS • ui.sender. This property only applies when dragging from one sortable widget to another. The ui.sender property contains a jQuery object for the sortable widget the dragged item is coming from. • placeholder. A jQuery object representing the empty placeholder spot created when dragging a sortable item. The ui object is available to all other sortable event handlers—activate, over, sort, and so on—except the create event. • activate. Fires just after start, but at basically the same moment. You can use this to add a second function you want to run just after a function you’ve assigned to start. • sort. The sort event fires each time the mouse is moved while a sortable item is being dragged. In other words, this event fires off continuously, so don’t assign any time- or processor-intensive tasks to this event. If you do, the repeated calling of the function will slow the page’s responsiveness and probably make dragging the Sortable widget difficult for your visitors. • change. This event is fired as soon as sortable items change place. For example, when you drag an item from the top of a list down, and the second item jumps up to replace the first, the change event is triggered. You could use this event to highlight the two items that swapped position, for example. • beforestop. The beforestop event fires just after the user lets go of a sortable item. It’s the last event that still has access to the ui.helper object. After this event, the ui.helper (the clone of the dragged) item is deleted. • update. When all of the sortable items are in place, and the DOM has been updated, the update event fires. • deactivate. When sorting is done, the deactivate event always fires immediately after update. • stop. After the sortable item is dropped into place, the stop event fires. This event is last of all, and always follows stop and deactivate. Assign a function to this event, when you want it to be the last thing to happen after a list item has been dropped. For example, you could use the stop event to check the status of the list to see if it matches some pre-defined order (Figure 12-7). The events just listed fire in the order listed above. However, there are a few other events that are triggered at different times and for different types of Sortable widgets. • out. The out event is trigged when a sortable item is moved out of a Sortable widget; for example, if you drag an item out of its Sortable widget to an empty spot on the page. It also fires when you move an item out of one Sortable widget into another. • over. When you move a sortable item over a connected list. For example, if you have two connected lists and drag an item from the first list to the second, then 434 JAVASCRIPT & JQUERY: THE MISSING MANUAL the over event fires on that second list. This event also fires when you move an item off a group of sortable items and then back onto it. SORTING PAGE ITEMS • receive. Use the receive event when using multiple connected Sortable widgets (see the connectWith option on page 429). When a sortable widget receives an item from another sortable widget, the receive event fires. You can use this event in conjunction with the ui.sender object (page 434) to determine where the new sortable item came from. • remove. This event fires when an item is removed from the current sortable widget. For example, say you had two sortable widgets: a wish list and a shopping cart. If a shopper dragged an item from the wish list to the shopping cart, the remove event would fire on the wish list (as well as the out event). (In this scenario, the over and receive events would fire on the shopping cart as well.) Sortable Methods The sortable widget includes several different methods, or functions that you can run on the widget. You don’t call these methods as you would a normal jQuery method, like selecting a page element then applying the method to it like this: $('body'). hide(). Instead, you give the method name, as a string, to the sortable() method. Say you’re using the destroy method, which completely removes the sortable widget—it returns a sortable set of list items, to regular list items that can’t be dragged. The code to invoke the destroy method looks like this: $('#sortableItems').sortable('destroy'); The selector—#sortableItems, in this example—should match the selector for a sortable widget on the page. You’ll commonly use these methods in response to one of the sortable events discussed in the previous section. For example, if you created a game that required a player to place a set of blocks into a particular order, you could destroy the sortable after the player completed the game, keeping him from moving the blocks again. You can find a complete list of sortable methods at http://api.jqueryui.com/sortable/, but here are a few of the most useful: • cancel. This cancels any change in the current order of a sortable. In other words, it stops the re-ordering of the list. You could use this with the receive method (page 435), to reject a list item that was dragged to another sortable widget. Or as part of the stop event (page 434), you could create a function that checks the placement of the newly dropped item, and rejects that change if the item doesn’t meet certain conditions. For example, in a to-do list application, you might make certain tasks dependent upon other tasks. For example, if a user tries to drag a task to the top of the to-do list, but another task must be completed first, you could cancel that user’s action and pop up a dialog box with an explanation of why the move was rejected. • destroy. To completely remove the sortable functionality of a sortable widget, use the destroy method. Chapter 12: jQuery UI Interactions and Effects 435 SORTING PAGE ITEMS • disable. To temporarily remove the sortable functionality of a widget, invoke the disable method. Use this when you want to prevent sorting temporarily, until some other condition is true. You can turn the sorting back on with the enable method (discussed next). • enable. Turn sorting back on for a disabled sortable widget—a widget that previously had the disable method applied to it. • serialize. This method is useful for sending the order of the list back to a web server via Ajax or a form post. You might want to do this if it’s important to store this information on the server for later use. For example, if a manager was organizing a list of tasks for her employees, the order could be sent to the server, stored in a database, and retrieved when an employee logged in to see what tasks needed to be done (and in what order). You need to format your sortable items in a specific way: • Each list item must have an ID • Each ID should begin with the same word, which acts like a group identifier for the list, followed by an underscore (_) character. • After the _ character in the ID name must follow a unique identifier for the list item. For example, say you had a playlist of songs. The HTML might look like this: <ul id="playlist"> <li id="song_1">My Way -- Frank Sinatra</li> <li id="song_2">Like a Rolling Stone -- Bob Dylan</li> <li id="song_3">Respect -- Aretha Franklin</li> </ul> Notice that the ID for each list item begins with "song_" and ends with a unique number. It doesn’t have to be a number—it could be a word, or a unique ID from a database. The idea is to provide a way to let the server know the new order of the list. You can use the serialize method to capture the current order of the list: var listOrder = $('#playlist").sortable('serialize'); The serialize method returns a string that looks something like this: song[]=2&song[]=3&song[]=1 The string indicates the order of the items in the list. In this case, the numbers are 2, 3, and 1, indicating that the first item in the list was dragged to the bottom of the list. You can tag the string value returned by serialize to a URL as part of an Ajax call (Chapter 13). NOTE The serialize method lets you provide options that control the format of the string returned by the method. You can read about those options at http://api.jqueryui.com/sortable/#method-serialize. 436 JAVASCRIPT & JQUERY: THE MISSING MANUAL • toArray. The toArray method, like serialize, is a way to retrieve an ordered list of items in a sortable widget. To use it, you must add an ID to each item in the sortable list. But, unlike the serialize method, it doesn’t require any special format. The method simply returns an array listing the ID of each item in the sortable widget in the order the items appear in the list. For example, say you had a sortable widget with an ID of colorList. Inside it are three list items, each with a different color: SORTING PAGE ITEMS <ul id="colorList"> <li id="red">Red</li> <li id="green">Green</li> <li id="blue">Blue</li> </ul> Say a user dragged the colors into a different order so Blue was first, Red was second, and Green was last. You could use the toArray method at that point like this: var colors = $('#colorList').sortable('toArray'); The color variable would then contain this array: ['blue', 'red', 'green'] The result is a basic JavaScript array (page 44). You can use any of the array methods discussed on pages 46-51 to manipulate it. One use of the toArray method is to see the order of the list matches some predefined state. For example, say you created a game that showed a randomly assorted list of color blocks. The player is supposed to sort the blocks into the order they appear in the rainbow (remember, ROY G BIV?). You could add a function to the stop event (page 434) that gets the current order of the blocks using the toArray method and then compares it to another array containing the answer (Figure 12-8). NOTE jQuery UI includes two other interaction widgets. The resizable widget is used by the dialog widget (page 305) to let users resize them by dragging a resize handle in the corner of the box. You can use this widget to make resizable floating windows. Learn more about this widget at http://api.jqueryui.com/resizable/. Chapter 12: jQuery UI Interactions and Effects 437 JQUERY UI EFFECTS FIGURE 12-8 Use the sortable widget’s toArray method to retrieve an array of item IDs in the order those items currently appear in the list. You can use this information to compare the current order to some predefined result. In this game, each time a block is moved, the current order of the blocks is compared to a correct answer. If the order matches the answer, the player wins. You’ll find this file—pattern-game. html—in the chapter12 folder of the tutorial files. NOTE The selectable widget lets a visitor select elements (highlight them) by clicking them. You could use it for a photo download page: “Select the photos that you’d like to download.” Learn more at: http://api.jqueryui. com/selectable/. jQuery UI Effects jQuery UI includes a suite of visual, animated effects that you can use to enliven your web applications. For example, the explode effect, which you saw in action in the tutorial on page 425—makes an element break apart and fade out of view. You’ll learn more about these kinds of effects in a moment, but first you need to know how to apply them. Effects are intended to either bring an element into view, make the element disappear, or highlight the element in some way—for example, by making it light up or shake. To apply effects, you use either jQuery functions, as you’ve done so far in this book, or the jQuery UI-only effect() function. For example, to use the jQuery UI drop effect to make an element appear to drop onto the page, you could use the show() method with the name of the effect and a duration: $('#pageElement').show('drop', 1000); 438 JAVASCRIPT & JQUERY: THE MISSING MANUAL This would “drop” the element onto the page over the course of 1 second (1,000 milliseconds). The show() method should look familiar (page 184). It’s a jQuery function that reveals a hidden element on the page. However, jQuery UI adds some new features to jQuery’s show() function as well as to two other jQuery functions. jQuery UI offers four different functions for adding effects to elements: JQUERY UI EFFECTS • show(). jQuery UI extends jQuery’s show() function by letting you use one of 15 different effects to reveal an already hidden element. You should make sure the element is hidden (see the hide() method on page 184) before using show(); otherwise, you’ll end up with the element quickly disappearing then reappearing. • hide(). To apply one of jQuery UI’s effects while hiding an element, use the hide() method. It works like jQuery hide() function (page 184) in that it makes an element disappear from the page—but using a special effect. Make sure the element is visible on the page, before using this function. • toggle(). The toggle() method either shows or hides an element. If the element is hidden, the toggle() makes it appear using a specified effect. If the element is visible, then toggle() reveals the element. • effect(). Most of jQuery UI’s effects are designed to reveal or hide an element with flair. A few effects—bounce, highlight, pulsate, and shake—can be used to highlight an already visible item without making it disappear. The highlight effect, for example, momentarily highlights an item by flashing a bright color, providing a great way to draw a visitor’s attention to a specific spot on the page. The effect() function is unique to jQuery UI and isn’t a normal jQuery function. NOTE You’ll use the effect() function in the web app you’re going to build in Chapter 14. The Effects The jQuery UI effects add powerful animated tools to your web design toolkit. You can pass each of these effects as an argument to the functions listed above. Each effect provides a different visual result. The basic structure for using an effect with one of the above functions looks like this: $('#element').hide('effectName', { optionName : optionValue }, duration, callBackFunction); For example, if you wanted to hide an element with an ID of deleteThis on the page by making it explode into 16 pieces in half a second, and then pop up an alert box that says “Boom!” you’d write this code: $('#deleteThis').hide('explode', { pieces : 16 }, 500, function () { alert('Boom!'); }); Most effects let you pass one or more additional options to control how the effect works. Options are passed as an object consisting of option names and values. In Chapter 12: jQuery UI Interactions and Effects 439 JQUERY UI EFFECTS the previous example, the option is the number of pieces the explode effect should divide the element into: { pieces : 16 } Each effect has different options, and some effects have no options at all. jQuery UI provides many effects: • blind. The blind effect either shows or hides an element simulating a blind being lifted open or pulled closed. The effect accepts one option—direction—which indicates the direction the blind should move: up, down, left, or right. You pass the option as an object—option name and value—as second argument to the function. For example, to make a particular element disappear from the screen: $('#element').hide('blind', { direction : 'left'}, 1000); • bounce. The bounce effect can be applied when hiding or showing an element. You can also use bounce with the effect() function to simply bounce a visible item up and down—a great way to make a page element say “look at me!!!!” The effect has two options: • distance. The farthest distance (in pixels) that the element will travel as it bounces. The higher the number, the farther it bounces, and the more attention it grabs. • times. The number of times the element will bounce. For example, to make an item bounce 20 times, at a distance of 100 pixels every time it’s clicked, you could write this code: $('#theElement').click(function () { $(this).effect('bounce', { distance : 100, times : 20 }, 1000 ); }); • clip. The clip effect applies the CSS clip attribute to an item to make it appear either vertically or horizontally. The effect accepts only one option—direction with a value of either vertical or horizontal: { direction : 'horizontal' } • drop. The drop effect shows or hides an element by fading it into or out of view while sliding it up, down, left, or right. It has a single option, direction, which accepts one of the following four values: up, down, left, or right. • explode. The explode effect divides an element into a bunch of pieces, animates them outward and fades them out of view. When used with the show() function, the element looks like an explosion in reverse: separate pieces coming together 440 JAVASCRIPT & JQUERY: THE MISSING MANUAL to form a whole. It only has one option—pieces—which indicates the number of pieces the element should be divided into. The number has to be a squared value: 1, 4, 9, 16, 25, and so on (but don’t make the number any bigger than 25 or this effect slows down to a crawl): JQUERY UI EFFECTS { pieces : 16 } • fade. Works like jQuery’s fadeIn() and fadeOut() functions. In other words, it’s not a terribly exciting effect. • fold. The fold effect shows or hides an element by folding it. You can set two options for this intriguing visual effect. size is the size in pixels (or percentages) that the item should reduce to before folding in the opposite direction and horizFirst accepts a Boolean value that determines whether the element should fold up vertically first (the default) or horizontally first: { size : '50%', horizFirst : true } • highlight. The highlight effect momentarily changes the background color of an element to draw attention to it. It’s another effect you can use on a visible element without hiding it. You can change the color of the background color by setting the color option. For example, to highlight an element by flashing a red background color for 1 second, you could apply the effect() method like this: $('#element').effect('highlight', { color : '#ff0000' }, 1000); • puff. This effect makes an element change size and fade out (or into) view. It has a single option, percent, which dictates the percentage the element should fade from (if showing the element) or fade to (if hiding the element): { percent : 200 } • pulsate. Another effect that you can use to draw attention to an element without hiding it first. This effect hides and shows an element repeatedly. You can dictate the number of times the element pulsates by setting the times option like this: $('#element').effect('pulsate', {times : 20}, 2000); • scale. Use this effect to scale an element. You can use this effect with either the hide() or show() methods. Normally, if you use the show() method to reveal a hidden element, the element will scale up from a tiny spot on the page to its full size; if the element is visible and you use the hide() method, the element will shrink and disappear. • shake. This effect can be applied to an element that’s visible on the page using the effect() function (page 439). It simply shakes the element a specific direction, distance, and number of times. This is another one of those “Pay attention to me” type of effects, but it can serve a more important purpose, like indicating an error; for example, shaking a dialog box when a visitor hasn’t checked the “Terms of service” box on a signup form. This effect has three options. The direction option dictates the direction to begin shaking the element: up, down, left, or right. Set the distance option to specify the number Chapter 12: jQuery UI Interactions and Effects 441 JQUERY UI EFFECTS of pixels the element should move on each shake; the greater the number, the more obvious the shaking action. Finally, the times option indicates the number of times the element shakes. For example, to shake an element left (and keep shaking it horizontally) 10 times, 50 pixels each time, you’d pass this object containing these options to the effect() function: { direction : 'left' , distance : 50, times : 10 } • size. This effect resizes an element to a specified width and height. It accepts three options: to is an object with width and height properties dictating the width and height the element should be resized to (when hiding the element) or the width and height to start at (when showing the element). The origin property dictates the vanishing point when using the size effect to hide an element. It’s an array of two numbers: the first number indicates the top position, and the second the left position. The scale property is used to indicate what should be scaled. The possible values include both, box, and content. For example, to increase or decrease just the size of the outer box (the border, background, and width and height) use the box value. Doing so doesn’t scale the content (like text) inside the element. • slide. This effect slides an element out of the viewport (if hiding it) or slides the element into place (if it’s showing). Provide a direction option—left, right, up, or down—to dictate the direction the slide effect moves: $('#element').show('slide', { direction : 'right' }, 1000 ); NOTE To learn more about jQueryUI effects, visit http://api.jqueryui.com/category/effects/. Easing jQuery UI includes a set of easing functions that control the speed of changes during an animation. Easing doesn’t change the overall time an effect takes to animate, but does changes the speed at which individual parts of an animation occur. For example, if you use the bounce effect, you could apply an easing function that makes the bouncing start slowly then bounce really quickly before stopping. NOTE Visit the jQuery UI Easings page to see what each easing function looks like and to try them out: http://api.jqueryui.com/easings/. To use an easing function with an effect, you need to pass it as a property of the options object. Its property name is easing, and the value should be one of the possible easing functions—easeInOutQuart, easeInSine, and so on (for a complete list of easing function names, visit http://api.jqueryui.com/easings/). For example, say you want to use the bounce effect (page 440), to bounce an element each time it’s clicked. You want the element to bounce 20 times with a 442 JAVASCRIPT & JQUERY: THE MISSING MANUAL maximum distance of 100 pixels (those are both options of the bounce effect). You also want to apply an easing function to make it look more realistic—a bouncing element slows down as it runs out of energy. You could add an easing property to the options object like this: JQUERY UI EFFECTS $('#theElement').click(function () { $(this).effect('bounce', { distance : 100, times : 20, easing : 'easeOutBounce' }, 1000 ); }); You’re not limited to using these easing functions only with jQuery UI’s effects. As discussed on page 192, you can use these functions with jQuery UI animations as well. Animating Changes Between Classes jQuery UI includes several functions that animate changes to an element’s CSS properties when a class is added or removed from the element. These functions are actually extensions of existing jQuery functions: addClass(), toggleClass(), and removeClass() (page 131). jQuery UI simply adds animation to the changes, so when you add or remove a class, jQuery UI animates the visual changes that occur because of the addition or removal of CSS properties. NOTE jQuery UI’s class animations may sound a lot like CSS transitions. In fact, they’re very similar: while CSS transitions depend on the browser’s built-in CSS rendering engine, jQuery uses JavaScript to animate the changes. CSS transitions are actually a better way to go: they work more smoothly and don’t require any work from the JavaScript interpreter. However, CSS transitions aren’t supported by Internet Explorer 9 or earlier, therefore you may need to use jQuery UI’s class animation feature to get the same effect in those browsers. However, if you don’t need to support outdated versions of Internet Explorer, then use CSS transitions, and skip these jQuery UI functions. To learn more about CSS transitions, visit: https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/ Using_CSS_transitions. Each of jQuery UI’s class animation features accept up to four arguments to modify how they work. The first argument is the class name you want to add or remove. The next three are composed of a duration, easing, and completion function—the same arguments you pass the effect() method (page 439). For example, to select an element with the ID of feature, add a class name highlight, and animate the visual changes caused by adding that class, you could write this: $('#feature').addClass('highlight', 1000, 'easeOutBack', function () { alert('done animating'); }); Chapter 12: jQuery UI Interactions and Effects 443 JQUERY UI EFFECTS This code adds the highlight class to the selected element and animates the visual changes to the element over the course of 1 second (1,000 milliseconds) using the easeOutBack easing method (page 442). After jQuery UI is finished animating the class change, a callback function is run opening an alert box with the words “done animating.” Only a class name and duration are necessary to get the animated effect. jQuery UI provides four functions for animating class changes: • The addClass() method lets you add a class to one or more elements and animate the visual changes over a specified amount of time. NOTE If you don’t pass a time argument to any of these methods, jQuery UI simply uses the standard jQuery form of the function, without animation. For example: $('#feature').addClass('highlight'); This code adds the class highlight to the element, but doesn’t animate the change. • The removeClass() method works just like the addClass() method. You pass it a class name, animation duration, optional easing value, and optional callback function. However, this function removes the specified class and animates any visual changes caused by removing that class. • The toggleClass() method removes a class from an element if that class is in place, or adds the specified class if it’s missing. You could use this function in conjunction with a click event (page 149) to add a class the first time an element is clicked, then remove that class the next time it’s clicked—in this way, you could create a “light switch” element that’s either on or off. Of course, this function also animates the changes caused by adding or removing the class. NOTE jQuery UI’s toggleClass() method has more advanced options as well. You can read about them at: http://api.jqueryui.com/toggleClass/. • The switchClass() method is the only one of these jQuery UI class methods that has no jQuery equivalent. It takes two class names: the first is the class that jQuery UI removes from the selected elements, and the second is a class that jQuery UI adds. It’s kind of like combining the removeClass() and addClass() methods together, but lets you animate the changes from the class you’re removing to the class you’re adding. For example, if you’re removing a class with a red background color and adding a class with a green background color, jQuery UI will animate that background color change by transitioning from red to green: $('#feature').switchClass('defaultStyles','highlight',1000); NOTE To learn more about jQueryUI methods, visit the Effects Core page at http://api.jqueryui.com/category/ effects-core/. 444 JAVASCRIPT & JQUERY: THE MISSING MANUAL PART Advanced jQuery and JavaScript CHAPTER 13: Introducing Ajax CHAPTER 14: Building a To-Do List Application 4 CHAPTER Introducing Ajax 13 J avaScript is great, but it can’t do everything. If you want to display information from a database, dash off an email with results from a form, or just download additional HTML, you need to communicate with a web server. For these tasks, you usually need to load a new web page. For example, when you search a database for information, you usually leave the search page and go to another page of results. Of course, waiting for new pages to load takes time. If anything, people want websites to feel faster and more responsive, as if they were operating right on their own desktop, not on some far-off server. Sites like Facebook, Twitter, Google Docs, and Gmail are blurring the line between websites and desktop computer programs. The technology that makes this new generation of web applications possible is a programming technology called Ajax. Ajax lets a web page ask for and receive a response from a web server and then update itself without ever having to load a new web page. The result is a website that feels more responsive. For example, when you visit Google Maps (Figure 13-1), you can zoom into the map; move north, south, east, or west; and even grab the map and drag it around. All of these actions happen without ever loading a new web page. What Is Ajax? The term Ajax was originally coined in 2005 to capture the essence of new websites coming from Google—Google Maps (http://maps.google.com), and Gmail (www. gmail.com). Ajax stands for Asynchronous JavaScript and XML, but it isn’t an “official” technology like HTML, JavaScript, or CSS. It’s a term that refers to the interaction of 447 WHAT IS AJAX? a mix of technologies—JavaScript, the web browser, and the web server—to retrieve and display new content without loading a new web page. FIGURE 13-1 Google Maps (http:// maps.google.com) was one of the first large sites to use Ajax to refresh page content without loading new web pages. The site’s responsiveness is due to the fact that only the map data changes—the other parts of the page, like the search box, search results sidebar, and map controls, remain the same even as you request new map information. Here’s how Ajax works: you use JavaScript in your website to send a request from the web browser to a web server, which, in turn, sends some data back (called a response) to the web browser. The JavaScript program takes the response and does something with it. For example, if you’re on a Google Maps page and click the “north” arrow button, the page’s JavaScript code requests new map data from the Google server. Google sends back its response—new parts of the map—which the JavaScript then uses to update the map in the browser. While you may not create the next Google Maps, there are many simple things that you can do with Ajax technologies: • Display new HTML content without reloading the page. For example, on a page that lists news headlines and displays the article when a visitor clicks a headline, you can save her the tiresome wait for a new page to load. Instead, the news story could appear right on the same web page, without the banner, sidebar, footer, or other page content needing to reload. You’ll learn how on page 455. • Submit a form and instantly display results. For example, imagine a “sign up for our newsletter” form; when someone fills out and submits the form, the form disappears and a “you’re signed up for our newsletter” message immediately appears. You’ll learn how to make such forms using Ajax on page 471. 448 JAVASCRIPT & JQUERY: THE MISSING MANUAL • Log in without leaving the page. Here’s another form-related use of JavaScript— a page with a small “login” form. Fill out the form, hit the “login” button, and you’re not only logged in, the page transforms to show your login status, username, and perhaps other information specific to you. AJAX: THE BASICS • Star-rating widget. On sites that list books, movies, and other products, you often see a star rating—usually 1 to 5 stars—to indicate how visitors have rated the item’s quality. These rating systems usually let you voice your opinion by clicking a number of stars. Using Ajax, you can let your visitors cast votes without actually leaving the web page—all they have to do is click the stars. There’s a cool jQuery plug-in that does just that: www.wbotelhos.com/raty/. • Browsing through database information. Amazon is a typical example of an online database you can browse. When you search Amazon for books on, say, JavaScript, you get a list of the JavaScript books Amazon sells. Usually, there are more books than can fit on a single web page, so you need to jump from page to page to see “the next 10 items.” Using Ajax, you can move through database records without having to jump to another page. Here’s how Twitter uses Ajax: When you view your Twitter page, you see a bunch of tweets from the people you follow. If you scroll to the bottom of the page, Twitter loads more tweets. Scroll again and more tweets appear. It’s like a never-ending web page! There’s nothing revolutionary about any of the tasks listed here—except for the “without loading a new page” part, you can achieve the same basic results using regular HTML and some server-side programming (to collect form data, or access database information, for example). However, Ajax makes web pages feel much more responsive, and lets you create a richer experience for your visitor. Ajax: The Basics Taken together, the technologies behind Ajax are pretty complicated. They encompass JavaScript, server-side programming, and the web browser all working together. However, the basic concept is easy to grasp, as long as you understand all of the steps involved. Figure 13-2 shows the difference between how HTML web pages and web pages with Ajax communicate with the web server. Pieces of the Puzzle Ajax isn’t a single technology—it’s a mixture of several different technologies that work together to make a more effective user experience. In essence, Ajax brings together three different components: • The web browser. Obviously, you need a web browser to view web pages and run JavaScript, but there’s a secret ingredient built into web browsers that makes Ajax possible: the XMLHttpRequest object. This odd-sounding term is what lets JavaScript talk to a web server and receive information in response. Chapter 13: Introducing Ajax 449 AJAX: THE BASICS The XMLHttpRequest object was actually introduced way back in Internet Explorer 5, but has made its way into all the major web browsers. You’ll learn more about it on page 452. FIGURE 13-2 In the simplest websites, a web browser requests a file from the server and receives a web page back (top). It’s a constant loading and reloading of web pages. With Ajax, the web browser requests only new information. The server returns the requested data, and the web page’s content and appearance are updated with help from JavaScript (bottom). • JavaScript does most of the heavy lifting in Ajax. It sends a request to the web server, waits for a response, processes the response, and (usually) updates the page by adding new content or changing the display of the page in some way. Depending upon what you want your program to do, you might have JavaScript send information from a form, request additional database records, or simply send a single piece of data (like the rating a visitor just gave to a book). After the data is sent to the server, the JavaScript program will be ready for a response 450 JAVASCRIPT & JQUERY: THE MISSING MANUAL back from the server—for example, additional database records or just a simple text message like “Your vote has been counted.” AJAX: THE BASICS With that information, JavaScript will update the web page—display new database records, for example, or inform the visitor that he’s successfully logged in. Updating a web page involves manipulating a page’s DOM (Document Object Model, discussed on page 117) to add, change, and remove HTML tags and content. In fact, that’s what you’ve been doing for most of this book: changing a page’s content and appearance using JavaScript. • The web server receives requests from and sends information back to the web browser. The server might simply return some HTML or plain text, or it might return an XML document (see the box on page 471) or JSON data (page 477). For example, if the web server receives information from a form, it might add that information into a database and send back a confirmation message (like “record added”). Or, the JavaScript code might send a request for the next 10 records of a database search, and the web server will send back the information for those next 10 records. The web server part of the equation can get a bit tricky. It usually involves several different types of technologies, including a web server, application server, and database server. A web server is really kind of a glorified filing cabinet: It stores documents and when a web browser asks for a document, the web server delivers it. To do more complicated tasks such as putting data from a form into a database, you also need an application server and a database server. An application server is programmed in a language like PHP, Java, C#, Ruby, or Cold Fusion Markup Language and lets you perform tasks that aren’t possible with only an HTML page, like sending email, checking Amazon for book prices, or storing information in a database. The database server lets you store information like the names and addresses of customers, details of products you sell, or an archive of your favorite recipes. Common database servers include MySQL, PostgreSQL, and SQL Server. NOTE The term server can refer either to a piece of hardware or software. In this book, the terms application, web, and database server refer to different pieces of software that can (and often do) run on the same machine. There are many different combinations of web servers, application servers, and database servers. You might use Microsoft’s IIS web server with ASP.NET (application server) and SQL server (a database server), for example. Or you can use Apache (a web server), PHP (an application server), and MySQL (a database). NOTE The combination of Apache, PHP, and MySQL (often referred to simply as AMP) is very common and available at no cost. You’ll find that most web hosting companies provide these servers for you. This book’s examples also use AMP (see the box on page 452). Chapter 13: Introducing Ajax 451 AJAX: THE BASICS UP TO SPEED Setting Up a Web Server Ajax works with a web server—after all, its main purpose is to let JavaScript send and retrieve information from a server. While the Flickr tutorial in this following chapter will run on your local computer without a web server, the others won’t. In addition, you’ll need to have access to a web server if you want to further explore the world of Ajax. If you’ve already got a website on the Internet, one choice is to test your Ajax programs by moving your files to the web server. Unfortunately, this technique is cumbersome—you have to create the pages on your computer and then move them to your web server using a FTP program just to see if they work. A better approach is to set up a development server, which involves installing a web server on your desktop computer so you can program and test your Ajax pages directly on your own computer. This task may sound daunting, but there are plenty of free programs that make installing all of the necessary components as easy as double-clicking a file. On the Windows side, you can install Apache, PHP, and MySQL using WAMP (www.wampserver.com/en/ ). WAMP is a free installer that sets up all of the required elements needed to simulate a real website hosted on the Internet. For Mac fans, MAMP (www.mamp.info/en) provides an easyto-use program that includes Apache, PHP, and MySQL. It’s also free. (There’s even a version of MAMP for Windows.) The tutorials on pages 458 and 471 require a web server. So if you want to follow along with that tutorial, you’ll need to install a web server on your computer using one of the two programs just mentioned. If you already have a website that uses a different web server (for example, Microsoft’s IIS), you’ll probably want to install it on your computer if you plan to create Ajax applications that you’d like to use on your real website. IIS is already installed in Windows 8; you just need to turn it on. This video will show you how: https://www.youtube. com/watch?v=mRm9-Xddt2w. Talking to the Web Server The core of any Ajax program is the XMLHttpRequest object. Sometimes just referred to as XHR, the XMLHttpRequest object is a feature built into web browsers that allows JavaScript to send information to a web server and receive information in return. There are basically five steps, all of which can be accomplished with JavaScript: 1. Create an instance of the XMLHttpRequest object. This first step simply tells the web browser “Hey, I want to send some information to the web server, so get ready.” In its most basic form, creating an XMLHttpRequest object in JavaScript looks like this: var xhr = new XMLHttpRequest(); While this bit is simple, programming Ajax with plain JavaScript can be tough. Fortunately, jQuery provides an easier way to make Ajax requests. You’ll learn the jQuery way on page 455. 452 JAVASCRIPT & JQUERY: THE MISSING MANUAL 2. Use the XHR’s open() method to specify a method for sending the data and where the data will go. AJAX: THE BASICS You can send data in several ways. The two most common are GET and POST— these are the same options as used with HTML forms. The GET method sends any information to the web server as part of the URL—shop.php?productID=34. In this example, the data is sent as a “query string.” The query string is the information that follows the ? (in this case, productID=34). This is a name/value pair, where productID is the name and 34 is the value. Think of the name like the name of a field on a form and the value as what a visitor would type into that field. The POST method sends data separately from the URL. Usually, you use the GET method to get data back from the server, and the POST method to send information that the server needs to keep (for example, to add, update, or delete a database record). You’ll learn how to use both methods on page 462. You also use the open() method to specify the page on the server the data is sent to. That’s usually a page on your web server that uses a server-side scripting language like PHP to retrieve data from a database or perform some other programming task, and you point to it by its URL. For example, the following code tells the XHR object what method to use (GET) and which page on the server to request: xhr.open('GET', 'shop.php?productID=34'); NOTE The URL you specify for the open() method must be on the same website as the page making the request. For security, web browsers won’t let you make Ajax requests to other domains. JSONP provides one way around this security problem. You’ll learn about it on page 483. 3. Create a function to handle the results. When the web server returns a result like new database information, a confirmation that a form was processed, or just a simple text message, you usually want to do something with that result. That could be as simple as writing the message “form submitted successfully,” or replacing an entire table of database records with a new table of records. In any case, you need to write a JavaScript function to deal with the results—this function (called a callback function) is often the meat of your program. Usually, this function will manipulate the page’s content (that is, change the page’s DOM) by removing elements (for example, removing a form that was just submitted using Ajax), adding elements (a “form submitted successfully” message, or a new HTML table of database records), or changing elements (for example, highlighting the number of stars a visitor just clicked to rate a product). There are a few other steps involved here, but you’ll be using jQuery to handle the details, so the only thing you really need to understand about the callback function is that it’s the JavaScript that deals with the server’s response. Chapter 13: Introducing Ajax 453 AJAX: THE BASICS 4. Send the request. To actually send information to the web server, you use the XHR object’s send() method. Everything up to this point is just setup—this step is what tells the web browser, “We’re good to go…send the request!” If you’re using the GET method, this step is as simple as: xhr.send(); The send() method can accept an argument—data that should be sent to the server. In the case, of a GET request, the data is sent in the URL like this: search. php?q=javascript, where the q=javascript is the data. With the POST method, on the other hand, you must provide the data along with the send() method like this: xhr.send('q=javascript'); Again, don’t sweat the details here—you’ll see how jQuery greatly simplifies this process starting in the next section. Once the request is sent, your JavaScript code doesn’t necessarily stop. The “A” in Ajax stands for asynchronous, which means that after the request is sent, the JavaScript program can continue doing other things. The web browser doesn’t just sit around and wait for the server to respond. 5. Receive the response. After the server has processed the request, it sends back a response to the web browser. Actually, the callback function you created in step 3 handles the response, but meanwhile, the XHR object receives several pieces of information when the web server responds, including the status of the request, a text response, and possibly an XML response. The status response is a number indicating how the server responded to the request: You’re probably familiar with the status number 404—it means the file wasn’t found. If everything went according to plan, you’ll get a status of 200 or possibly 304. If there was an error processing the page, you’ll get a 500 Internal Server Error status report, and if the file you requested is password protected, you’ll get a 403 Access Forbidden error. For a complete list of status codes, visit www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. In addition, most of the time, you’ll receive a text response, which is stored in the XHR object’s responseText property. This response could be a chunk of HTML, a simple text message, or a complex set of JSON data (page 477). Finally, if the server responds with an XML file, it’s stored in the XHR object’s responseXML property. Although XML is still used, it’s more common for program server pages to return text, HTML, or JSON data, so you may never have a need to process an XML response. Whatever data the server returns, it’s available to the callback function to use to update the web page. Once the callback function finishes, the entire Ajax cycle is over. (However, you may have multiple Ajax requests shooting off at the same time.) 454 JAVASCRIPT & JQUERY: THE MISSING MANUAL AJAX THE JQUERY WAY Ajax the jQuery Way Although the basic XMLHttpRequest process isn’t too complicated, you do have to repeat the same set of steps each time you make an XHR request. Fortunately, the jQuery library provides several functions that greatly simplify the entire process. After all, if you look at the five steps in an Ajax request (page 452), you’ll see that the interesting stuff—the programming that actually does something with the server’s response—happens in just a single step (step 3 on page 453). jQuery simplifies all of the other steps so you can concentrate on the really fun programming. Using the load() Method The simplest Ajax method offered by jQuery is load(). This method loads an HTML file into a specified element on the page. For example, say you have an area of a web page dedicated to a short list of news headlines. When the page loads, the five most recent news stories appear. You may want to add a few links that let visitors choose what type of news stories are displayed in this area of the page: for example, yesterday’s news, local news, sports news, and so on. You can do this by linking to separate web pages, each of which contain the proper news items—but that would force your visitors to move onto another web page (and wouldn’t use Ajax at all!). Another approach would be to simply load the selected news stories into the news headlines box on the page. In other words, each time a visitor clicks a different news category, the web browser requests a new HTML file from the server, and then places that HTML into the headlines box—without leaving the current page (Figure 13-3). UP TO SPEED Learning the Ways of the Server Side Unless you’re using jQuery’s basic load() function (discussed above) to insert HTML from a page on the server into the page in the web browser, you’ll need to have server-side programming to use Ajax. The main point of Ajax is to let JavaScript talk to and get information from the server. Most of the time, that means there’s another script running on the web server that completes tasks JavaScript can’t do, like reading information from a database, sending off an email, or logging a user in. This book doesn’t cover the server side, so you’ll need to learn how to program using a server-side technology like PHP, Ruby on Rails, .NET, or JSP (or you’ll need someone who can program the server-side bit for you). If you haven’t picked a server-side language yet, PHP is a good place to start: It’s one of the most popular web server programming languages, it’s free, and nearly every web hosting company offers PHP on its servers. It’s a powerful language that’s built for the web, and it’s relatively easy to learn. If you want to get started learning server-side programming with PHP, check out Learning PHP, MySQL, and JavaScript (O’Reilly) and Head First PHP & MySQL (O’Reilly). There are also plenty of free online resources for learning PHP. PHP 101 (http://devzone.zend.com/6/php-101-php-for-theabsolute-beginner/) from Zend (one of the main companies that supports the development of PHP) has plenty of basic (and advanced) information. The W3Schools website also has a lot of information for the beginning PHP programmer at www. w3schools.com/PHP. Chapter 13: Introducing Ajax 455 AJAX THE JQUERY WAY FIGURE 13-3 The top set of images shows how links work—the typical method of accessing additional HTML. Click a link on a page (top left) and it loads a brand new page (top right). However, using Ajax and jQuery’s load() function, you can access the same HTML without leaving the current web page (bottom). Clicking a link loads the HTML content into a <div> tag (outlined). 456 JAVASCRIPT & JQUERY: THE MISSING MANUAL To use the load() function, you first use a jQuery selector to identify the element on the page where the requested HTML should go; you then call the load() function and pass the URL of the page you wish to retrieve. For example, say you have a <div> tag with the ID headlines and you want to load the HTML from the file todays_news.html into that div. You can do that like this: AJAX THE JQUERY WAY $('#headlines').load('todays_news.html'); When this code runs, the web browser requests the file todays_news.html from the web server. When that file is downloaded, the browser replaces whatever is currently inside the <div> with the ID headlines with the contents of the new file. The HTML file can be a complete web page (including the , , and tags), or just a snippet of HTML—for example, the requested file might just have a single <h1> tag and a paragraph of text. It’s OK if the file isn’t a complete web page, as the load() function inserts only that HTML snippet into the current (complete) page. NOTE You can only load HTML files from the same site. For example, you can’t load Google’s home page into a <div> on a page from your site using the load() function. When using the load() function, you must be careful with the file paths. First, note that the URL you pass to the load() function is in relation to the current page. In other words, you use the same path as if you were linking from the current page to the HTML file you wish to load. In addition, any file paths in the HTML don’t get rewritten when the HTML is loaded into the document, so if you have a link or include images in the HTML file that’s loaded, those URLs need to work in relation to the page using the load() function. In other words, if you’re using document-relative paths (see the box on page 11) and the loaded HTML file is located in another folder on your website, images and links might not work when the HTML is loaded into the current page. Here’s a simple workaround: Just use root-relative links, or make sure the file you load is located in the same directory as the page that’s using the load() function. The load() function even lets you specify which part of the downloaded HTML file you wish to add to the page. For example, say the page you request is a regular web page from the site; it includes all of the normal web page elements such as a banner, navigation bar, and footer. You may just be interested in the content from a single area of that page—for example, just a particular <div> and its contents. To specify which part of the page you wish to load, insert a space after the URL, followed by a jQuery selector. For example, say in the preceding example you want to insert the content only inside a <div> with the ID news in the todays_news.html file. You could do that with this code: $('#headlines').load('todays_news.html #news'); In this case, the web browser downloads the page todays_news.html, but instead of inserting the entire contents of the file into the headlines div, it extracts just the <div> element (and everything inside it) with an ID of news. You’ll see this technique in the following tutorial. Chapter 13: Introducing Ajax 457 AJAX THE JQUERY WAY Tutorial: The load() Function In this tutorial, you’ll use jQuery to replace the traditional click-and-load method of accessing HTML (Figure 13-3, top) with a more responsive method that simply replaces content on the current page with new HTML (Figure 13-3, bottom). OVERVIEW To get a handle on what you’ll be doing in this tutorial, you first need to understand the HTML of the page you’re about to “Ajaxify.” Take a look at Figure 13-4: The page has a bulleted list of links, each of which points to a different page containing different news headlines. The <ul> tag used to create the list has the ID newslinks. In addition, there’s an empty <div> tag in the right sidebar (below the “News Headlines” header). That div has an ID of headlines and is, at this point, an empty placeholder. Eventually, once you use jQuery’s load() function, clicking one of the links will load news stories into the <div>. Currently, clicking a link just opens a web page with a series of news items. In other words, this page works the regular HTML way—it has links that point to other pages. In fact, without the nifty JavaScript you’re about to add, the page works perfectly fine—it’ll get any visitors to the news they’re after. That’s a good thing, because not everyone has JavaScript enabled in their browsers. In addition, if the only way to get to those news items is through JavaScript, search engines would skip over that valuable content. FIGURE 13-4 When you want to use JavaScript to add content to a page, it’s common to insert an empty <div> tag with an ID. You can then select that <div> and insert content when you want. For example, this page has an empty div (<div id="headlines">) in the right sidebar. With a little Ajax power, it’s a simple matter to fill that div with the contents of any of the three linked pages listed in the middle of the page. 458 JAVASCRIPT & JQUERY: THE MISSING MANUAL NOTE Most browsers don’t let you use the load() method directly from your hard drive without a web server, so you need to set up a server on your computer (see the box on page 452) to follow along. At the time of this writing, Safari on the Mac does let you use the load() method without a web server. AJAX THE JQUERY WAY This tutorial provides an example of progressive enhancement—it functions just fine without JavaScript, but works even better with JavaScript. In other words, everyone can access the content, and no one’s left out. NOTE See the note on page 12 for information on how to download the tutorial files. THE PROGRAMMING To implement progressive enhancement, you’ll add JavaScript to “hijack” the normal link function, then get the URL of the link, and then download the link to the page and put its contents into the empty <div>. It’s as simple as that: 1. In a text editor, open the file load.html in the chapter13 folder. You’ll start by assigning a click event function to each of the links in the bulleted list in the main part of the page. The bulleted list (the <ul> tag) has an ID of newslinks, so you can easily use jQuery to select each of those links and assign a click() function to them. This file already links to the jQuery library, and it also has a <!--<script type="text/javascript"> tag with the $(document).ready() function in it. 2. Click in the empty line inside the $(document).ready() function, and type: $('#newslinks a').click(function() { }); The $('#newslinks a') is the jQuery way to select each of those links, and the .click() function lets you assign a function (an event handler) to the click event (page 152) if you need a refresher on events). The next step is to extract the URL from each link. 3. Inside the click() function (the blank line in step 2) type var url=$(this). attr('href'); and press Return to create an empty line. This line of code creates a new variable (url) and assigns it the value of the link’s href attribute. As you’ll recall from page 126, when you attach a function (like the click() function) to a jQuery selection ($('#newslinks a') in this case), jQuery loops through each element in the selection (each link) and applies the function to each one. The $(this) is just a way to get hold of the current element being worked on. In other words, $(this) will refer to a different link as jQuery loops through the collection of elements. The attr() function (discussed on page 137) can retrieve or set a particular element for a tag; in this case, the function extracts the href property to get the URL of the page the link points Chapter 13: Introducing Ajax 459 AJAX THE JQUERY WAY to. In the next step, you’ll use that URL along with the load() function to retrieve the page’s content and display it inside a <div> on the page. 4. Type $('#headlines').load(url); so the script looks like this: $('#newslinks a').click(function() { var url=$(this).attr('href'); $('#headlines').load(url); }); Remember that the empty <div> tag on the page—where the downloaded HTML will go—has an ID of headlines, so $('#headlines') selects that <div>. The load() function then downloads the HTML at the URL that the previous line of code retrieved, and then puts that HTML in the <div> tag. Yes, there’s actually lots of other stuff going on under the hood to make all that happen, but thanks to jQuery, you don’t have to worry about it. The page isn’t quite done yet. If you save the file and preview it in a web browser, you’ll notice that clicking one of the links doesn’t load new content onto the page—it actually leaves the current page and loads the linked page instead! What happened to the Ajax? It’s still there; it’s just that the web browser is following its normal behavior of loading a new web page when a link is clicked. To stop that, you have to prevent the browser from following the link. 5. Add a new empty line after the code you typed in the previous step and type return false; so the script now looks like this: $('#newslinks a').click(function() { var url=$(this).attr('href'); $('#headlines').load(url); return false; }); This simple step tells the web browser, “Hey, web browser, don’t follow that link.” It’s one way of preventing a browser from following its normal behavior in response to an event. You can also use jQuery’s preventDefault() function as described on page 165 to achieve the same effect. 6. Save the file. If you have a web server set up on your machine, you can preview the page in a web browser. Click the links to test it out. Now there’s another problem, as you can see in Figure 13-5. The load() function is working, but the page doesn’t look right. The load() function downloaded the entire web page and inserted it into the <div>. This caused some weird spacing issues and the banner “JavaScript & jQuery” is actually duplicated at the top of the page. What you really want is only a portion of that web page—the area containing the news items. Fortunately, the load() function can help here as well. 460 JAVASCRIPT & JQUERY: THE MISSING MANUAL AJAX THE JQUERY WAY FIGURE 13-5 jQuery’s load() function will download all of the HTML for a specified file and place it into an element on the current page. If the downloaded file includes unneeded HTML, like a duplicate banner, sidebar, and footer, the result can look like a page within a page. In this case, there’s a lot of extra space above the headline “Today’s News” and the banner at the top of the page has shifted— it is, in fact, a duplicate banner placed on top of the old banner! 7. Locate the line with the load() function and add + ' #newsItem' after url. The finished code should look like this: $('#newslinks a').click(function() { var url=$(this).attr('href'); $('#headlines').load(url + ' #newsItem'); return false; }); As described on page 457, you can specify which part of a downloaded file you want the load() function to add to the page. To do that, you add a space after the URL followed by a selector that identifies the part of the downloaded page you wish to display. Here’s how the code breaks down into bite-sized chunks: First, on each of the linked pages, there’s a <div> tag with the ID newsItem. That div contains the HTML you want—the news items. So you can tell the load() function to only insert that part of the downloaded HTML by adding a space followed by #newsItem to the URL passed to load(). For example, if you want to load the file today. html and place just the HTML inside the newsItem div inside the headlines div, you can use this code: $('#headlines').load('today.html #newsItem'); Chapter 13: Introducing Ajax 461 AJAX THE JQUERY WAY In this case, you need to combine two strings—the contents of the url variable and ' #newsItems' to get the proper code—so you use JavaScript’s string concatenation operator (the + symbol) like this: load(url + ' #newsItems'). (See page 36 if you need a refresher on how to combine two strings.) 8. Save the file. If you have a web server set up on your computer, you can preview the page in a web browser. Click the links to test it out. Now the news items—and only the news items—from each linked page should appear in the box in the middle of the page. Ajax in just a few lines of code! (You’ll find a completed version of the tutorial—complete_load.html—in the chapter13 file for reference.) The get() and post() Methods The load() method described in the previous section is a quick way to grab HTML from a web server and inject it into a page. But the server may not always return straight HTML—it may return a message, a code number, or data that you then need to process further using JavaScript. For example, if you want to use Ajax to get some database records, the server may return an XML file containing those records (see the box on page 471) or a JSON object (page 477). You wouldn’t just insert that data into the page—you first have to get the data and process it in some way to generate the HTML you want. jQuery’s get() and post() functions provide simple tools to send data to and retrieve data from a web server. As mentioned in step 2 on page 453, you need to treat the XMLHttpRequest object slightly differently when using either the GET or POST method. However, jQuery takes care of any differences between the two methods so the get() and post() functions work identically. (So which should you use? Read the box on page 464.) The basic structure of these functions is: $.get(url, data, callback); Or: $.post(url, data, callback); Unlike most other jQuery functions, you don’t add get() or post() to a jQuery selector—in other words, you’d never do something like this: $('#mainContent'). get('products.php'). The two functions stand by themselves and aren’t connected to any element on the page, so you just use the $ symbol, followed by a period, followed by either get or post: $.get(). The get() and post() functions accept three arguments: url is a string that contains the path to the server-side resource that processes the data (for example, 'processForm.php'). The data argument is either a string or a JavaScript object literal containing the data you want to send to the server (you’ll learn how to create this in the next section). Finally, callback is the function that processes the information returned from the server (see the page 194 for details on writing a callback function). 462 JAVASCRIPT & JQUERY: THE MISSING MANUAL When either the get() or post() function runs, the web browser sends a request, using the specified method, to the specified URL, with the specified data. When the server sends data back to the browser, the browser hands that data to the callback function, which then processes that information and usually updates the web page in some way. You’ll see an example of this in action on page 471. AJAX THE JQUERY WAY Formatting Data to Send to the Server Most of the time when writing a JavaScript program that uses Ajax, you’ll be sending some information to the server. For example, if you want to get information about a particular product stored in a database, you could send a single number representing a product. When the web server gets the number from the XHR request, it looks for a product in the database that matches that number, retrieves the product information, and sends it back to the web browser. Or, you might use Ajax to submit an entire form’s worth of information as part of an online order or a “sign up for our email newsletter” form. In either case, you need to format the data for your request in a way that the get() and post() functions understand. The second argument sent to either function contains the data you wish to send the server—you can format this data either as a query string or as a JavaScript object literal, as described in the next two sections. QUERY STRING You’ve probably seen query strings before: They frequently appear at the end of a URL following a ? symbol. For example, in this URL http://www.chia-vet.com/ products.php?prodID=18&sessID=1234, the query string is prodID=18&sessID=1234. This query string contains two name/value pairs, prodID=18 and sessID=1234. This string does basically the same as creating two variables, prodID and sessID, and storing two values into them. A query string is a common method for passing information in a URL. You can also format data sent to the server using Ajax in this format. For example, say you’ve created a web page that lets visitors rate movies by clicking a number of stars. Clicking five stars, for instance, submits a rating of five to the server. In this case, the data sent to the server might look like this: rating=5. Assuming the name of the page processing these ratings is called rateMovie.php, the code to send the rating to the server using Ajax would look like this: $.get('rateMovie.php','rating=5'); Or, if you’re using the POST method: $.post('rateMovie.php','rating=5'); NOTE jQuery’s get() and post() functions don’t require you to define data or a callback function. You only need to supply the URL of the server-side page. However, you’ll almost always provide data as well. For example, in this code $.get('rankMovie.php','rating=5'); only the URL and the data are supplied—no callback function is specified. In this case, the visitor is merely submitting a ranking, and there’s no need for the server to respond or for a callback function to do anything. Chapter 13: Introducing Ajax 463 AJAX THE JQUERY WAY FREQUENTLY ASKED QUESTION GET or POST? The two methods for submitting data to a web server, GET and POST, seem pretty much the same. Which should I use? The answer really depends. In some cases, you don’t have a choice. For example, suppose you’re sending information to a server-side script that’s already up and running on your server. In other words, the server-side programming is already done, and you just need to use JavaScript to talk to it. In that case, you use the method that the script is expecting. Most likely, the programmer set up the script to accept either GET or POST data. So you can either talk to the programmer or look at the script to see which method it uses, then use the jQuery function that matches—either get() or post(). If you (or another programmer) haven’t yet written the serverside script that your JavaScript program will talk to, then you get to choose the method. The GET method is suited to requests that don’t affect the state of a database or files on the server. In other words, use it when you want to get information, like requesting the price of a particular product or obtaining a list of most popular products. The POST method is for sending data that will change information on the server, like a request to delete a file, update a database, or insert new information into a database. In reality, you can use either method, and often programmers will use a GET method to delete database information, and the POST method just to retrieve information from the server. However, there is one situation where POST is required. If you’re submitting a lot of form data to a server—for example, a blog post that might include hundreds of words—use POST. The GET method has a built-in limit on the amount of data it can send (this limit varies from browser to browser but Internet Explorer’s limit is several thousand characters). Most of the time, web designers use POST for forms that include more than just a few fields. If you need to send more than one name/value pair to the server, insert an & between each pair: $.post('rateMovie.php','rating=5&user=Bob'); You need to be careful using this method, however, because some characters have special meaning when you insert them into a query string. For instance, you use the & symbol to include additional name/value pairs to the string; the = symbol assigns a value to a name. For example, the following query string isn’t valid: 'favFood=Mac & Cheese' // incorrect The & symbol here is supposed to be part of “Mac & Cheese,” but when used as part of a query string, the & will be interpreted to mean a second name/value pair. If you want to use special characters as part of the name or value in a name/value pair, you need to escape or encode them so they won’t be mistaken for a character with special meaning. For example, the space character is represented by %20, the & symbol by %26, and the = sign by %3D. So you need to write out the “Mac & Cheese” example like this: 'favFood=Mac%20%26%20Cheese' // properly escaped 464 JAVASCRIPT & JQUERY: THE MISSING MANUAL JavaScript provides a method for properly escaping strings—the encodeURIComponent() method. You supply the encodeURIComponent() method with a string, and it returns a properly escaped string. For example: AJAX THE JQUERY WAY var queryString = 'favFood=' + encodeURIComponent('Mac & Cheese'); $.post('foodChoice.php', queryString); OBJECT LITERAL For short and simple pieces of data (that don’t include any punctuation symbols), the query string method works well. But a more foolproof method supported by jQuery’s get() and post() functions is to use an object literal to store data. As you’ll recall from page 136, an object literal is a JavaScript method for storing name/value pairs. The basic structure of an object literal is this: { name1: 'value1', name2: 'value2' } You can pass the object literal directly to the get() or post() function. For example, this code uses the query string method: $.post('rankMovie.php','rating=5'); To use an object literal, rewrite the code like this: $.post('rankMovie.php', { rating: 5 }); You can either pass the object literal directly to the get() or post() functions, or first store it in a variable and pass that variable to get() or post(): var data = { rating: 5 }; $.post('rankMovie.php', data); Of course, you can include any number of name/value pairs in the object that you pass to the get() or post() function: var data = { rating: 5, user: 'Bob' } $.post('rankMovie.php', data); Or, if you directly pass an object literal to $.post(): $.post('rankMovie.php', { rating: 5, user: 'Bob' } ); // end post Chapter 13: Introducing Ajax 465 AJAX THE JQUERY WAY JQUERY’S SERIALIZE() FUNCTION Creating a query string or object for an entire form’s worth of name/value pairs can be quite a chore. You have to retrieve the name and value for each form element, and then combine them all to create one long query string or one large JavaScript object literal. Fortunately, jQuery provides a function that makes it easy to convert form information into data that the get() and post() functions can use. You can apply the serialize() function to any form (or even just a selection of form fields) to create a query string. To use it, first create a jQuery selection that includes a form, then attach the serialize() function to it. For example, say you have a form with an ID of login. If you wanted to create a query string for that form, you can do so like this: var formData = $('#login').serialize(); The var formData part just creates a new variable; $('#login') creates a jQuery selection containing the form; finally, .serialize() collects all of the field names and the values currently in each field and creates a single query string. To use this with either the get() or post() functions, just pass the serialized results to the function as the second argument (the argument that follows the URL). For example, say you want to send the contents of the login form to a page named login. php. You can do so like this: var formData = $('#login').serialize(); $.get('login.php',formData,loginResults); This code sends whatever the visitor enters into the form to login.php using the GET method. The final argument for get() here—loginResults—is the callback function: the function that takes the data sent back from the server and does something with it. You’ll learn how to create a callback function next. Processing Data from the Server Ajax is usually a two-way street—a JavaScript program sends some data to the server and the server returns data to the JavaScript program, which can then use that data to update the page. In the previous pages, you saw how to format data and send it to a server using the get() and post() functions. Now you’ll learn how to receive and process the server’s response. When the web browser sends off a request to the server using the XMLHttpRequest object, it keeps listening for a response from the server. When the server responds, a callback function handles the server’s response. That function is passed several arguments that can be used by the function. First, and most important, the data returned by the server is sent as the first argument. You can format the data the server returns in any number of ways. The server-side script can return a number, a word, a paragraph of text, or a complete web page. In cases where the server is sending a lot of information (like a bunch of records from a database), the server often uses XML or JSON. (See the box on page 471 for more about XML; see page 477 for a discussion of JSON.) 466 JAVASCRIPT & JQUERY: THE MISSING MANUAL The second argument to the callback function is a string indicating the status of the response. Most of the time, the status is “success,” meaning that the server has successfully processed the request and returned data. However, sometimes a request doesn’t succeed—for example, the request was made for a file that doesn’t exist, or there was an error in the server-side programming. If a request fails, the callback function receives an “error” status message. AJAX THE JQUERY WAY The callback function processes the information, and, most of the time, updates the web page in some way—replacing a submitted form with results from the server, or simply printing a “request successful” message on the page, for example. Updating the content of a web page is easy using jQuery’s html() and text(), functions described on page 127. Other methods of manipulating a page’s DOM are discussed in Chapter 4. To get a handle on a complete request/response cycle, take a look at a basic movierating example (Figure 13-6). A visitor can rate a movie by clicking one of five links. Each link indicates a different rating. When the visitor clicks a link, the rating and ID of the movie being rated are sent to a server-side program, which adds the rating to the database, and then returns the average rating for that movie. The average rating is then displayed on the web page. In order for this page to work without JavaScript, each of the links on the page points to a dynamic server-side page that can process the visitor’s rating. For example, the five-star rating link (Figure 13-6) might be rate.php?rate=5&movie=123. The name of the server-side file that processes the ratings is called rate.php, while the query string (?rate=5&movie=123) includes two pieces of information for the server: a rating (rate=5) and a number that identifies the movie being rated (movie=123). You can use JavaScript to intercept clicks on these links and translate them into Ajax calls to the server: 1 2 3 4 5 6 $('#message a').click(function() { var href=$(this).attr('href'); var querystring=href.slice(href.indexOf('?')+1); $.get('rate.php', querystring, processResponse); return false; // stop the link }); Line 1 selects every link (<a> tag) inside of another tag with an ID of message (in this example, each link used to rate the movie is contained within a <div> with the ID message). A function is then applied to the click event for each of those links. Line 2 extracts the href attribute of the link—so, for example, the href variable might hold a URL like rate.php?rate=5&movie=123. Line 3 extracts just the part after the ? in the URL using the slice() method (discussed on page 545) to extract part of the string, and the indexOf() method (page 543) to determine where the ? is located (this information is passed to the slice() method to determine where to start slicing). Line 4 is the Ajax request. Using the GET method, a request containing the query string for the link is sent to the server resource rate.php (Figure 13-7). The results Chapter 13: Introducing Ajax 467 AJAX THE JQUERY WAY will then go to the callback function processResponse. Line 5 just stops the normal link behavior and prevents the web browser from unloading the current page and loading the linked-to page. FIGURE 13-6 On this page, a visitor clicks a link to rate the movie (top). By adding Ajax to the mix, you can submit the rating to the server without leaving the page. In fact, using the response from the server, you can update the page’s contents (bottom). NOTE If you need a refresher on how functions work and how to create them, see page 85. Finally, it’s time to create the callback function. The callback function receives data and a string with the status of the response ('success' if the server sent information back). Remember the callback function’s name is used in the request (see line 4 of the code on the previous page). So in this example, the function’s name is processResponse. The code to deal with the server’s response might look like this: 468 JAVASCRIPT & JQUERY: THE MISSING MANUAL 1 2 3 4 5 6 7 AJAX THE JQUERY WAY function processResponse(data) { var newHTML; newHTML = '<h2>Your vote is counted</h2>'; newHTML += '<p>The average rating for this movie is '; newHTML += data + '.</p>'; $('#message').html(newHTML); } FIGURE 13-7 This diagram shows how JavaScript and the web server interact. The $.get() method sends information to the server, while the callback function—processResponse()— handles the information returned by the server. The function accepts data arguments, which is the information returned by the web server. This data could be plain text, HTML, XML, or JSON. Line 2 creates a new variable that holds the HTML that will be displayed on the page (for example, “Your vote is counted”). In lines 3 and 4, the newHTML variable is filled with some HTML, including an <h2> tag and a <p> tag. The server’s response doesn’t come into play until line 5—there the response from the server (stored in the data variable) is added to the newHTML variable. In this case, the server returns a string with the average rating for the movie: for example, '3 stars'. NOTE If you want to add a star rating system to your site, there’s a great jQuery plug-in that handles most of the details: http://www.wbotelhos.com/raty/. Finally, line 6 modifies the HTML on the web page using jQuery’s html() function (page 127) by replacing the contents of the <div> with the ID of message with the new HTML. The result is something like the bottom image in Figure 13-6. In this example, the callback function was defined outside of the $.get() method; however, you can use an anonymous function (page 138) if you want to keep all of the Ajax code together: Chapter 13: Introducing Ajax 469 AJAX THE JQUERY WAY $.get('file.php', data, function(data,status) { // callback function programming goes here }); For example, you could rewrite line 4 on page 467 to use an anonymous function like this: $.get('rate.php', querystring, function(data) { var newHTML; newHTML = '<h2>Your vote is counted</h2>'; newHTML += '<p>The average rating for this movie is '; newHTML += data + '.</p>'; $('#message').html(newHTML); }); // end get Handling Errors Unfortunately, things don’t always go as planned. When using Ajax to talk to a web server, things can go wrong. Maybe the web server is down for a moment, or a visitor’s Internet connection drops momentarily. If that happens, the $.get() and $.post() methods will fail without letting the visitor know. While this type of problem is rare, it’s best to be prepared and letting your visitors know that something has temporarily gone wrong can help them figure out what to do (like reload the page, try again, or come back later). To respond to an error, you simply add a .error() function to the end of the $.get() or $.post() functions. The basic structure looks like this: $.get(url, data, successFunction).error(errorFunction); For example, you could rewrite line 4 on page 467 to look like this: $.get('rate.php', querystring, processResponse).error(errorResponse); Then create a new function named errorResponse that notifies the visitor that there was a problem. For example: function errorResponse() { var errorMsg = "Your vote could not be processed right now. "; errorMsg += "Please try again later."; $('#message').html(errorMsg); } In this case, the function errorResponse runs only if there’s some kind of error with the server or the server’s connection. NOTE The .error() method doesn’t work with jQuery’s .load() method, or with a request to another website using JSONP (page 483). 470 JAVASCRIPT & JQUERY: THE MISSING MANUAL Tutorial: Using the $.get() Method In this tutorial, you’ll use Ajax to submit information from a login form. When a visitor supplies the correct username and password, a message will appear letting her know she’s successfully logged in. If the login information isn’t correct, an error message will appear on the same page—without loading a new web page. AJAX THE JQUERY WAY NOTE In order to successfully complete this tutorial, you’ll need to have a running AMP (Apache, MySQL, and PHP) web server to test the pages on. See the box on page 452 for information on how to set up a testing server on your computer. POWER USERS’ CLINIC Receiving XML from the Server XML is a common format for exchanging data between computers. Like HTML, XML lets you use tags to identify information. Unlike HTML, you’re free to come up with tags that accurately reflect the content of your data. For example, a simple XML file might look like this: <?xml version="1.0" ?> <message id="234"> <from>Bob</from> <to>Janette</to> <subject>Lunch</subject> <content>Janette, let's grab lunch today.</content> </message> For example, say a server-side resource named xml.php returned the sample XML listed here, and you want to retrieve the text within the <content> tag. The XML file becomes the returned data, so the callback function can process it. You can use the jQuery find() function to search the XML to find a particular CSS element using any of the regular selectors you’d use with jQuery. For example, you can find an element, class, ID, descendant selector (page 122), or jQuery’s filters (page 124). For example: As you can see, there’s a main tag (called the root element) named <message>—the equivalent of HTML’s <html> tag—and several other tags that define the meaning of each piece of data. When using Ajax, you might have a server program that returns an XML file. jQuery has no problem reading and extracting data from an XML file. When you use the $.get() or $.post() methods, if the server returns an XML file, the data argument that’s sent to the callback function will contain the DOM of the XML file. In other words, jQuery will read the XML file and treat it like another document. You can then use jQuery’s selector tools to access the data inside the XML. $.get('xml.php','id=234',processXML); function processXML(data) { var messageContent=$(data find('content').text(); } The key here is $(data).find('content'), which tells jQuery to select every <content> tag within the data variable. In this case, the data variable contains the returned XML file, so this code tells jQuery to look for the <content> tag within the XML. To learn more about XML, visit http://www.learn-xml-tutorial. com/xml-basics.cfm. To learn more about jQuery’s find() function, visit http://api.jquery.com/find. Chapter 13: Introducing Ajax 471 AJAX THE JQUERY WAY OVERVIEW You’ll start with the form pictured in Figure 13-8. It includes fields for supplying a username and password to the server. When the form is submitted, the server attempts to verify that the user exists and the password matches. If the information supplied matches valid login credentials, then the server logs the visitor in. FIGURE 13-8 A basic login page is a simple affair: just a couple of fields and a Submit button. However, there’s really no reason to leave the page when the user logs in. By adding Ajax, you can submit the visitor’s credentials, then notify whether he logged in successfully or not. You’ll add Ajax to the form by sending the login information via an XMLHttpRequest. The server will send a message to the callback function, which removes the form and displays a “logged in” message if the login information is valid, or an error message if it’s not. THE PROGRAMMING See the note on page 12 for information on how to download the tutorial files. The starting file contains the HTML form, ready for you to add some jQuery and Ajax programming: 1. In a text editor, open the file login.html in the chapter13 folder. The link to the jQuery library file and the $(document).ready() function are already in place. You’ll start by using jQuery to select the form and adding a submit event to it. 2. Click in the empty line inside the $(document).ready() function and type: $('#login').submit(function() { }); // end submit 472 JAVASCRIPT & JQUERY: THE MISSING MANUAL The <form> tag has the ID login applied to it, so the jQuery selector— $('#login')—selects that form, while the submit() function adds an event handler to the submit event. In other words, when a visitor tries to submit the form, the function you’re about to create will run. AJAX THE JQUERY WAY The next step is to collect the information from the form and format it as a query string to submit to the server. You could do this by finding each form field, extracting the value that the visitor had typed in, then constructing a query string by concatenating those different pieces of information. Fortunately, jQuery’s serialize() method takes care of all these details in one shot. 3. Hit Return to create an empty line and type: var formData = $(this).serialize(); This line starts by creating a new variable to hold the form data, and then applies the serialize() method to the form. Recall that $(this) refers to the current element, so in this case it refers to the login form, and is the same as $('#login') (see page 139 for more on how $(this) works). The serialize() method (page 466) takes a form and extracts the field names and values and puts them in the proper format for submitting to the server. Now you’ll use the $.get() method to set up and send the XMLHttpRequest. 4. Hit Return to create another empty line and type: $.get('login.php',formData,processData); This code passes three arguments to the $.get() method. The first—'login. php'—is a string identifying where the data should be sent—in this case, a file on the server named login.php. The second argument is the query string containing the data that’s being sent to the server—the login information. Finally, processData refers to the callback function that will process the server’s response. You’ll create that function now. 5. Add another blank line below the last one and type: 1 2 3 function processData(data) { } // end processData These lines form the shell of the callback function; there’s no programming inside it yet. Notice that the function is set up to accept one argument (data), which will be the response coming from the server. The server-side page is programmed to return a single word—pass if the login succeeded, or fail if the login failed. In other words, based on the response from the server, the script will either print a message letting the visitor know he’s successfully logged on, or that he hasn’t—this is the perfect place for a conditional statement. Chapter 13: Introducing Ajax 473 AJAX THE JQUERY WAY NOTE The server-side page used in this tutorial isn’t a full-fledged login script. It does respond if the proper credentials are supplied, but it’s not something you could use to actually password-protect a site. There are many ways to effectively password protect a site, but most require setting up a database or setting up various configuration settings for the web server—these steps are beyond this basic tutorial. For a real, PHP-based login script, visit http://www.wikihow.com/Create-a-Secure-Login-Script-in-PHP-and-MySQL. 6. Inside the processData() function, add the bolded code: 1 function processData(data) { 2 if (data === 'pass') { 3 $('.main').html('<p>You have successfully logged on!</p>'); 4 } 5} // end processData Line 1 checks to see whether the information returned from the server is the string 'pass'. If it is, the login was successful and a success message is printed (line 2). The form is inside a <div> tag with the class of main, so $('.main'). html('<p>You have successfully logged on!</p>') will replace whatever’s inside that <div> with a new paragraph. In other words, the form disappears and the success message appears in its place. To finish up, you’ll add an else clause to let the visitor know if he didn’t supply the correct login information. 7. Add an else clause to the processData() function so it looks like this (additions are in bold): 1 2 3 4 5 6 7 function processData(data) { if (data=='pass') { $('#content').html('<p>You have successfully logged on!</p>'); } else { $('#formwrapper').prepend('<p id="fail">Incorrect ↵ login information. Please try again</p>'); } } // end processData Line 5 prints the message that the login failed. Notice that the prepend() function is used. As discussed on page 127, prepend() lets you add content to the beginning of an element. It doesn’t remove what’s already there; it just adds more content. In this case, you want to leave the form in place, so the visitor can try again to log in a second time. 8. Save the file, and preview it in a web browser. You must view this page through a web browser using a URL, like http://localhost/chapter13/login.html, for this tutorial to work. See the box on page 452 for more information on how to set up a web server. 474 JAVASCRIPT & JQUERY: THE MISSING MANUAL 9. Try to log into the site. “But wait—you haven’t given me the username and password yet!” you’re probably thinking. That’s the point—to see what happens when you don’t log in correctly. Try to log in a second time: You’ll see the “Incorrect login information” message appear a second time (Figure 13-9). Because the prepend() function doesn’t remove the first error message, it just adds the message a second time. That doesn’t look right at all. AJAX THE JQUERY WAY You have several ways to deal with this problem. You could, for example, insert an empty div—<div id="failMessage">—below the form. Then simply replace its HTML when the login fails. However, in this case, there’s no empty div tag on the page. Instead, use a basic conditional statement to check whether the error message already exists—if it does, there’s no need to add it a second time. FIGURE 13-9 jQuery’s prepend() function adds HTML to an already existing element. It doesn’t delete anything, so if you’re not careful, you may end up adding the same message over and over again. 10. Add another conditional statement (lines 5 and 7): 1 2 3 4 5 6 7 8 9 10 function processData(data) { if (data=='pass') { $('.main').html('<p>You have successfully logged on!</p>'); } else { if ($('#fail').length === 0) { $('#formwrapper').prepend('<p id="fail">Incorrect ↵ login information. Please try again</p>'); } } } // end processData Chapter 13: Introducing Ajax 475 AJAX THE JQUERY WAY Notice that the error message paragraph has an ID—fail—so you can use jQuery to check to see if that ID exists on the page. If it doesn’t, then the program writes the error message on the page. One way to check if an element already exists on the page is to try to use jQuery to select it. You can then check the length attribute of the results. If jQuery couldn’t find any matching elements, the length attribute is 0. In other words, $('#fail') tries to find an element with the ID fail. If jQuery can’t find it—in other words, the error message hasn’t yet been written to the page—then the length attribute is 0, the conditional statement will be true, and the program writes the error message. Once the error message is on the page, the conditional statement always evaluates to false, and the error message doesn’t appear again. Finally, you need to tell the web browser that it shouldn’t submit the form data itself—you already did that using Ajax. 11. Add return false; at the end of the submit event (line 15). The finished script should look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 $(document).ready(function() { $('#login').submit(function() { var formData = $(this).serialize(); $.post('login.php',formData,processData); function processData(data) { if (data=='pass') { $('.main').html('<p>You have successfully logged on!</p>'); } else { if ($('#fail').length === 0) { $('#formwrapper').prepend('<p id="fail">Incorrect ↵ login information. Please try again</p>'); } } } // end processData return false; }); // end submit }); // end ready 12. Save the file and preview the page once again. Try to log in again: the username is 007 and the password is secret. A completed version of this tutorial, complete_login.html, is in the chapter13 folder. NOTE As mentioned on page 462, you use jQuery’s $.post() and $.get() functions identically even though, behind the scenes, jQuery has to do two different set of steps to make the Ajax request work correctly. You can check this out yourself by just changing get to post in the script (see line 4 in step 11). The server-side script for this tutorial is programmed to accept either GET or POST requests. 476 JAVASCRIPT & JQUERY: THE MISSING MANUAL JSON JSON Another popular format for sending data from the server is called JSON, which stands for JavaScript Object Notation. JSON is a data format that’s structured like a JavaScript object. It’s kind of like XML (see the box on page 471) in that it’s a method for exchanging data. JSON is a string that’s formatted just like a JavaScript object: browsers can quickly and easily convert JSON into real JavaScript. XML, on the other hand, needs to be parsed into a series of “nodes” that JavaScript needs to traverse to access the data inside the XML document: this process is generally slower and requires more programming. Because of this, JSON is a more common choice for exchanging data using Ajax. In essence, JSON is very similar to a JavaScript object literal, or a collection of name/ value pairs. Here’s a simple example of JSON: { "firstName" : "Frank", "lastName" : "Smith", "phone" : "503-555-1212" } The { marks the beginning of the JSON object, while the } marks its end. In between are sets of property name/value pairs; for example, "firstName": "Frank". The property name is separated from the property value by a colon. Unlike a regular JavaScript object, JSON property names must be quoted using double quotations, and all string values must be quoted with double quotes. In other words, the following is incorrect: firstName : 'Frank' While this is correct: "firstName" : "Frank" Like JavaScript objects, every property name/value pair is separated by a comma, but don’t put a comma at the end of the last pair (otherwise, some versions of Internet Explorer will cough up an error). Think of a name/value pair just like a variable—the name is like the name of the variable, and the value is what’s stored inside that variable. In the above example, "lastName" acts like a variable, with the string "Smith" stored in it. When the web server responds to an Ajax request, it doesn’t actually send JavaScript: It just sends text that’s formatted like a JavaScript object—that’s what JSON is. It isn’t actually real, usable JavaScript until the string is converted into an actual JavaScript object. Fortunately, jQuery provides a special function, $.getJSON(), that handles all of the details. The $.getJSON() method looks and works much like the $.get() and $.post() functions. The basic structure looks like this: $.getJSON(url, data, callback); Chapter 13: Introducing Ajax 477 JSON The three arguments passed to the function are the same as for $.post() or $.get()—the URL of the server-side page, data to send to the server-side page, and the name of a callback function. The difference is that $.getJSON() will process the response from the server (which is just a JSON-formatted string) and convert it (through some JavaScript wizardry) into a usable JavaScript object. In other words, $.getJSON() works just like $.post() or $.get(), but the data passed to the callback is a JSON string. To use the $.getJSON() function, then, you only need to learn how to process the JavaScript object with the callback function. For a basic example, say you want to use Ajax to request information on a single contact from a server-side file named contacts.php; that file returns contact data in JSON format (like the JSON example on the previous page). A basic request would look like this: $.getJSON('contacts.php','contact=123',processContacts); This code sends a query string—contact=123—to contacts.php. Say the contacts. php file uses that information to locate a single contact in a database and retrieve that contact’s information. The result is sent back to the web browser and handed to the callback function processContacts. The basic structure of the callback, then, would look like this: function processContacts(data) { } The processContacts() function has one argument—data—that contains the JavaScript object from the server. Next, you’ll take a look at how the callback can access information from that object. Accessing JSON Data There are two ways to access data in the object converted from the JSON string: dot syntax or array notation. Dot syntax (page 56) is a way of indicating an object’s property—specifically, by adding a period between the name of the object and the property you wish to access. You’ve seen this in use with properties of different JavaScript objects like strings and arrays. For example, 'abc'.length accesses the string’s length property, and, in this example, returns the number of letters in the string 'abc', which is 3. For example, suppose you create a variable and store an object literal inside it like this: var bdate = { "person" : "Raoul", "date" : "10/27/1980" }; In this case, the variable bdate contains the object literal, so if you want to get the value of person in the object, use dot syntax like this: bdate.person // "Raoul" 478 JAVASCRIPT & JQUERY: THE MISSING MANUAL To get the birth date: JSON bdate.date // "10/27/1980" The same is true with JSON data that’s returned by the web server. For example, take the following $.getJSON() example and callback function: $.getJSON('contacts.php','contact=123',processContacts); function processContacts(data) { } Assuming that the server returned the JSON example on page 477, that JSON object is assigned to the variable data (the argument for the callback function processContacts()), just as if this code had been executed: var data = { "firstName" : "Frank", "lastName" : "Smith", "phone" : "503-555-1212" }; Now within the callback function, you can access the value of firstName like this: data.firstName // "Frank" And retrieve the last name of the contact like this: data.lastName // "Smith" So, say the whole point of this little Ajax program is to retrieve contact information and display it inside of a <div> with the ID info. All of the programming for that might look like this: $.getJSON('contacts.php','contact=123',processContacts); function processContacts(data) { var infoHTML='<p>Contact: ' + data.firstName; infoHTML+=' ' + data.lastName + '<br>'; infoHTML+='Phone: ' + data.phone + '</p>'; $('#info').html(infoHTML); } The final outcome would be a paragraph added to the page that looks something like this: Contact: Frank Smith Phone: 503-555-1212 Complex JSON Data You can create even more complex collections of information by using object literals as the values inside a JSON-encoded string—in other words, object literals nested within object literals. Here’s an example: Say you want the server to send back Chapter 13: Introducing Ajax 479 JSON contact information for more than one individual using JSON. You’ll send a request to a file named contacts.php with a query string that dictates how many contacts you wish returned. That code may look something like this: $.getJSON('contacts.php','limit=2',processContacts); The limit=2 is the information sent to the server, and indicates how many contacts should be returned. The web server would then return two contacts. Say the contact info for the first person matched the preceding example (Frank Smith), and a second set of contact information was another JSON object like this: { "firstName" : "Peggy", "lastName" : "Jones", "phone" : "415-555-5235" } The web server may return a JSON string that represents a single object, which combines both of these objects like this: { "contact1": { "firstName" : "Frank", "lastName" : "Smith", "phone" : "503-555-1212" }, "contact2": { "firstName" : "Peggy", "lastName" : "Jones", "phone" : "415-555-5235" } } Assume that the callback function accepts a single parameter named data (for example, function processContacts(data)). The variable data would then be assigned that JSON object, just as if this code had been executed: var data = { "contact1": { "firstName" : "Frank", "lastName" : "Smith", "phone" : "503-555-1212" }, "contact2": { "firstName" : "Peggy", "lastName" : "Jones", "phone" : "415-555-5235" } } 480 JAVASCRIPT & JQUERY: THE MISSING MANUAL Now, you could access the first contact object within the callback function like this: JSON data.contact1 And retrieve the first name of the first contact like this: data.contact1.firstName But, in this case, because you want to process multiple contacts, jQuery provides a function that lets you loop through each item in an object—the $.each() method. The basic structure of the function is this: $.each(JSON,function(name,value) { }); You pass the JSON data, and a function to the $.each() method. That anonymous function receives the name and value of each item in the object. Here’s how the JSON data would look in use in the current example: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 $.getJSON('contacts.php','limit=2',processContacts); function processContacts(data) { // create variable with empty string var infoHTML=''; //loop through each object in the JSON data $.each(data,function(contact, contactInfo) { infoHTML+='<p>Contact: ' + contactInfo.firstName; infoHTML+=' ' + contactInfo.lastName + '<br>'; infoHTML+='Phone: ' + contactInfo.phone + '</p>'; }); // end of each() // add finished HTML to page $('#info').html(infoHTML); } Here’s how the code breaks down: 1. Line 1 creates the Ajax request with data (limit=2) and assigns the callback function (processContacts). 2. Line 2 creates the callback function, which accepts the JSON object sent back from the server and stores it in the variable data. 3. Line 4 creates a variable containing an empty string. The HTML that eventually gets added to the page will fill it. 4. Line 7 is the $.each() method, which will look through the objects in the JSON data. The $.each() method takes the JSON data as its first argument (data) and an anonymous function as the second argument. The process is diagrammed in Chapter 13: Introducing Ajax 481 JSON Figure 13-10. Essentially, for each of the main objects (in this example, contact1 and contact2), the anonymous function receives the name of the object as a string (that’s the contact argument listed in line 7) and the value for that object (that’s the contactInfo argument). In this case, the contactInfo variable will hold the object containing the contact information. 5. Lines 8–10 extract the information from one contact. Remember that the $.each() method is a loop, so lines 8–10 will run twice—once for each of the contacts. FIGURE 13-10 You can use jQuery’s each() function to loop through a JavaScript object to perform tasks on nested objects. You can also use the each() function to loop through arrays. To learn more about this useful function, visit http:// docs.jquery.com/Utilities/jQuery. each#objectcallback. 6. Line 14 updates the web page by adding the HTML to the page. The final result will be the following HTML: <p>Contact: Frank Smith<br> Phone: 503-555-1212</p> <p>Contact: Peggy Jones<br> Phone: 415-555-5235</p> 482 JAVASCRIPT & JQUERY: THE MISSING MANUAL INTRODUCING JSONP Introducing JSONP For security reasons, Ajax requests are limited to requests to the same origin. That is, the page making an Ajax request must be on the same server as the page responding to the request. This policy is enforced by web browsers to keep one site from using JavaScript to maliciously contact another site (like your bank). There’s one way around that, though. While a web browser can’t send an XML HTTP request to a different website, it can download resources from other sites, including pictures, style sheets, and external JavaScript files. JSONP (which stands for JSON with padding) provides one way to retrieve information from another site. Instead of making an Ajax request of the foreign site, you load a script that contains the JSON code in it. In other words, it’s like linking to an external JavaScript file on another website. You can’t request just any bit of information that you’d like from another site, however. For JSONP to work, the foreign site must be set up to respond with JSONP. Most sites aren’t set up to send information this way, but many of the big sites like Google Maps, Twitter, Flickr, Facebook, Netflix, and YouTube offer an API (application programming interface) that lets you request data like a map, a photo, movie review text, and so on, using jQuery’s $.getJSON() method (Figure 13-11). FIGURE 13-11 While Ajax is restricted to requesting information from the same domain, the JSONP workaround lets you retrieve JSON data from another site by requesting a JavaScript file from that site. This technique lets you access tweets from Twitter, maps from Google, and photos from Flickr (pictured here) and embed them directly in your own web pages. Chapter 13: Introducing Ajax 483 ADDING A FLICKR FEED TO YOUR SITE Adding a Flickr Feed to Your Site Flickr has been around for years, allowing people to share photographs—the site currently hosts billions of photos and counting. A lot of websites like to include photos either taken by the site owner or within a Flickr group (a collection of photos submitted by multiple people around a common subject like web design, landscape photography, cat yawns, and so on). Flickr gives you a couple of ways to retrieve photos and related information. The most powerful, but also most complex, method is to use Flickr’s API to search for photos. This method requires that you sign up at Flickr and get a special API key (a string of numbers and letters that identifies you). It also requires some fancy programming to work. The simplest way is to use the Flickr Feed Service. Feeds are a way to keep people up to date with a site’s information. For example, you may have seen sites with RSS feeds that let you view the latest news and information from that website. Flickr offers a similar service for its photos—you can get a listing of the 20 most recent photos from a particular person or a particular group. In this section, you’ll use the feed method to get a collection of photos from Flickr and display them on a web page, and in the process, learn how to use jQuery’s $.getJSON() method to retrieve JSONP data from another website. Constructing the URL Flickr offers several different URLs for accessing feeds for different types of photos (see www.flickr.com/services/feeds/ for a full list). For example, you use https://api. flickr.com/services/feeds/photos_public.gne to access photos from specific Flickr accounts (such as your own account if you have one), as well as a link for retrieving photos from a particular group (like the Web Design group, which features photos and images to inspire awesome websites). Once you know which type of photo feed you’d like and the basic URL that accompanies it, you need to add some additional information to retrieve the photos you’re interested in. To do so, you add a query string with several pieces of information added on. (As you recall from page 463, a query string is a ? mark at the end of a URL, followed by one or more name/value pairs: https://api.flickr.com/services/ feeds/groups_pool.gne?id=25053835@N03&format=json, for example.) • Add one or more IDs. To select photos from a particular group or one or more individual accounts, you add id, plus an = sign followed by an individual or group account number. For example, to access a group photo feed for the Web Design group, you’d use this group photo feed and add the ID for the group, like this: https://api.flickr.com/services/feeds/ ↵ groups_pool.gne?id=37996591093@N01 For individual Flickr feeds, you’d use the public photos feed and use one or more IDs. For example, to retrieve photos from both the Smithsonian (which has its 484 JAVASCRIPT & JQUERY: THE MISSING MANUAL own Flickr account) and the Library of Congress, you can use the ids names and the public photo feed, like this: ADDING A FLICKR FEED TO YOUR SITE https://api.flickr.com/services/feeds/ ↵ photos_public.gne?ids=8623220@N02,25053835@N03 To use multiple IDs, separate each with a comma. Note that you can only use multiple IDs for retrieving individual accounts: You can’t use the group feed and retrieve photos from multiple groups. TIP If you know someone’s Flickr username, you can get his Flickr ID using this website: http://idgettr.com/. • Add the JSON format. The Flickr photo feed service is very flexible and can return photo information in many different formats from RSS to Atom, CSV, and JSON. To let Flickr know that you want data in JSON format, you need to add &format=json to the query string. For example, to get the a Flickr feed of the Smithsonian Museum’s Flickr photos in JSON format, you’d use this URL: https://api.flickr.com/services/feeds/ ↵ photos_public.gne?ids=25053835@N03&format=json Go ahead and type the URL above into a web browser (if you’re feeling lazy, you can copy and paste the URL from the flickr_json.txt file in the chapter13 folder of the tutorial files). You’ll see a bunch of data; actually, an object literal containing a bunch of information. That’s what you receive from Flickr when you use the $.getJSON() method (discussed on page 477). You need to use JavaScript to dissect that object and then use it to build a neat little gallery of images. (The structure of Flickr’s JSON feed is discussed on page 487, and taking apart the feed so you can use it is shown in the tutorial on page 488.) • Add a JSONP callback to the URL. Finally, for a page on your site to successfully request JSON data from another website, you need to add one last bit to the URL: &jsoncallback=?. Remember that for security reasons you can’t just send an XMLHTTP request to a different domain. To get around that problem, the &jsoncallback=? piece notifies Flickr that you want to receive JSONP data and lets jQuery’s $.getJSON() method treat this request as if the web browser were simply requesting an external JavaScript file. In other words, to receive a feed of the Smithsonian Museum’s latest Flickr photos, you’d need to pass the $.getJSON() method a URL, like this: https://api.flickr.com/services/feeds/ ↵ photos_public.gne?ids=25053835@ N03&format=json&jsoncallback=? FINDING PHOTOS OF SPECIFIC THINGS On Flickr, you can tag any photo with one or more words; a tag is a word or short phrase that describes an element of the photo. For example, you might tag a particularly bright photo of a sunset with the word “sunset.” Any photo can have multiple tags, so you might tag that sunset photo with the words “sunset, orange, beach.” Chapter 13: Introducing Ajax 485 ADDING A FLICKR FEED TO YOUR SITE Flickr’s feed service provides options that let you search a feed for specific tags: • tags. Add the tags keyword with one or more comma-separated keywords to the URL to specify a tag; for example: tags=fireworks,night. To search for photos of fireworks at night, you could then use this URL: https://api.flickr.com/services/feeds/ ↵ photos_public.gne?tags=fireworks,night&format=json&jsoncallback=? • tagmode. Normally when you search for a set of tags, Flickr retrieves photos that match all of the tags. For example, say you added ?tags=chipmunks,baseball,winter to a feed. This code finds only photos of chipmunks playing baseball in the winter. If you wanted pictures of chipmunks, or baseball, or the winter (in other words, at least one of the tags), add &tagmode=any to the URL. For example: https://api.flickr.com/services/feeds/ ↵ photos_public.gne?tags=chipmunk,baseball,winter ↵ &tagmode=any&format=json&jsoncallback=? COMBINING OPTIONS You can combine search options to refine the photo selection even more. For example, you can combine an ID with a tag, so you can find photos by a specific person and of a particular thing. For example, say you and a couple of friends like to take pictures of chipmunks and post them up on Flickr, and you want to get a feed of the 20 latest chipmunk photos you and your friends have taken. You can do this by filtering the feed by specifying one or more tags: https://api.flickr.com/services/feeds/ ↵ photos_public.gne?ids=25053835@N03,8623220@N02 ↵ &tags=chipmunk&format=json&jsoncallback=? Using the $.getJSON() Method Using the $.getJSON() method to retrieve a photo feed from Flickr works the same way as retrieving JSON data from your own site. The basic structure for the function is the same. For example, here’s the setup for retrieving the Smithsonian’s Flickr feed: 1 var flickrURL = "https://api.flickr.com/services/feeds/ ↵ gne?ids=25053835@N03&format=json&jsoncallback=?"; 2 $.getJSON(flickrURL, function(data) { 3 // do something with the JSON data returned 4 }); // end get photos_public. In this example, line 1 creates a variable named flickrURL and stores the URL (using the rules discussed in the previous section). Line 2 sends the Ajax request to the URL and sets up an anonymous function for processing that data. After sending an Ajax request, the code retrieves data back from the server—in this example, that data is sent to the anonymous function and is stored in the variable called data. You’ll learn how to process the data in a few pages, but first, you need to understand what Flickr’s JSON data looks like. 486 JAVASCRIPT & JQUERY: THE MISSING MANUAL Understanding the Flickr JSON Feed As discussed on page 477, JSON is simply a JavaScript object literal. It can be as simple as this: ADDING A FLICKR FEED TO YOUR SITE { "firstName" : "Bob", "lastName" : "Smith" } In this code, firstName acts like a key with a value of Bob—a simple string value. However, the value can also be another object (see Figure 13-10 on page 482), so you can often end up with a complex nested structure—like dolls within dolls. That’s what Flickr’s JSON feed is like. Here’s a small snippet of one of those feeds. It shows the information retrieved for two photos: 1 { 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 "title": "Uploads from Smithsonian Institution", "link": "http://www.flickr.com/photos/smithsonian/", "description": "", "modified": "2011-08-11T13:16:37Z", "generator": "http://www.flickr.com/", "items": [ { "title": "East Island, June 12, 1966.", "link": "http://www.flickr.com/photos/smithsonian/5988083516/", "media": {"m":"http://farm7.static.flickr.com/6029/5988083516_ bfc9f41286_m.jpg"}, "date_taken": "2011-07-29T11:45:50-08:00", "description": "Short description here", "published": "2011-08-11T13:16:37Z", "author": "nobody@flickr.com (Smithsonian Institution)", "author_id": "25053835@N03", "tags": "ocean birds redfootedbooby" }, { "title": "Phoenix Island, April 15, 1966.", "link": "http://www.flickr.com/photos/smithsonian/5988083472/", "media": {"m":"http://farm7.static.flickr.com/6015/5988083472_ c646ef2778_m.jpg"}, "date_taken": "2011-07-29T11:45:48-08:00", "description": "Another short description", "published": "2011-08-11T13:16:37Z", "author": "nobody@flickr.com (Smithsonian Institution)", "author_id": "25053835@N03", 28 29 30 31 } "tags": "" } ] Chapter 13: Introducing Ajax 487 TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE Flickr’s JSON object has a bit of information about the feed in general: That’s the stuff at the beginning—"title", "link", and so on. The "title" element (line 2) is the name of that feed. In this case, "Uploads from Smithsonian Institution"—the "link" element (line 3)—points to the main Flickr page for the Smithsonian Institution. You can use this information, for example, as a headline presented before displaying the photos. To access that information, you use the dot syntax described on page 56. For example, say you used the code from the previous section (page 486): The anonymous function used to process the data stores the JSON response in a variable named data (see line 2 on page 486). Then, to access the title of the feed, you’d access the "title" property of the "data" object like this: data.title The most important part of the feed is the "items" property (line 7), which contains additional objects, each containing information about one photo. For example, lines 8–18 provide information for one photo, while lines 19-29 are about another photo. Within each item object, you’ll find other properties like the title of the photo (line 9), a link to that photo’s Flickr page (line 10), the date the photo was taken (line 12), a description (the "Short description here" on line 13 [the curators at the Smithsonian must have been feeling a little lazy that day]), and so on. Another important element for each photo is "media"—it’s another object. For example: { "m":"http://farm7.static.flickr.com/6029/5988083516_bfc9f41286_m.jpg" } The "m" means “medium,” and its value is a URL to the photo. Flickr photos are often available in different sizes, like medium, thumbnail, and small (which is a small square image). If you want to display the image on a page, then this URL is what you’re after. You can use it to insert an <img> tag in the page and point to that photo on the Flickr server. You’ll see how in the tutorial. Tutorial: Adding Flickr Images to Your Site In this tutorial, you’ll put together all the pieces to retrieve the photo feed from the Smithsonian Institution, display thumbnail images of the photos, and add links to each image, so a visitor can click the thumbnail to go to Flickr and see the photos page. NOTE See the note on page 12 for information on how to download the tutorial files. 1. In a text editor, open the file flickr.html in the chapter13 folder. You’ll start by creating a few variables to store the components of the URL required to talk to Flickr. 488 JAVASCRIPT & JQUERY: THE MISSING MANUAL 2. Click in the empty line inside the $(document).ready() function, and type: TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE var URL = "https://api.flickr.com/services/feeds/photos_public. gne?jsoncallback=?"; This URL points to the public feed and includes the magic little bit— ?jsoncallback=?—that tells the Flickr website that it should send JSONP. In other words, this code tells Flickr to send a JavaScript file containing the photo information. Next, you’ll create an object to hold additional information to Flickr. Each variable here is just part of that much longer URL discussed on page 484. Breaking each piece into a separate variable makes it easy to adjust this code. For example, if you want to get a photo feed from another Flickr user, just change the ID variable. TIP If you have a Flickr account, go ahead and plug in your ID number in here. If you don’t know your Flickr ID, visit http://idgettr.com/ to find out. Next, you’ll put these variables together to construct a complete URL: 1. Add another line of code after the one you just typed: var searchInfo = { }; This line is an empty JavaScript object literal. As you read on page 477, you can pass additional information along with an Ajax request. The server can then use that information to modify its response. In this case, you want to provide the a Flickr user’s ID to find photos from just that user. 2. Inside the object, add one name/value pair (bolded): var searchInfo = { id : "25053835@N03" }; The Flickr API expects an ID for a particular user. In this case, the ID belongs to the Flickr account for the Smithsonian Institute. Note that you have to use lowercase—id—for the property name. If you want to get a photo feed from another Flickr user, just change the ID variable (again, if you have a Flickr account, you can use your own ID number). You also need to tell Flickr to send back JSON data. TIP If you want to retrieve the photos from a Flickr group, like the Web Design group, change the URL in step 2 to: https://api.flickr.com/services/feeds/groups_pool.gne?jsoncallback=? and the ID in step 4 to the ID of the Flickr group. Chapter 13: Introducing Ajax 489 TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE 3. Add a comma after the line with the id, hit Return and type format : "json": var searchInfo = { id : "25053835@N03", format : "json" }; If you don’t add this format part, you’ll get data back in XML format. Now it’s time to get into the Ajax part of this and use jQuery $.getJSON() function. 4. After the line you just added, type this: $.getJSON(ajaxURL, searchInfo, function(data) { }); // end get JSON; Here’s the basic shell of the $.getJSON() method: It will contact the URL you specified in step 2, send the search criteria you created in steps 3–5, and receive data back from Flickr. That data is passed to an anonymous function and stored in a variable named data. You can then take that data and begin to use it on the page. First, you’ll get the title of the feed and replace the <h1> tag that’s currently on the page with it. 5. Add the bolded line of code below to the code from the last step: $.getJSON(ajaxURL,function(data) { $('h1').text(data.title); }); // end get JSON; This line is a basic jQuery selector—$('h1')—and function—.text()—that selects the <h1> tag currently on the page and replaces the text inside it. The actual JSON feed is stored in the data variable. To access its components, you can use dot syntax (page 56), so data.title retrieves the title of the feed. If you save the page now and preview it in a web browser, you should see a bold headline reading “Uploads from Smithsonian Institution.” Next, you’ll create a new variable, which will hold a string containing the HTML that you’ll add to this web page. 6. Add the bolded line of code below to the code from the last step: $.getJSON(ajaxURL,function(data) { $('h1').text(data.title); var photoHTML = ''; }); // end get JSON; 490 JAVASCRIPT & JQUERY: THE MISSING MANUAL This string is empty now, but soon you’ll add the HTML required to display the photos returned by Flickr. To create this HTML, you’ll loop through the items array of objects returned by the Flickr feed. For each photo in the feed, you’ll add more HTML to the photoHTML variable. TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE 7. Add the bolded lines of code below to the code from the previous step: $.getJSON(ajaxURL,function(data) { $('h1').text(data.title); var photoHTML = ''; $.each(data.items,function(i,photo) { }); // end each }); // end get JSON; The .each() function (page 138) is used to loop through a jQuery selection. The $.each() method is different, but similar. It’s a generic loop utility that you can use to loop through either an array (page 44) or a series of objects. You pass the $.each() method an array or an object literal and an anonymous function. The $.each() method then loops through the array or the object literal and runs the anonymous function once for each item. That anonymous function receives two arguments (i and photo in the code in this step), which are variables that contain the index of the item and the item itself. The index is the number of the item through the loop: This function works just like an index for an array (page 48). For example, the first item in the loop has an index of 0. The second argument (photo in this example), is the photo object containing the photo’s name, description, URL, and so on, as described on page 488. In the case of the Flickr feed, data.items represents the photo objects in the JSON feed, so the $.each() function passes the object for each photo to the anonymous function in the photo variable. In other words, this code loops through each of the photos in the feed and then does something. In this case, you’ll create a series of thumbnail images that links to each photo’s Flickr page. The goal is to create some basic HTML to display each image and include a link. For example: <span class="image"> <a href="http://www.flickr.com/photos/smithsonian/5988083516/"> <img src="http://farm7.static.flickr.com/6029/5988083516_bfc9f41286_s.jpg"> </a> </span> To build this, you need only two pieces of information—the URL of the photo’s Flickr page, and the path to the photo file. You’ll just build up a long string that looks just like the HTML above, only replacing the URL and image path for each of the images. Chapter 13: Introducing Ajax 491 TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE 8. Inside the $.each() method, add the bolded code below: $.each(data.items,function(i,photo) { photoHTML += '<span class="image">'; photoHTML += '<a href="' + photo.link + '">'; photoHTML += '<img src="' + photo.media.m + '"></a></span>'; }); // end each This code starts by adding an opening <span> tag to the variable photoHTML. Each subsequent line adds more to the variable (for a refresher on what += means and how it works, see page 39). The key elements here are photo.link and photo.media.m. If you look at the JSON code on page 487, you can see that each photo has various properties like title (the name of the photo) and description (a short description of the photo). The link property points to the photo’s page on Flickr.com, while the media object has a property named m, which contains the path to the medium-sized version of the graphic file. Altogether, this code builds up HTML like that pictured in step 6. Now you just need to add that code to the page. 9. Add the bolded code below: $.each(data.items,function(i,photo) { photoHTML = '<span class="image">'; photoHTML += '<a href="' + photo.link + '">'; photoHTML += '<img src="' + photo.media.m + '"></a></span>'; }); // end each $('#photos').append(photoHTML); Note that this line goes outside of the loop. You don’t want to add the HTML to the page until you’ve finished creating it inside of the loop. The $('#photos') part selects an already existing <div> tag on the page, while the append() function (discussed on page 127) adds the HTML to the end of that div. 10. Save the page and preview it in a web browser. You should see 20 photos load on the page. (If you don’t see anything, doublecheck your code and use your web browser’s error console [page 18] to look for any syntax errors.) The problem is the photos all vary in size and don’t form a nice grid on the page. That’s because the Flickr feed only provides the path to medium-sized Flickr images. Flickr does offer nice square thumbnails of all their photos as well. Displaying those identically sized photos together on a page makes a neat, orderly presentation. Fortunately, it’s easy to request those thumbnail images. Flickr uses a consistent naming convention for their photos: If the path to a mediumsized image is http://farm7.static.flickr.com/6029/5988083516_bfc9f41286_m. jpg, the thumbnail path for that same image is http://farm7.static.flickr. com/6029/5988083516_bfc9f41286_s.jpg. The only difference is at the end of the filename: _m indicates a medium image, _s is a small square thumbnail image (75 pixels by 75 pixels), _t is a small image that’s at most 100 pixels on 492 JAVASCRIPT & JQUERY: THE MISSING MANUAL the longest side, _o indicates the original image (the original size the file that the was uploaded to Flickr), and _b is a large image (at most, 1,024 pixels tall or wide). By simply adjusting the filename (replacing the _m with _s, for example), you can display a different size file. Fortunately, JavaScript provides a handy method of quickly swapping characters in a string. TUTORIAL: ADDING FLICKR IMAGES TO YOUR SITE 11. In the code, change photo.media.m to photo.media.m.replace(' _m',' _s'). The final code on the page should look like this: $(document).ready(function() { var URL = "https://api.flickr.com/services/feeds/photos_public. gne?jsoncallback=?"; var searchInfo = { id : "25053835@N03", format : "json" }; $.getJSON(URL,searchInfo,function(data) { $('h1').text(data.title); var photoHTML = ''; $.each(data.items,function(i,photo) { photoHTML += '<span class="image">'; photoHTML += '<a href="' + photo.link + '">'; photoHTML += '<img src="' + photo.media.m.replace('_m','_s') + '"> </a></span>'; }); // end each $('#photos').append(photoHTML); }); // end get JSON }); // end ready JavaScript’s replace() method (discussed on page 560) works with strings, and takes two arguments—the string to find ('_m' in this case) and the string to replace it with ('_s'). 12. Save the page and preview it in a web browser. Now you should see 20 neatly aligned, square thumbnails (Figure 13-11). Click a thumbnail to see a larger image on Flickr’s site. A working version of this tutorial—complete_flickr.html—is available in the chapter13 folder. NOTE The Flickr feed only provides 20 images maximum. You can’t retrieve more than 20 from any one feed. What if you only want to display 10 images from the feed? See the file complete_flickr_limit_photos.html in the chapter13 folder for the solution. Chapter 13: Introducing Ajax 493 CHAPTER Building a To-Do List Application 14 j Query and jQuery UI provide the tools to build a professional-looking web application in just a few steps. jQuery takes care of the details regarding selecting page elements, adding new page elements, and updating the DOM. jQuery UI provides great-looking widgets, interactions, and effects that solve many common problems in user interface design. With both of these libraries working for you, you can skip time-consuming programming tasks and jump directly into coding a dynamic interactive application. This chapter walks you through the construction of a basic task manager. An Overview of the Application Your to-do list application will let its users do the following: • Add a new task to the list of to-dos. You’ll achieve that by adding a jQuery UI button (#1 in Figure 14-1) that, when clicked, opens a jQuery UI dialog box. • Mark a task as complete. Each to-do list item will have a checkbox to the left of the task name (#2 in Figure 14-1). Clicking this box will automatically remove the to-do list item from the To Be Done list and move it to the Completed Tasks list. • Drag items from the To Be Done list to the Completed Tasks list and vice versa (#3 in Figure 14-1). While clicking a checkbox works, why limit your users to just one way of marking a task as complete? With jQuery UI’s sortable widget, you can also let users just drag an item to the Completed Tasks list to mark it done. In addition, you can let users drag a completed task back to the To Be Done list. 495 ADD A BUTTON • Remove tasks from either list by clicking a Delete button (#4 in Figure 14-1). To allow complete removal of a task, you’ll supply a Delete button that removes it from the page. You’ll also use a jQuery UI effect to make deleting the task look cool. Because jQuery UI provides most of the user interface, you just need to work on the basic logic of the application. You’ll tackle this task in small bits following the outline just presented. You’ll start by adding a button, then a dialog box, and then build up the rest of the app. It’s a good idea when taking on a programming task to break the task down into small, testable components, so in this tutorial you’ll do one thing, make sure it works, and then continue to the next step. FIGURE 14-1 jQuery and jQuery UI make it relatively simple to create a basic to-do list application. jQuery and jQuery UI solve the difficult user interface problems—like creating dialog boxes, creating sortable lists, and animating page elements—so you can concentrate on just coding the to-do list functionality. Add a Button First, you’ll add a button and format it using jQuery UI. In this tutorial, you’ll work on two different files supplied in the Chapter 14 folder: index.html and todo.js. You’ll put all the JavaScript code into the todo.js file and add HTML code for the button and dialog box to the index.html file. NOTE See the note on page 12 for information on how to download the tutorial files. 1. In a text editor, open the file index.html in the chapter14 folder. This file already contains links to the necessary CSS, jQuery, and jQuery UI files. However, it doesn’t yet load the todo.js file—the file you’ll add the programming to. 496 JAVASCRIPT & JQUERY: THE MISSING MANUAL 2. In the line just below <script src="js/jquery-ui.min.js"></script>-->, add the following: ADD A BUTTON <!--<script src="todo.js" type="text/javascript"></script>--> It’s important that the todo.js file is listed last because it relies on both jQuery and jQuery UI. If you loaded it before either of those files, the browser would cough up a syntax error when the page loads. Next, you’ll add a button. A visitor clicks this button to add a new task to the to-do list. 3. Locate the HTML comment <!-- add button here --> and replace it with the following HTML: </ul></div></div></div></div></div></div></ul></div></div></div></div></h1></div></div></div></li></ol></ul></div></h2></ul></div></li></div></div></ol></ul></div></span></div></div></div></h2></div></div></div></h2></div></div></div></div></div></button><button id="add-todo">Add to-do item</button> There’s nothing special about this code—it’s just a basic HTML <button> element. If you previewed the page right now, you’d see that it looks like a basic Submit button on a form—drab and uninteresting. Next, you’ll turn it into a jQuery UI button. 4. Open the todo.js file in your text editor, and, inside the $(document).ready() function, type: $('#add-todo').button(); This code simply applies the button formatting supplied by the jQuery UI theme (page 385). You can spruce it up a little by adding a jQuery UI icon. 5. Inside the button() function, add a JavaScript object literal that defines an icon for this button (additions in bold): $('#add-todo').button({ icons: { primary: "ui-icon-circle-plus" } }); This adds a little + icon to the left of the text “Add to-do item” on the button. As discussed on page 367, jQuery UI lets you place two icons on a button one of the left (the primary icon) and one on the right (the secondary icon). One icon is enough for this button. 6. Save both the todo.js and index.html files. Preview the index.html file in a browser. The button should match the look of a jQuery UI button widget (Figure 14-1). If it doesn’t, it’s because the JavaScript isn’t working. Double check your code and use your browser’s JavaScript console to see if there are any errors. Chapter 14: Building a To-Do List Application 497 ADD A DIALOG BOX Add a Dialog Box Now there’s a button, but it doesn’t do anything. It’s supposed to open a dialog box when clicked, so the next task is to add the dialog. First, you’ll add the HTML for the dialog: 1. Locate the comment <!-- add dialog box here --> in the index.html file and replace it with the following HTML: <div id="new-todo" title="Add to-do item"> <form></form> <p> <label for="task">Task Name:</label> <input type="text" name="task" id="task"> </p> </div> As you learned on page 306, you can turn any chunk of HTML into a dialog box. In this case, there’s a <div> element containing a form with a single text field. Users will type the name of their task into this field when adding a new to-do item. To transform this HTML into a dialog box, you need to add some JavaScript. 2. Return to the todo.js file. Below the code you added in step 5 on page 497, type: $('#new-todo').dialog(); Save the index.html and todo.js files and preview the index.html file in a browser. The dialog box should appear (see top image in Figure 14-2). However, it appears immediately, without clicking the button. That’s the normal behavior of a jQuery UI dialog box. To hide the dialog, you need to pass the dialog() function some options. 3. Add an object to the dialog() function with two properties: $('#new-todo').dialog({ modal : true, autoOpen : false }); As you read on page 310, the modal option requires a user to close the dialog box in order to do anything else with the web page. That’s what you want— when the user clicks the “Add to-do item” button, the dialog should be the user’s main focus. By setting the autoOpen option to false, the dialog will no longer open as soon as the page loads. It’s now hidden, and you need to open it programmatically— like when the button is clicked! 498 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADD A DIALOG BOX FIGURE 14-2 jQuery UI dialog boxes automatically open when the page loads. That’s great for an important announcement that visitors should see when they visit the page, but not so useful for most other purposes, like adding a task to a to-do list. Most of the time, you’ll want a dialog box to remain hidden until it’s called into action by a visitor’s request—like clicking an “Add to-do item” button. 4. Add a click event handler to the button by chaining the click() function to the end of the button() function: $('#add-todo').button({ icons: { primary: "ui-icon-circle-plus" } }).click(function() { Chapter 14: Building a To-Do List Application 499 ADD A DIALOG BOX $('#new-todo').dialog('open'); }); You can “chain” jQuery functions by simply adding a period at the end of one function and then adding another function after it. In this case, the code first selects an element with the ID of add-todo (that’s the button), applies the jQuery UI button() function, and then adds a click event handler. The event handler calls the dialog box’s open method (page 313). In other words, clicking the button should now open the dialog box. Now’s a good time to test. 5. Save the todo.js file and preview the index.html file in a browser. Click the “Add to-do item” button. The dialog should only appear when you click the button (bottom image in Figure 14-2). In addition, the area below the dialog should appear darkened with diagonal stripes. This visual cue indicates that the dialog is modal, which means that you can’t do anything until you dismiss it. But as you can see, there’s no way to dismiss it. There aren’t any buttons! jQuery UI lets you add buttons easily. 6. Return to the todo.js file. Add a new option named buttons to the options list, and set its value to an empty object: $('#new-todo').dialog({ modal : true, autoOpen : false, buttons : { } }); The buttons option lets you name buttons that jQuery UI dynamically adds to a dialog box. In addition, you can assign functions to each button, so when a visitor clicks the button, something happens. You’re building up this code slowly, bit by bit, because there’s a lot going on here. For example, you now have an object (the buttons property) inside another object (the options object passed to the dialog() function). First, just add a button with an empty function. 7. Add one property to the buttons object (additions in bold): $('#new-todo').dialog({ modal : true, autoOpen : false, buttons : { "Add task" : function () { 500 JAVASCRIPT & JQUERY: THE MISSING MANUAL ADD A DIALOG BOX } } }); This code adds a button with a label reading “Add task”. When a user clicks the “Add task” button, the function runs. Currently there’s nothing in that function, so it won’t do anything. You’ll add functionality to the button in the next section of this tutorial. But for now, you’ll add another button. 8. Type a comma after the add task() function’s closing } and add another button with a function: $('#new-todo').dialog({ modal : true, autoOpen : false, buttons : { "Add task" : function () { }, "Cancel" : function () { $(this).dialog('close'); } } }); This adds a second button with the label “Cancel.” This time, the button does something. $(this) refers to the element that called the function—that’s the dialog box itself. When the Cancel button is clicked, the jQuery UI Dialog widget’s close method is called (page 315). This simply tells the dialog box to close without doing anything further. Time to see how it works. 9. Save the todo.js file and preview the index.html file in a browser. Click the “Add to-do item” button. The dialog should only appear with two buttons (Figure 14-3). Click the “Add task” button, and sure enough, nothing happens, because you haven’t programmed it yet. However, you did add code to the Cancel button, so when you click it, the dialog box closes. In the next section, you’ll add the code to actually insert to-do list items onto the page. Chapter 14: Building a To-Do List Application 501 ADDING TASKS FIGURE 14-3 With just a few lines of code, you have all the basic user interface components for adding to-do list items in place. Adding Tasks The to-do list application is looking good, but not doing much. It’s time to add the code for adding tasks to the To Be Done list. All of this code is attached to the function assigned to the dialog box’s “Add task” button—that empty function you added back at step 7 on page 500. The code breaks down into 4 steps: 1. Retrieve the name of the task the user typed into the dialog box. The value is stored in a form text input field, so you can easily use jQuery’s val() function (page 255) to retrieve the task name. 2. Build up a <li> item to add to the page. Each task will be represented by a list item in an unordered list. The basic HTML for each list item looks like this: </li><li> <span class="done">%</span> <span class="delete">x</span> <span class="task">Bake cake</span> </li> The first <span> represents the area the visitor clicks to mark an item as done. The second <span> represents the delete button the visitor clicks to remove 502 JAVASCRIPT & JQUERY: THE MISSING MANUAL a task completely. The last <span> contains the task name the visitor types into the dialog box. You can build up this chunk of HTML by combining strings containing the literal tags just listed with the task name the visitor provides. ADDING TASKS NOTE You’ll use CSS to format the Done and Delete buttons on each list item. In fact, the % and x in the first two spans above will look like a checkmark button and a delete button thanks to an icon font (an icon font is simply a web font made up of icons instead of letters). 3. Add the new <li> item to the To Be Done list. jQuery makes it very easy to take a string, convert it to an actual DOM element, and add it to a web page (Chapter 4 discusses that thoroughly). Because you have jQuery UI’s powerful effects at your disposal, you’ll use them to add the new task in an eye-catching fashion. 4. Close the dialog box. This step’s easy. You already programmed this same functionality for the dialog box’s Cancel button in step 8 on page 501. Now that you know the basic steps you need to code, it’s time to get started. First, you’ll capture the visitor’s input—the task he types into the dialog box: 1. Locate the function assigned to the “Add task” button (it’s inside the buttons option for the dialog() function) and add the bolded code shown here: "Add task" : function () { var taskName = $('#task').val(); }, This creates a new variable—taskName—and assigns the value of the dialog box’s text field. Remember in step 1 on page 498, you added the HTML for the dialog box. That included an input field with the ID of task, so $('#task'). val() retrieves the value of that field—in other words, what the visitor typed in as the task’s name. It’s possible that a visitor might leave the text field blank and click the “Add task” button anyway. Because you don’t want to add an empty task to the to-do list, you should check to make sure the taskName variable isn’t empty. 2. Add three more lines of code below the one you added in the last step (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } }, Chapter 14: Building a To-Do List Application 503 ADDING TASKS This code simply checks to make sure the taskName variable doesn’t contain an empty string (that’s two single quote marks next to each other like this '') and that the visitor didn’t just click the “Add task” button without typing anything. The return false part just exits this function, with the result that the dialog box stays open. The visitor either has to type a task or click the Cancel button to close the dialog box (or click the little X button in the top right of all jQuery UI dialog boxes). Next, you’ll begin constructing the HTML for the task. 3. Add a new variable and add string values to it by adding three more lines of code (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '</li><li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; }, You could have used just a single line of code to create the taskHTML variable and store one really long string in it. But that would create one very long, hard-toread JavaScript statement. Building up a long string over the course of several lines like this makes the code more readable. The += operator lets you combine a string with the string in an already existing variable (page 39). Notice that you didn’t add the visitor’s task—the taskName variable—to this string. You’ll see why in just a moment. 4. Add another variable and assign to it a jQuery object created from the string of HTML (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); }, jQuery lets you take a string of text—'<h1>A headline</h1>', for example—and convert it to an actual DOM element. In other words, taskHTML is a variable that just holds a string—a series of characters. That string isn’t “real” HTML, however; passing a string that’s formatted like HTML to the $() function turns it into a 504 JAVASCRIPT & JQUERY: THE MISSING MANUAL DOM element. Even better, it turns the string into a jQuery object so you can use all of the regular jQuery functions on it. While the $ at the beginning of the $newTask variable name isn’t required, it’s a common practice among JavaScript programmers who use jQuery. The $ is a visual way to remind the programmer that the variable holds a jQuery object and that all the various jQuery methods, like .show() and .addClass() can be used with that variable. ADDING TASKS You’ll add the task the visitor types in next. 5. Add another line of code to the “Add task” function (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); $newTask.find('.task').text(taskName); }, jQuery’s find() method looks for an element inside the current element (page 531). In this case, jQuery takes the <li> element contained inside $newTask and looks inside it for another element with the class name of task—that’s the <span> tag where the task’s name should go (look at step 3). jQuery’s text() function then adds the contents of the taskName variable inside that span. Why go to all this trouble, when you could just add taskName when creating the string in step 4 like this: taskHTML += '<span class="task">' + taskName + '</span></span></li>'; If you did it that way, then a nefarious visitor could type something like <!--<script type="text/javascript">alert('ha, ha, ha, I am breaking your to-do list');</script>--> as the task’s name. That code would be added as straight HTML to the page and the malicious JavaScript in this example would be run. However, jQuery’s text() function converts all HTML tags into their HTML-safe equivalents— <script> instead of <!--<script type="text/javascript">. Even if the visitor wasn’t trying to be malicious, this step lets him type a perfectly reasonable task like “Add <h1> tag to the home page” without breaking the app. Now it’s time to add the new to-do item to the page. Chapter 14: Building a To-Do List Application 505 ADDING TASKS 6. Add two more lines of code inside the “Add task” function (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); $newTask.find('.task').text(taskName); $newTask.hide(); $('#todo-list').prepend($newTask); }, Because $newTask is a jQuery object, you can use jQuery functions on it. First, you hide it, so you can reveal it using some cool visual animations. After it’s hidden, select the To Be Done list—an unordered list on the page with the ID todo-list—and then add the new (hidden) list item to the beginning of the list (see page 127 to learn how the prepend() method works). Now, you’ll reveal the new list item and close the dialog box. 7. Add two more lines of code to complete the “Add task” button’s functionality (additions in bold): "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); $newTask.find('.task').text(taskName); $newTask.hide(); $('#todo-list').prepend($newTask); $newTask.show('clip',250).effect('highlight',1000); $(this).dialog('close'); }, The first new line selects the newly added and hidden list item and then uses jQuery’s show() method to reveal it. For some added fun, you’re using two jQuery UI effects: the clip effect (page 440) makes the new item appear to grow. After the item is visible, the effect() method applies the highlight effect 506 JAVASCRIPT & JQUERY: THE MISSING MANUAL to make the item flash yellow and draw attention to it (and get “ooohs” and “aaahhhs” from the people using this app). ADDING TASKS The last line closes the dialog box (you already used this code with the Cancel button at step 8 on page 501). Time to check and see how it works. 8. Save the todo.js file and open the index.html file in a browser. Click the “Add to-do item” button, type a task in the dialog box that appears, and then click “Add task.” A new task should appear under the “To Be Done” headline. If it doesn’t, check your code and use your browser’s JavaScript console to see if there are any errors. Try adding another task. You should see one small problem—the dialog box’s text input field remembers the last task you typed. To add a new task, you first have to delete the old one from the text field. You can fix that easily. 9. After the buttons option inside the object passed to the dialog() function, type a comma and add the following: close: function() { $('#new-todo input').val(''); } The complete code for the dialog() function should look like this: $('#new-todo').dialog({ modal : true, autoOpen : false, buttons : { "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); $newTask.find('.task').text(taskName); $newTask.hide(); $('#todo-list').prepend($newTask); $newTask.show('clip',250).effect('highlight',1000); $(this).dialog('close'); }, "Cancel" : function () { $(this).dialog('close'); } }, Chapter 14: Building a To-Do List Application 507 MARKING TASKS AS COMPLETE close: function() { $('#new-todo input').val(''); } }); Wow, that’s a lot of code. Make sure you add this new code outside the buttons object. jQuery UI’s dialog widget’s close option lets you run a function when the visitor closes the dialog box. In this case, you’ll erase the text field, so next time the dialog is opened, the field will be empty and ready to receive a new task name. (You could also have erased the input field as part of the “Add task” function, but this example was intended to demonstrate the close option.) Marking Tasks as Complete One of the most satisfying actions you perform with a to-do list is checking off a completed task. Unfortunately, your to-do list is missing that most rewarding feature. In this section, you’ll fix that. The basic process is pretty straightforward: the user checks the empty box to the left of the task name, and that task—the list item element—is moved from one unordered list to the other. Event Delegation To mark a task as complete, a user must click a box within the list item. Usually you assign an event handler using jQuery by selecting the element then adding an event handler, like this: $('.done').click(function () { // do something when this element is clicked }); However, there’s something different about how you handle the items in this to-do list. When the web page first loads, there are no list items, and no boxes to mark a task as complete. If you applied the event handler when the page loaded, nothing would happen. Because there were no list items and no checkboxes when the page loaded, there’s nothing to apply the handler to. Only after the visitor adds a task is there anything to click on. You could add the click() method each time a new list item is created, but jQuery provides a better method called event delegation (page 171). In a nutshell, event delegation lets you select another page element—an already existing page element that will contain the items that are going to be added dynamically after the page loads. This container element will listen for the proper event—a click event, for example—anywhere inside of it. When it gets the event, it will see if the event was actually triggered on a particular element (the Done box on each task item, for instance), and if it was, the event handler runs. In this case, an empty unordered list is already on the web page when it loads: 508 JAVASCRIPT & JQUERY: THE MISSING MANUAL MARKING TASKS AS COMPLETE <ul id="todo-list"> </ul> As the visitor adds tasks to the to-do list, your program dynamically adds list items: <ul id="todo-list"> <li> <span class="done">%</span> <span class="delete">x</span> <span class="task">Bake cake</span> </li> </ul> To respond to a click on the done span, you have to delegate the event handler to the existing unordered list: 1. After the code for the dialog() function but still inside the $(document). ready() function, type the following: $('#todo-list').on('click', '.done', function() { }); This is the basic outline for the event delegation routine. First, you select the unordered list. Then we use jQuery’s on() method, which accepts three arguments. The first is a string containing the event name—'click' . The second is the element inside the unordered list that must be clicked on. In this case, it’s the <span> tag with the class done. Finally, you add a function—the programming that should run when the visitor clicks the Done box. 2. Inside the event handler function, add the following (in bold): $('#todo-list').on('click', '.done', function() { var $taskItem = $(this).parent('li'); }); Remember that the point of this function is to move the list item from the To Be Done list to the Completed Tasks list. At the point that the visitor clicks the Done box, jQuery is only aware of that one <span> in the list item, but we need to access the entire <li> tag. To do so, you’ll use jQuery’s parent() method, which lets you select the parent element of the current selection. Here, $(this) refers to the element the visitor clicks the <span class="done">%</ span>. So $(this).parent('li') selects the nearest ancestor that is an <li> tag; in other words, it selects the list item you’re after! That element is then stored in a variable named $taskItem, which you’ll now make disappear. NOTE For a more thorough discussion of what this and $(this) mean, turn to page 139. Chapter 14: Building a To-Do List Application 509 MARKING TASKS AS COMPLETE 3. Inside the event handler function add the following (in bold): $('#todo-list').on('click', '.done', function() { var $taskItem = $(this).parent('li'); $taskItem.slideUp(250, function() { }); }); jQuery’s slideUp method is a fun way to hide a page element (page 186). It doesn’t actually remove the element from the page, however. When the slideUp method is done, the item is still on the page; it’s just hidden using some CSS. As you read on page 183, all jQuery animation functions (like hide(), show(), and slideUp()) can accept arguments. In this case, the first argument—250—is the amount of time the animation will take: 250 milliseconds. The second argument here is a callback function. This is a function that runs after jQuery finishes the animation. Remember that after slideUp is finished, the list item is still in the To Be Done list—it’s just hidden. You need to move it to the other unordered list. You can do that as part of the callback function. 4. Inside the callback function, add the following (in bold): $('#todo-list').on('click', '.done', function() { var $taskItem = $(this).parent('li'); $taskItem.slideUp(250, function() { var $this = $(this); $this.detach(); }); }); The first new line just selects the list item—$(this)—and stores it inside another variable. You do this because each time you run the jQuery function—$( )— you’re making the browser do work. You must perform several tasks on this list item, so instead of unnecessarily calling the jQuery function over and over, you can just run it once and keep the results in a variable. (This jQuery best practice is discussed in more detail on page 522.) The second line uses jQuery’s detach() method to remove the selected HTML element or elements from the page, but doesn’t completely get rid of them. In other words, the list item is gone from the list, but it still exists in memory. In fact, it’s still stored in the variable $this. You can then move the detached element to another place on the page—the other list! NOTE 510 Visit http://api.jquery.com/detach/ to get the full scoop on jQuery’s detach() method. JAVASCRIPT & JQUERY: THE MISSING MANUAL MARKING TASKS AS COMPLETE 5. Finish up the callback function by adding two more lines (in bold): $('#todo-list').on('click', '.done', function() { var $taskItem = $(this).parent('li'); $taskItem.slideUp(250, function() { var $this = $(this); $this.detach(); $('#completed-list').prepend($this); $this.slideDown(); }); }); You’ve seen the prepend() method before (in step 6 on page 506). It inserts HTML inside another element. In this case, the detached list item—$this—is added inside the Completed Tasks list (another unordered list with the ID of completed-list). Lastly, because the slideUp() method hid the list item, you can now reveal it in its new location on the page with slideDown() (page 186). 6. Save the todo.js file and preview the index.html file in a web browser. To test it out, add a few new to-do items, and then click the box to the left of the task name to mark the task as complete. You should be able to add tasks and mark them as complete (Figure 14-4). If it’s not working, double check your code and look at your browser’s JavaScript console for errors. Now, wouldn’t it be cool if you could reorder your tasks? For example, after you add a bunch of tasks to the list, you could put them in the order in which you should complete them: “Buy a cookbook,” “Bake a cake,” and “Eat a cake,” for example. jQuery UI’s sortable widget lets you add that feature easily. And while you’re at it, you can make it so you can freely drag items between lists, so you can mark a to-do item “complete” simply by dragging it to the Completed Tasks list. FIGURE 14-4 The buttons on the list items which let you mark a task as complete, or delete a task, change as you mouse over them. That’s not JavaScript, that’s CSS. In particular, it’s the CSS :hover pseudo-class that lets you change how an element looks when you mouse over it. To see how this effect works, check out the todo.css file inside the css folder for this chapter. Chapter 14: Building a To-Do List Application 511 MARKING TASKS AS COMPLETE 7. Open the index.html file in your text editor and locate the <ul> tags for the To Be Done and Completed Tasks lists. Add class="sortlist" to both so you’ll end up with: <ul id="todo-list" class="sortlist"> and <ul id="completed-list" class="sortlist"> By supplying the same class name to both lists, you can easily select both and make both sortable. 8. Save the index.html file and open the todo.js file in your text editor. After the code for the delegated event handler you just added but still inside the $(document).ready() function, type the following: $('.sortlist').sortable(); Now the two lists are sortable. You can save the files and preview the index.html file if you want to try it out. But you’ll notice that while you can re-order items in each list, you can’t drag one list item into another list. You have to connect the two sortable widgets first. 9. Inside the sortable() function you just added, insert an object with a property and value: $('.sortlist').sortable({ connectWith : '.sortlist' }); The sortable widget’s connectWith option (page 429) lets you connect one list with another. Because you’ve supplied both lists with the same class name, you’ve connected both lists. Now you’ll be able to drag items freely between lists, but you’ll add just a few last user interface niceties before you’re done with these sortable widgets. 10. Add three more options to the sortable widget’s option object: $('.sortlist').sortable({ connectWith : '.sortlist', cursor : 'pointer', placeholder : 'ui-state-highlight', cancel : '.delete,.done' }); Don’t forget the comma after the connectWith option. The cursor option (page 403) changes the cursor to a pointer when a list item is being dragged; the placeholder option (page 432) highlights the space in the list where a visitor can drop an item as she drags it around the list. Finally, the cancel option (page 429) identifies elements on the sortable item that won’t work as handles for dragging the item: in this case, a visitor can’t drag a task by either its “delete this task” icon, or its “mark as done” box. 512 JAVASCRIPT & JQUERY: THE MISSING MANUAL 11. Save the index.html and todo.js files, and preview the index.html file in a web browser. DELETING TASKS Add lots of tasks. Drag tasks between the two lists. You should be able to mark an item as complete simply by dragging it from the To Be Done to the Completed Task list (Figure 14-1). Deleting Tasks There’s just one last feature to add: the ability to delete a task. This feature is important because a user might accidentally add a task that shouldn’t be there. Or if the Completed Tasks list starts getting too long, a user might want to delete those completed to-do items. 1. After the code for the sortable() function but still inside the $(document). ready() function, type the following: $('.sortlist').on('click', '.delete', function() { }); It’s event delegation again. When the page loads, there are no list items and no delete buttons, so you need to use event delegation to handle this situation. In this case, $('.sortlist') selects both of the unordered lists on the page (because users should be able to delete tasks from either list) and the on() method tells jQuery to be on the lookout for clicks on any element with the class delete. When that element is clicked, this event handler function is called. Next, you’ll program the event handler. 2. Inside the event handler function, add three lines of code (in bold): $('.sortlist').on('click','.delete',function() { $(this).parent('li').effect('puff', function() { $(this).remove(); }); }); There’s a lot going on there, but you should be accustomed to this type of code by now. Here’s how it breaks down: • $(this).parent('li') selects the element the user clicked on—$(this)— and then finds an ancestor that is an <li> tag. In other words, it selects the list item you want to delete. • jQuery UI’s effect() method applies one of its many effects to the element. In this case, the puff effect makes an element grow in size, fade away, and disappear. Chapter 14: Building a To-Do List Application 513 DELETING TASKS • The function inside the effect() method is a callback function that runs once the effect is done. In this case, it selects the item that the effect() method was applied to—that’s the list item selected by $(this)—and removes it from the page using jQuery’s remove() method (page 130). Unlike the detach() method discussed on page 510, the remove() method literally removes the selected elements from the page and disposes of them. 3. Save the files and preview the index.hml file in a web browser. You should be able to add, move, and delete to-do list items. The page should look like Figure 14-1. If you have any problems, the complete code for this tutorial is shown here: $(document).ready(function(e) { $('#add-todo').button({ icons: { primary: "ui-icon-circle-plus" } }).click(function() { $('#new-todo').dialog('open'); }); $('#new-todo').dialog({ modal : true, autoOpen : false, buttons : { "Add task" : function () { var taskName = $('#task').val(); if (taskName === '') { return false; } var taskHTML = '<li><span class="done">%</span>'; taskHTML += '<span class="delete">x</span>'; taskHTML += '<span class="task"></span></li>'; var $newTask = $(taskHTML); $newTask.find('.task').text(taskName); $newTask.hide(); $('#todo-list').prepend($newTask); $newTask.show('clip',250).effect('highlight',1000); $(this).dialog('close'); }, "Cancel" : function () { $(this).dialog('close'); } }, close: function() { 514 JAVASCRIPT & JQUERY: THE MISSING MANUAL $('#new-todo input').val(''); } }); GOING FURTHER $('#todo-list').on('click','.done', function() { var $taskItem = $(this).parent('li'); $taskItem.slideUp(250, function() { var $this = $(this); $this.detach(); $('#completed-list').prepend($this); $this.slideDown(); }); }); $('.sortlist').sortable({ connectWith : '.sortlist', cursor : 'pointer', placeholder : 'ui-state-highlight', cancel : '.delete,.done' }); $('.sortlist').on('click','.delete',function() { $(this).parent('li').effect('puff', function() { $(this).remove(); }); }); }); // end ready NOTE For a complete, working copy of this tutorial look at the complete-index.html and complete-todo.js files in the chapter14 folder. Going Further Congratulations—you’ve built your first web page application! But there’s clearly some ways you can improve this to-do list manager. You may already have a list of additional features you’d like to add. This section will take a look at some possible improvements you could make to the app, including resources you could use to learn how to implement those changes. Editing Tasks Currently, the application has no way for a user to edit a typo in a task. If someone creates a new task named “Brake cake,” he’d have to delete the task and create a new one to correct her mistake. There are two ways you could solve this problem. Chapter 14: Building a To-Do List Application 515 GOING FURTHER The first solution is to add an Edit button on each task item. Clicking this button will open an edit dialog box with the text content of the task—that’s contained inside a <span> element with the class of task. You could add another dialog box to the page, like the one you added on page 498. Clicking the Edit button opens the dialog box and places the task name into an editable text field. Closing the box updates the task in the list. Another method uses the HTML contentEditable property. This property makes any HTML element editable. For example, the HTML to make the task name editable in the example HTML you’re using for this application would look like this: <span class="task" contentEditable> You can even apply this property dynamically with jQuery: $('.task').prop('contentEditable', true); There’s one problem with using contentEditable in this application. jQuery UI’s sortable widget prevents selections of text inside sortable items, so you can’t select the text to edit it, even if the contentEditable property is enabled. You can get around this problem by telling jQuery UI to ignore the task elements when applying the sortable() function. You did something similar for the Delete and Done buttons in step 10 on page 512. You’d just need to add the .task selector to the list: cancel : '.delete,.done,.task' If you go this route, there won’t be much of the list item left for a user to click on and drag. In this case, you should add a clearly identifiable handle that visitors could use to drag the tasks in the list. The sortable item’s handle option can help with this (page 431). Confirming Deletions Currently, when a visitor clicks the Delete button, the task is gone forever. You could add a modal dialog box that asks the visitor to confirm the action. If the visitor clicks Yes, the task is removed; if No, the task stays as is. Saving the Lists The biggest problem with the to-do list application is that it doesn’t remember the list when you close the browser window. The to-do list is completely temporary, and won’t be remembered between browser visits or if the page is viewed on different computers. There are a few ways you can save the state of your to-do list. LOCAL STORAGE All current browsers include a feature called local storage, which lets you save data to the visitor’s computer and call that data back up when the visitor returns to the page. You could use local storage to save a snapshot of the task items each time the to-do lists are updated. When a visitor returns to the page, you check to see if there is any local storage data, and if so, update the web page with that data. 516 JAVASCRIPT & JQUERY: THE MISSING MANUAL You can learn more about local storage at the Mozilla Developer Network: https:// developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage. There’s even a jQuery plug-in to help make using local storage easy: https://github.com/julienmaurel/jQuery-Storage-API. GOING FURTHER SAVE TO A SERVER Another approach is to save the to-do list to a web server. The benefit of this approach is that you could access the to-do list from any computer. The disadvantage is that you’d need to create some system for controlling access to the to-do list; otherwise, anyone could visit the to-do list page and see your tasks (and delete them). This book doesn’t cover server-side programming. However, you will need to use some JavaScript to send the to-do list items to the server. You’ll use Ajax, covered in the previous chapter, to send the to-do list data to the server. The best way would be to grab all of the list items with jQuery and use its .each() method to go over each of the list items and extract just the task name. You could build up a JavaScript object with a list of both the uncompleted and completed tasks. Finally, in order to be able to send the object containing the list of tasks to the server with Ajax, you’ll need to serialize that object—convert it into a simple string that can be sent to the server. Here’s a function that could do that: function getData() { var todoData = { toDo : [], completed : [] }; $('#todo-list').each( function() { var task = $(this).find('.task').text(); todoData.toDo.push(task); }); $('#completed-list').each( function() { var task = $(this).find('.task').text(); todoData.completed.push(task); }); return $.param(todoData); } You could call this function whenever you wanted to retrieve the to-do list items in a form that could be sent to the server. It’s up to the programming on your web server to decode this and do something with it. More Ideas If you have further ideas for improving this to-do list, explore them. This is a great project for trying out your new JavaScript, jQuery, and jQuery UI skills. You’ll find an ever-evolving version of this project up on GitHub at https://github.com/sawmac/ jquery-todo. Chapter 14: Building a To-Do List Application 517 PART Tips, Tricks, and Troubleshooting CHAPTER 15: Getting the Most from jQuery CHAPTER 16: Going Further with JavaScript CHAPTER 17: Troubleshooting and Debugging 5 CHAPTER Getting the Most from jQuery 15 j Query greatly simplifies JavaScript programming, and lets you quickly and easily give your websites sophisticated interactivity. This book has walked you through some examples, like using jQuery plug-ins for form validation and rollover effects. When you venture into jQuery on your own, you’ll find it isn’t always simple, and you need a certain amount of knowledge to use it to its full extent. In this chapter, you’ll learn how to take jQuery further: how to use the documentation and how to take advantage of prepackaged interactivity with plug-ins, plus some useful tips and tricks. Useful jQuery Tips and Information jQuery makes programming easier, but on top of that, there are ways you can make programming jQuery easier. Here are a few bits of information that give you insight into jQuery so you can get the most from it. $() Is the Same as jQuery() In the many articles and blog posts on jQuery out there on the Web, you may encounter code like this: jQuery('p').css('color','#F03'); While you’re familiar with $('p'), which selects all the <p> tags on a page, you may be wondering about this jQuery() function. Actually, they are one and the same. The code above could also be written like this: $('p').css('color','#F03'); 521 USEFUL JQUERY TIPS AND INFORMATION $() is an alias for jQuery(), and the two are interchangeable. John Resig, the creator of jQuery, realized that programmers would be using the main jQuery function a lot, so rather than force people to type jQuery() over and over, he decided the shorter $() would be a good substitute. In practice, you can use either jQuery() or $(); it’s your choice. However, $() is faster to type, so you’ll probably want to stick with it (as most programmers do). NOTE Other JavaScript libraries, like Prototype (www.prototypejs.org), also use $(). If you happen to also use Prototype or another library that lays claim to the $ on your site, you might want to use jQuery() instead of $(). In addition, jQuery provides a special function to deal with this situation, named .noConflict(). You can read about it at http://api.jquery.com/jQuery.noConflict/. Saving Selections into Variables Every time you make a selection of page elements using $()—$('#tooltip'), for example—you’re calling the jQuery function. And each time you do that, a visitor’s browser has to run a bunch of code, which slows your programs down unnecessarily. For example, say you wanted to apply several jQuery functions to a selection like this: $('#tooltip').html('<p>An aardvark</p>'); $('#tooltip').fadeIn(250); $('#tooltip').animate({left : 100px},250); This code selects an element with an ID of tooltip and inserts a <p> tag into it. It then selects the element again and fades it into view. Finally, it selects the element a third time and then animates its left property to 100px. Each of those selections— each $('#tooltip')—runs the jQuery function. These three lines of code affect the same element, so you really only need to select it once. One approach (discussed earlier in the book on page 127) is to use jQuery’s chaining abilities. You select the elements then add one function after another to it like this: $('#tooltip').html('<p>An aardvark</p>').fadeIn(250).animate({left : 100px},250); But sometimes chaining gets unwieldy and hard to read. One way to deal with that is by adding a line break after each chained method. Because JavaScript isn’t that sensitive to the use of space and line breaks, you can do this: $('#tooltip').html('<p>An aardvark</p>') .fadeIn(250) .animate({left:100px},250); Even though .html, .fadeIn, and .animate are on separate lines, they’re really part of one long statement of chained methods. Another option is to only run the jQuery function a single time, and store its result in a variable that you reuse. Here’s how you could do that with the preceding code: 522 JAVASCRIPT & JQUERY: THE MISSING MANUAL 1 2 3 4 var tooltip = $('#tooltip') tooltip.html('<p>An aardvark</p>'); tooltip.fadeIn(250); tooltip.animate({left : 100px},250); USEFUL JQUERY TIPS AND INFORMATION Line 1 runs the jQuery function, creating a selection of an element with the ID of tooltip and stores it into a variable named tooltip. Once the selection is made and stored, you don’t need to do it again. You can simply use that variable (which now contains a jQuery selection) and run jQuery functions on it. When using this approach, many programmers like to add a $ before the variable name, which helps remind you that the variable is storing a jQuery selection as opposed to other data types like strings, variables, arrays, or object literals. For example: var $tooltip = $('#tooltip'); Storing a selection into a variable is also very common when using events. As you recall from page 139, when you are inside an event function, the variable $(this) refers to the element the event is applied to. However, each time you use $(this) you are calling the jQuery function, so repeated use of $(this) inside an event function just wastes computer power. Instead, you can store $(this) into a variable at the beginning of the event function and use it repeatedly without needing to continually call the jQuery function: $('a').click(function() { var $this = $(this); // store a reference to the <a> tag $this.css('outline','2px solid red'); var href = $this.attr('href'); window.open(href); return false; }); // end click Adding Content as Few Times as Possible In Chapter 4, you learned about some jQuery functions that let you add content to page elements: The .text() function (page 129), for example, lets you replace the text inside an element, and the .html() function (page 128) lets you replace the HTML inside of an element. For example, if you wished to insert an error message inside a span tag with the ID of passwordError, you could write this code: $('#passwordError').text('Passwords must by at least 7 characters long.'); Other functions let you add content after an element (append(); discussed on page 129) or before an element (prepend(); discussed on page 129). Adding and changing content lets you add error messages, pop up tooltips (page 321), and insert pull quotes (page 141), but it does require a lot from a browser. Each time you add content, the browser needs to do a lot of work—you’re basically changing the DOM (page 117) and when that happens, browsers do a lot of behindthe-scenes work. Changing the content a lot of times can significantly affect a web page’s performance. Chapter 15: Getting the Most from jQuery 523 USEFUL JQUERY TIPS AND INFORMATION It’s not the amount of content that matters—it’s the number of times you change the page that affects performance. For example, say you wanted to create a tooltip effect: When someone mouses over a box, for example, a div would appear with some additional content. To do this, you need to add the box and the additional content to the page. Here’s one way to add that div: 1 2 3 4 5 6 // add div to end of element $('#elemForTooltip').append('<div id="tooltip"></div'); // add headline to tooltip $('#tooltip').append('<h2>The tooltip title</h2>'); // add contents $('#tooltip').append('<p>The tooltip contents here</p>'); The code above will work just fine: Line 2 adds a div to the element the visitor will mouse over; line 4 adds a headline to the tooltip box; and line 6 adds a paragraph to the tooltip. However, the DOM is modified three times in the process with three different append operations. All of this processing is actually quite taxing on a web browser, and reducing the number of times you have to modify the DOM can significantly improve the performance of a page. In this example, you can reduce the number of append operations to just one by building the entire tooltip HTML, storing it in a variable, and then appending that variable’s contents to the page, like this: 1 var tooltip = '<div id="tooltip"><h2>The tooltip title</h2> ↵ <p>The tooltip contents here</p></div>'; 2 $('#elemForTooltip').append(tooltip); NOTE The ↵ symbol at the end of a line of code indicates that the next line should really be typed as part of the first line. But because a really long line of JavaScript code won’t fit on this book’s page, it’s broken up over two lines. Also note that a string is one case where JavaScript is sensitive about space and line breaks. You can’t break a string over multiple lines like this: var longString = "Now is the time for all good people to come to the aid of their country"; You’ll end up with a syntax error if you try. In this code, line 1 creates a variable containing all of the HTML for the tooltip, and line 2 appends that HTML to a page element. There’s only one append operation, and depending upon which browser the visitor views the page in, this code can be up to 20 times faster than using the three .append() functions. The bottom line is that if you want to inject a chunk of HTML into a spot on the page, do it in one single operation (or at least in as few as you can get away with) rather than add the HTML in parts using multiple inserts. 524 JAVASCRIPT & JQUERY: THE MISSING MANUAL Optimizing Your Selectors jQuery’s flexibility means you have many ways to achieve the same goal. For example, you can select a page element in a number of ways: you can use any CSS selector, or refine a jQuery selection using the DOM Traversal functions discussed on page 531. However, the following techniques will make your selections faster and your JavaScript programs more efficient: USEFUL JQUERY TIPS AND INFORMATION • Use ID selectors if at all possible. The fastest way to select a page element is to use an ID selector. Browsers from the dawn of JavaScript have provided a method for selecting elements with IDs, and it’s still the fastest way. If you’re worried about performance, then you might want to slap an ID on each element that you plan on selecting rather than depending upon other methods like a descendant selector. • Use IDs first, as part of a descendant selector. The problem with using just an ID selector is that you only ever retrieve a single element. What if you need to retrieve multiple elements like all the <a> tags inside a div, or the paragraphs on a page? If your page is structured in such a way that all the elements you wish to select are within an element with an ID, then use a descendant selector that includes the ID first. For example, say you want to select all the <a> tags on a page. It just so happens that all of those tags are also inside a div tag with an ID of main. It’s faster to use this selector: $('#main a') than this selector: $('a') • Use the .find() function. jQuery includes a function for finding elements within a selection. It works kind of like a descendant selector in that it locates tags inside of other tags. You’ll read more about this function on page 531, but in a nutshell, you start with a jQuery selection, slap on .find(), and pass a selector to it. In other words, you could write $('#main a') like this: $('#main').find('a'); In fact, in some situations, using .find() instead of a descendant selector is over two times as fast! NOTE You can try a speed test for the .find() function at http://jsperf.com/sawmac-selector-test. • Avoid too much specificity. You may be used to using CSS’s specificity rules to create CSS styles that target particular elements on a page. A rule like #main .sidebar .note ul.nav li a is very specific, but when you run it through the jQuery function, it can also perform slowly. If possible, either use a descendant selector that’s shorter and more refined—$('.sidebar .nav a'), for example—or use the .find() function mentioned in the previous point: $('#main'). find('. sidebar').find('.nav a'). Chapter 15: Getting the Most from jQuery 525 USING THE JQUERY DOCS Using the jQuery Docs The jQuery website provides very detailed documentation for jQuery at http://api. jquery.com/ (Figure 15-1). You’ll find useful links for how to get started with jQuery, where to seek help, tutorials, and more, but the most important section of the site deals with the jQuery API. API stands for application programming interface, and simply means the set of functions that jQuery lets you use, like the event handler functions you read about in Chapter 5 (.click(), .hover(), and so on), the CSS functions you learned about in Chapter 4 (.css(), .addClass(), and .removeClass()), and most importantly, the basic jQuery function itself—$()—which lets you select elements on a page. FIGURE 15-1 The main jQuery docs page contains links to lots of useful information. On the left side of the screen, you’ll find a complete listing of each of jQuery’s functions. In some cases, they’re grouped into topics like the Ajax functions, the Event functions, the Manipulation functions, and so on. The jQuery docs page provides information on every method available in jQuery. The main page actually lists all of them, which is useful if you know the name of the method, as the list is in alphabetical order, but otherwise it’s a bit overwhelming. Instead, you’ll probably want to select one of the categories in the lefthand navigation bar. Here are a few of the most useful categories: • Selectors (http://api.jquery.com/category/selectors/) provides access to some of the most helpful jQuery functions. This page is worth visiting often, as it lists the many different ways to use jQuery to select page elements. You learned about many of these in Chapter 4, but you’ll find even more ways when you visit this section of the jQuery documentation. 526 JAVASCRIPT & JQUERY: THE MISSING MANUAL Because there are so many jQuery functions related to selectors, you’ll see that the left sidebar provides sub-categories which group related selector functions such as basic selectors, form selectors, attribute selectors, and so on. USING THE JQUERY DOCS • Attributes (http://api.jquery.com/category/attributes/ ). Visit this page to find the various jQuery functions that get and set attributes of HTML elements such as adding a class to a tag, finding or setting the value of an attribute (like the href attribute on an <a> tag), or getting the value of a form element. NOTE You’ll often find the same function listed in more than one section of the jQuery documentation site. For example, the .val() function used to read and set the value of a form field is listed both under the Attributes and the Forms categories of the site. • Traversing (http://api.jquery.com/category/traversing/) refers to functions used to manipulate a set of page elements. For example, the .find() function lets you find an element inside a jQuery selection: This is handy when you want to select a page element (a <ul> tag for example), perform an operation on it (like add a class, or fade it into view), and then find another element inside that page element to do something else (for example, find an <li> tag inside the original <ul> tag). jQuery provides lots of functions for traversing HTML elements, and you’ll read about some of them later in this chapter. • Manipulation (http://api.jquery.com/category/manipulation/). Whenever you want to add or remove something from a page, you need to manipulate the page’s DOM. This page lists the many functions available for changing a page, including the ones you read about in Chapter 4 (page 127) like .html() to add HTML to a page, .text() to add text to a page, and so on. This category of functions is very important—a lot of JavaScript programming is about dynamically changing the content and appearance of a web page. • The CSS page (http://api.jquery.com/category/css/) lists jQuery functions used for reading or setting CSS-related properties on elements including adding or removing classes, directly setting CSS properties, and controlling or reading the height, width, and position of an element. You’ll learn about some of these functions on page 134. • Events (http://api.jquery.com/category/events/ ). In Chapter 5, you learned how to use jQuery to respond to user interaction like the mouse moving over a link, or the visitor clicking a button on the page. You’ll find a list of jQuery’s many event-related functions on this page. On page 160, you’ll learn about some advanced event functions. • The Effects page (http://api.jquery.com/category/effects/ ) provides access to information on jQuery’s effects-related functions like the .slideDown(), .fadeIn(), and .animate() functions you learned about in Chapter 6. • The Forms category (http://api.jquery.com/category/forms/ ) lists functions related to—drum roll, please—forms. It mainly lists events used with Chapter 15: Getting the Most from jQuery 527 USING THE JQUERY DOCS form elements, but also includes the .val() function for reading or setting the value of a form field, as well as a couple of functions to make it easy to submit a form using Ajax (Chapter 13). • The Ajax category (http://api.jquery.com/category/ajax/) lists functions related to dynamically updating a page based on information sent to or received from a web server. You read about Ajax in Chapter 13. • Utilities (http://api.jquery.com/category/utilities/ ). jQuery also provides a handful of functions dedicated to simplifying common programming tasks like finding an element inside an array, acting on each item inside an array or object (the $.each() function discussed on page 138), and a bunch of other geeky niceties. You may not need any of these functions at this point in your programming career (they don’t really tap into any cool effects, or help you update the content or appearance of a page), but as you get more advanced, it’s worth visiting this page on the jQuery documentation site. There are a few other categories of functions that are used less frequently, but still are worth knowing about: • The Data category (http://api.jquery.com/category/data/) lists functions related to adding data to page elements. jQuery provides a .data() function to add data to an element—think of it as a way to add name/value pairs to any page element, kind of like a mini-database. This and the other data-related functions can come in handy when working on a web application where you need to store and track data. For an understandable introduction to using these data functions, check out http://tutorialzine.com/2010/11/jquery-data-method/. • Deferred Object (http://api.jquery.com/category/deferred-object/). You don’t need to look much further than the introduction to this category (which explains that a deferred object “is a chainable utility object that can register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function”) to understand that jQuery’s Deferred Object is a complex beast. Basically, it helps with queuing up functions to control the order in which they run. If you want to learn more, visit the category page of the jQuery docs site. • Dimensions (http://api.jquery.com/category/dimensions/) refers to functions used to determine the width and height of objects. These functions are also listed under the CSS category mentioned earlier. • Internals (http://api.jquery.com/category/internals/) are a handful of functions of various degrees of usefulness. The .jquery property, for example, returns the version of jQuery in use on the page: // open alert box with version number alert($().jquery); // 1.6.2, for example You can lead a long, happy life without using any of the functions here. 528 JAVASCRIPT & JQUERY: THE MISSING MANUAL • The Offset category page (http://api.jquery.com/category/offset/ ) lists functions related to determining the position of an object relative to the screen or to its parent element. You’ll use these functions when setting or getting the position of an element on the page. USING THE JQUERY DOCS Reading a Page on the jQuery Docs Site Each jQuery function has its own page, documenting what it does and how it works. Figure 15-2 shows part of the page explaining jQuery’s .css() function. The page lists the functions name (.css() in this case), as well as listing the category and subcategories the function falls under. You can click on the category and subcategory links to jump up to a page listing all functions that fit that category. In some cases, a function serves double- or even triple-duty and acts differently based on the type and number of arguments you provide it. In that case, you’ll see the function listed in several different ways under the function title. For example, in Figure 15-2, you’ll see that the .css() function can accept one or two arguments (numbers 1 and 2 in the figure). The first way, #1, is listed as css( propertyName ). Here, propertyName indicates that you pass one argument to the function, which should be a CSS property name. jQuery then returns the value of that property for the specified element (notice “Returns: String” circled in Figure 15-2). The information listed on the page then lets you know that you pass one argument and receive a string in return. For example, say you want to determine the width of a <div> tag with the ID of tooltip; you can use this code: var tipWidth = $('#tooltip').css('width'); // get the width value In this code, 'width' is passed to the function, and a string value is returned. (However, in this case, because it’s a width, the string will be the number of pixels wide; the element is—'300', for example.) NOTE jQuery offers another variant—css( propertyNames )—which also returns the CSS property values of an element. But instead of accepting a single property name and returning a single value, it accepts an array (page 44) of property names and returns a JavaScript object (page 136) consisting of name/value pairs. The name is a CSS property name from the array and the value is the current value for that CSS property on the specified HTML element. A second way to use the .css() function is listed (#2) as css( propertyName, value ), indicating that you pass the function two arguments—the name of a CSS property and a value. Used this way, the .css() function sets the CSS property for the element. For example, if you wanted to set the width of a <div> tag with the ID of tooltip, you would pass width as the first argument, and the value you wish for the width as the second like this: $('#tooltip').css('width',300); // set div to 300px wide Chapter 15: Getting the Most from jQuery 529 USING THE JQUERY DOCS FIGURE 15-2 The docs page for each jQuery function lists all the different ways you can use a function. In this case, listed under Contents: you’ll see that you can pass the .css() function either a single argument (#1) or two arguments (#2). The function behaves differently depending on which of those two routes you go. Click the function example, and you’ll jump to the spot on the page that discusses how that example works. The documentation also lists two other ways to use the .css() function to set CSS properties: • .css( propertyName, function) indicates that you can set a CSS property using a function to dynamically generate a value. This is handy when you have a collection of page elements and you want to set slightly different values for each; for example, a series of divs that you wish to set the left property, but you want each div to be positioned next to each other at a different left position. • .css( properties ) is described on page 134, and means that you can pass an object literal in order to set several CSS properties and values in one step. The important thing to understand is that the same jQuery function can and often does take different arguments and does different things. The .css() function, for example, can both retrieve a CSS value and set a CSS value. You’ll frequently find jQuery functions working in this way as both “getters” (that is, they retrieve information about an element) and “setters” (that is, they set the value of a particular property for an element). 530 JAVASCRIPT & JQUERY: THE MISSING MANUAL The docs page will describe each use of the function and usually provides working examples of how the function works. The jQuery docs are well-maintained, and as far as technical documentation goes, pretty easy to read and understand. You should spend some time visiting these pages and especially reading up on the functions you use most often. TRAVERSING THE DOM Traversing the DOM You’ve learned how to select page elements using jQuery and basic CSS syntax: $('p'), for example, selects all of the paragraphs on a page. Once you select elements, you can do stuff to them, such as add or remove a class, change a CSS property, or make the elements disappear. But sometimes you want to find other page elements in relationship to your original selection. In JavaScript-speak, this is called Traversing the DOM (Document Object Model). Traversing the DOM happens frequently when you attach an event to an element but then want to do something to another element. For example, say you have a <div> tag with an ID of gallery; the div contains a series of thumbnail images. When a visitor clicks the div, you want the thumbnails to do something: shrink, grow, shake, or something like that. The event is attached to the <div> tag like this: $('#gallery').click(function() { }); // end click Inside the function, you need to add the programming code to animate the images. So, although the user clicks the div, you want do something to the images. In the code above, you’ve merely selected the <div> tag, and inside the function $(this) will refer to that div (if that’s news to you, turn to page 139 for a refresher on what $(this) means). So, although the <div> tag is the selected element inside the click function, you need to find the images inside that div. Fortunately, jQuery provides just such a solution: the .find() function. Its purpose is to generate a new selection of page elements by searching inside the current selection for other tags that match a given selector. So you can select the images inside the div by adding the bolded code below: $('#gallery').click(function() { $(this).find('img'); }); // end click The $(this).find('img') creates a new selection of elements; $(this) refers to the div, then .find('img') looks for every image inside that div. Of course, this code doesn’t do anything to the new selection, but you could add any of the effects you learned about in the last chapter. For example, say you want the images to fade out temporarily and then fade back in. You could use this code: $('#gallery').click(function() { $(this).find('img').fadeTo(500,.3).fadeTo(250,1); }); // end click Chapter 15: Getting the Most from jQuery 531 TRAVERSING THE DOM As you read on page 185, the fadeTo() function takes a duration and an opacity value as arguments. So this code first fades all of the images to 30% opacity in 500 milliseconds, and then fades it back to 100% opacity in 250 milliseconds (see the file find.html in the chapter15 tutorial folder to see this effect in action). In fact, traversing the DOM is such a common task that jQuery provides many functions that help you take a selection of elements and then locate other elements in relationship to the first. To better understand how they work, you’ll use a simple chunk of HTML represented in Figure 15-3: http://api.jquery.com/category/manipulation/. It’s a <div> tag with an ID of gallery containing four links, each of which is wrapped around an image. As discussed on page 122, you can use the relationships of a family to describe the relationships between tags on a page. For example, in Figure 15-3, the <div> tag is the parent of the <a> tags, and each <a> tag is the parent of the <img> tag inside it. Conversely, the <a> tags are children of the <div> tag, and each <a> tag is the sibling of the other <a> tags. Each <img> tag is the child of the <a> tag that wraps around them, and because there are no other tags inside each <a>, the <img> tags don’t have siblings. FIGURE 15-3 When you make a jQuery selection—for example, to add an event handler to an element, such as the <a> tags pictured here—you’ll often want to act on another tag in relation to that selection (for example, add an outline to the div tag or alter the img tag). jQuery’s DOM traversing functions can help. Here are a few of jQuery’s most useful DOM traversing functions: • .find(). Finds particular elements inside the current selection. You start with a jQuery selection, add .find(), and pass it a CSS selector like this: $('#gallery').find('img') This code finds all of the images inside the gallery div. Of course, you could achieve the same goals with a descendant selector like this $('#gallery img'). As mentioned earlier, you’re more likely to use .find() in a situation where you 532 JAVASCRIPT & JQUERY: THE MISSING MANUAL already have a selection that you’ve done something to—like attach a click event—to create a new selection to act on. TRAVERSING THE DOM You use .find() to select a descendant (a tag inside another tag) of the current selection. So in the example pictured in Figure 15-3, you could use .find() on a selection including the div to select either the <a> tags or the <img> tags. NOTE See page 531 to read about the huge performance benefits .find() offers. It’s generally a faster way to select elements than using a descendant selector. • .children() is similar to .find(). It also accepts a selector as an argument, but it limits its selection to immediate children of the current selection. For example, say you had a div tag that contains a series of other divs. When you click on the main div, it reveals previously hidden divs, and adds a red outline around them. Say you used the .find() function to achieve this goal like this: $('#mainDiv').click(function() { $(this).find('div').show().css('outline','red 2px solid'); }); A problem arises if one of the divs inside the main div also has a div tags inside it. .find('div') locates all div tags, even divs inside other divs. You may end up with a page that has outlines around all the divs, when what you want is simply an outline around the immediate child divs of the main div. To solve that dilemma, you can rewrite the preceding code using .children() like this: $('#mainDiv').click(function() { $(this).children('div').show().css('outline','red 2px solid'); }); Now this code finds only the divs that are immediate children of the main div and avoids any divs that might exist inside the child divs. • .parent(). Whereas .find() locates elements inside the current element, .parent() travels up the DOM locating the parent of the current tag. This could come in handy, for example, if you attach a hover event to the <a> tags pictured in Figure 15-3, but you want to perform an action on the <div> tag (for example, add a border or background color to the div. In this case, you’d use .parent() to locate the div and apply an action to it, like this: $('#gallery a').hover( function() { var $this = $(this); // add outline to link $this.css('outline','2px solid red'); // add background color to div $this.parent().css('backgroundColor','white'); }, function() { Chapter 15: Getting the Most from jQuery 533 TRAVERSING THE DOM var $this = $(this); // remove outline from link $this.css('outline',''); // remove background color from div $this.parent().css('backgroundColor',''); } ); // end hover In this example, hovering over a link adds an outline around that link, then selects the link’s parent (the div) and applies a background color. Mousing off the link removes both the outline and background color (see page 162 for more information on the .hover() event). See the file parent.html in the chapter15 tutorial folder for an example of this function in action. • .closest() finds the nearest ancestor that matches a particular selector. Unlike .parent(), which finds the immediate parent of the current tag, .closest() accepts a selector as an argument and finds the nearest ancestor that matches. For example, in Figure 15-3, each image is inside an <a> tag; in other words, the <a> tag is the parent of the image. However, what if you wanted to select the <div> tag that surrounds the <a> tags (an ancestor further up the HTML chain)? You could then use .closest() like this: 1 $('#gallery img').click(function() { 2 var $this = $(this); 3 $this.css('outline','2px red solid'); 4 $this.closest('div').css('backgroundColor','white'); 5 }); // end click In line 3, $(this) refers to the <img> tag; .closest('div') means find the nearest ancestor that’s a <div> tag. The closest ancestor is the <a> tag, but because it isn’t a div, jQuery skips it and finds the next ancestor, and so on and so on until it locates a <div>. • .siblings() comes in handy when you wish to select an element that’s at the same level as the current selection. Say you had the setup pictured in Figure 15-3; when a visitor clicks a link, you want all the other links to gently fade out and into view. In this case, the event—click—applies to a link tag, but the effect you wish to perform is to all the other links inside that div. In other words, you start with a link, but you want to select all that link’s siblings. You could do that like this: 1 $('#gallery a').click(function() { 2 $(this).siblings().fadeTo(500,.3).fadeTo(250,1); 3 }); // end click In the above code, $(this) refers to the clicked link, so .siblings() selects all of the other links in that div. The .siblings() function also can take an argument—the name of a selector—to limit the selected siblings to a certain type of tag. For example, say inside the 534 JAVASCRIPT & JQUERY: THE MISSING MANUAL <div> tag pictured in Figure 15-3, there’s a headline and introductory paragraph prior to the links. The headline and paragraph are both inside the <div> tag along with all of the <a> tags, also making them siblings of the <a> tag. In other words, given the preceding code, clicking a link would also cause that headline and paragraph to fade out and back into view. To limit the effect to just other links, you could rewrite line 2 to look like the following: MORE FUNCTIONS FOR MANIPULATING HTML $(this).siblings('a').fadeTo(500,.3).fadeTo(250,1); The 'a' inside siblings('a') limits the selection to just siblings that are also <a> tags. See the siblings.html file in the chapter15 tutorial folder to see how this function works. • .next() finds the next sibling of the current selection. You already saw this function in action in the One Page FAQ tutorial on page 174. In that tutorial, clicking a question opens and then closes a <div> tag containing the answer to that question. Each question is represented by an <h2> tag, and each answer by a div tag immediately following that <h2> tag. The headline and div are siblings, but they are also the siblings of all the other questions and answers on that page. So when the headline is clicked, you must select the immediate sibling (in other words, the next sibling). Like .siblings(), .next accepts an optional selector so you can limit selection to the next sibling of a particular type. (See the complete_faq.html file in the chapter15 tutorial folder for an example of .next() in action.) • .prev() works just like .next(), except that it selects the immediately preceding sibling. NOTE For more jQuery functions that let you traverse the DOM, visit http://api.jquery.com/category/traversing/. More Functions for Manipulating HTML You’ll often want to add, remove, and change the HTML of a page dynamically. For example, when a visitor clicks a submit button on a form, you might want the text “Send form information. Please wait.” to appear on the screen. Or when a visitor mouses over a photo, you want a box to appear on top of the photo with a caption and photo credits. In both cases, you need to add HTML to a page. You learned about the most common functions in Chapter 4 on page 127. Here’s a quick recap: • .text() replaces the text inside a selection with selection you pass to the function. For example: $('#error').text('You must supply an e-mail address'); • .html() works like .text() but lets you insert HTML instead of just text: $('#tooltip').html('<h2>Esquif Avalon</h2><p>Designed for canoe camping. </p>'); Chapter 15: Getting the Most from jQuery 535 MORE FUNCTIONS FOR MANIPULATING HTML POWER USERS’ CLINIC Putting an .end() to DOM Traversal In order to get the most done while writing the least amount of code, jQuery lets you chain functions together. Chaining is discussed on page 127, but in a nutshell it lets you select some pages elements, do one thing to them, then do another and another thing to them, simply by adding one function after another. For example, if you wanted to select all the paragraphs on a page and have them fade out of view then fade back into view, you could write this code: $('p').fadeOut(500).fadeIn(500); You can chain as many functions together as you’d like including the DOM Traversal methods discussed earlier. For example, you could select a <div> tag, add an outline around it, and then select all of the <a> tags inside that <div> and change the color of their text like this: $('div').css('outline','2px red solid'). find('a').css('color','purple'); Broken into pieces, this means: 1. $('div') selects all <div> tags. 2. .css('outline','2px red solid') adds a 2-pixel red outline to the div. 3. .find('a') then changes the selection from the div to all of the <a> tags inside the div. 4. .css('color','purple') makes the text of all of the links (not the div tag) purple. When adding one of the DOM Traversal functions to the chain, you alter the selection. For example, in the above code, jQuery first selects the div, then halfway through the chain, changes the selection to links inside the div. But sometimes when you want to return the selection to its original state. In other words, you want to select one thing, then select another thing in relation to the first selection, then return to the first selection. For example, say when a visitor clicks a div that has an opacity of 50%, you want to make the div fade to 100% opacity, change the color of the headline inside the div, add a background color to each p inside the div. One action—a click—needs to trigger several actions on different elements of the page. One way to do this would be like this: 536 $('div').click(function() { var $this = $(this); $this.fadeTo(250,1); // fade div in $this.find('h2').css('color','#F30'); $this.find('p') .('backgroundColor','#F343FF'); }); // end click Here’s a case where chaining would be really helpful—instead of calling $(this) three times, you could call it once and chain together the functions. However, you’d run into trouble if you tried to chain the functions like this: $('div').click(function() { $(this).fadeTo(250,1) .find('h2') .css('color','#F30') .find('p') .('backgroundColor','#F343FF'); }); // end click This might look right, but the problem occurs after the .find('h2')—which changes the selection from the div to the h2 tag inside the div. When the next .find() function runs—.find('p')—jQuery tries to find p tags inside the h2 tag, not inside the div. Fortunately, you can use jQuery’s .end() function to “rewind” a changed selection back to its original state. In the example above, you can use .end() to return the selection back to the div, and then find the <p> tags inside the div like this: $('div').click(function() { $(this).fadeTo(250,1) .find('h2') .css('color','#F30') .end() .find('p') .('backgroundColor','#F343FF'); }); // end click Notice the .end() after the .css('color', '#F30); this code returns the jQuery selection back to the div, so the following .find('p') will find all <p> tags inside the div. JAVASCRIPT & JQUERY: THE MISSING MANUAL • .append() lets you add HTML to the end of an element (for example, at the end of a div just before the closing </div> tag. This function is perfect for adding items to the bottom of a list. MORE FUNCTIONS FOR MANIPULATING HTML • .prepend() lets you add HTML to the beginning of an element (for instance, at the beginning of a div just after the opening <div> tag). • .before() adds content before the selection. • .after() works just like .before(), except that the content is added after the selection (after its closing tag). Which of these you use really depends on what your final goal is. JavaScript is really just about automating the tasks web designers normally perform manually: adding HTML and CSS to create a web page. If you’re writing a program to add content to a page dynamically—like a tooltip, an error message, a pull quote, and so on—just imagine what your finished product should look like and the HTML and CSS required to achieve it. For example, if you want to create a special message on the page when a visitor mouses over a button, try building a web page that demonstrates that message without using JavaScript—just build it with CSS and HTML. Once you have the HTML/ CSS mockup working, take a look at the HTML you used to achieve the effect: Is it placed before some other element? If so, use the .before() function. Is the HTML inside a specific tag? Then use the .append() or .prepend() functions. jQuery also supplies some functions for removing content from a page: • .replaceWith() completely replaces the selection (including the tag and everything inside it) with whatever you pass the function. For example, to replace a submit button on the page with the text “processing…” you could use this code: $(':submit').replaceWith('<p>processing...</p>'); • .remove() removes the selection from the DOM; essentially erasing it from the page. For example, to remove a div with the ID of error from the page, you’d write this code: $('#error').remove(); While you may only need the functions listed above and discussed in Chapter 4, jQuery provides other functions that provide additional ways of manipulating the HTML of a page: • .wrap() wraps each element in a selection in a pair of HTML tags. For example, what if you want to create a fancy caption effect for images on a page? You can start by selecting images from the page and wrapping them in a <div> with a class like figure and adding a <p> tag inside that div with a class of caption. Then, using CSS, you can format the div and caption in whatever way you’d like. Here’s one way to accomplish that: Chapter 15: Getting the Most from jQuery 537 MORE FUNCTIONS FOR MANIPULATING HTML 1 // loop through the list of images 2 $('img').each(function() { 3 // save reference to current image 4 var $this = $(this); 5 // get the alt property for the caption 6 var caption = $this.attr('alt'); 7 // add the HTML 8 $this.wrap('<div class="figure"></div>').after('<p>' + caption + '</ p>'); 9 }); // end each This code first selects all the images on the page and then loops through the list of images using the .each() function (page 138); on line 4, the current image in the loop is saved into a variable (a good practice, as described on page 522 in this chapter). In line 6, the alt attribute is retrieved from the image and stored in a variable named caption. Finally, line 8 wraps the image in a <div> tag, and adds a captions after the image using the .after() function described before. NOTE You can see the .wrap() code listed on line 8 in action in the file wrap.html in the chapter15 tutorial folder. You pass a complete set of tags to the .wrap() function—$('p').wrap('<div></ div>')—or even a nested set of tags like this: $('#example').wrap('<div id="outer"><div id="inner"></div></div>'); In the above code, jQuery will wrap the selection with the two divs, leaving the HTML something like this: <div id="outer"> <div id="inner"> <div id="example">This is the original code on the page</div> </div> </div> • .wrapInner() wraps the contents of each element in a selection in HTML tags. For example, say you had the following code in your HTML: <div id="outer"> <p>This is the contents of outer</p> </div> If the browser encounters the code $('#outer').wrapInner('<div id="inner"></div>'); it transforms the HTML on the page into this: <div id="outer"> <div id="inner"> <p>This is the contents of outer</p> </div> </div> 538 JAVASCRIPT & JQUERY: THE MISSING MANUAL • .unwrap() simply removes the parent tag surrounding the selection. For example, say a page has the following HTML: MORE FUNCTIONS FOR MANIPULATING HTML <div> <p>a paragraph</p> <div> Running the code $('p').unwrap() changes the HTML to: <p>a paragraph</p> The outer <div> is simply removed. Note that unlike the other functions discussed here, .unwrap() takes no arguments—in other words, don’t put anything inside the parentheses in .unwrap() or it won’t work. • .empty() removes all of the contents of a selection, but leaves the selection in place. For example, say you had a div on a web page with the ID of messageBox. Using JavaScript, you can dynamically add content to this div to display messages to a visitor as she interacts with the page. You might fill that div with lots of content headlines, images, and paragraphs to provide status messages to the visitor. You may want to empty that box at some point in the program (when there are no current messages to display, for example), but leave the box in place so you can later add status messages to it. To remove all the tags inside that box, you can use this code: $('#messageBox').empty(); As with .unwrap(), .empty() takes no arguments. NOTE jQuery provides even more functions for manipulating HTML. You can read about all of them at http:// api.jquery.com/category/manipulation/. Chapter 15: Getting the Most from jQuery 539 CHAPTER Going Further with JavaScript 16 T his chapter covers various concepts that can help make you a better JavaScript programmer. You don’t need most of the ideas here to write functioning JavaScript programs, so don’t worry if you don’t understand them all. The first few sections provide helpful tips and methods for working with strings, numbers, and dates, and once you’ve mastered the basics, these sections can really help you process visitor input in forms, work with HTML and HTML attributes, and generate dates for calendars. The section “Putting It All Together” on page 582 contains some good advice for beginners, but you can program happily for a long time without needing the information in the other sections in this chapter. But if you want to expand your skills, this chapter can point you in the right direction. Working with Strings Strings are the most common type of data you’ll work with: input from form fields, the path to an image, a URL, and HTML that you wish to replace on a page are all examples of the letters, symbols, and numbers that make up strings. You learned the basics of strings in Chapter 2, but JavaScript provides a lot of useful methods for working with and manipulating strings. Determining the Length of a String There are times when you want to know how many characters are in a string. For example, say you want to make sure that when someone creates an account on your top secret website, they create a new password that’s more than 6 letters but no more than 15. Strings have a length property that gives you just this kind of information. 541 WORKING WITH STRINGS Add a period after the name of the variable, followed by length to get the number of characters in the string: name.length. For example, assume you have a form with a text field. The field has the ID of password. To make sure the password has the proper number of characters, you could use a conditional statement (page 61) to test the password’s length like this: var password = $('#password').val(); if (password.length <= 6) { alert('That password is too short.'); } else if (password.length > 15) { alert('That password is too long.'); } The code in this example uses jQuery to get the value of the password field— $('#password').val()—but the rest of the code is plain JavaScript. A great way to use this validation snippet would be to put it into its own function like this: function verifyPassword() { var password = $('#password').val(); if (password.length <= 6) { alert('That password is too short.'); } else if (password.length > 15) { alert('That password is too long.'); } } You could then call it as part of a submit event handler (page 258) to test whether the visitor entered a long enough password when submitting the form: $('form').submit(verifyPassword); You could also place this code inside a blur() event (page 260) placed on the password input, so when a visitor tabs or clicks outside of the password field, you could check immediately to see if the password was the correct length. For example, say the password field had an ID of password, you could then send the verifyPassword function as an event handler for the blur event like this: $('#password').blur(verifyPassword); Changing the Case of a String JavaScript provides two methods to convert strings to all uppercase or all lowercase, so you can change “hello” to “HELLO” or “NOT” to “not”. Why, you might ask? Converting letters in a string to the same case makes comparing two strings easier. For example, say you created a quiz program like the one from Chapter 3 (page 94) and one of the questions is, “Who was the first American to win the Tour de France?” You might have some code like this to check the quiz taker’s answer: var correctAnswer = 'Greg LeMond'; var response = prompt('Who was the first American to win the Tour de France?', 542 JAVASCRIPT & JQUERY: THE MISSING MANUAL ''); if (response == correctAnswer) { // correct } else { // incorrect } WORKING WITH STRINGS The answer is Greg LeMond, but what if the person taking the quiz typed Greg Lemond? The condition would look like this: 'Greg Lemond' == 'Greg LeMond'. JavaScript treats uppercase letters as different than lowercase letters, so the lowercase 'm' in Lemond wouldn’t match the 'M' in LeMond, so the quiz taker would have gotten this question wrong. The same would happen if her caps lock key was down and she typed GREG LEMOND. To get around this difficulty, you can convert both strings to the same case and then compare them: if (response.toUpperCase() == correctAnswer.toUpperCase()) { // correct } else { // incorrect } In this case, the conditional statement converts both the quiz taker’s answer and the correct answer to uppercase, so 'Greg Lemond' becomes 'GREG LEMOND' and 'Greg LeMond' becomes 'GREG LEMOND'. To get the string all lowercase, use the toLowerCase() method like this: var answer = 'Greg LeMond'; alert(answer.toLowerCase()); // 'greg lemond' Note that neither of these methods actually alters the original string stored in the variable—they just return that string in either all uppercase or all lowercase. So in the above example, answer still contains 'Greg LeMond' even after the alert appears. (In other words, these methods work just like a function that returns some other value as described on page 91.) Searching a String: indexOf() Technique JavaScript provides several techniques for searching for a word, number, or other series of characters inside a string. Searching can come in handy, for example, if you want to know which web browser a visitor is using to view your website. Every web browser identifies information about itself in a string containing a lot of different statistics. You can see that string for yourself by adding this bit of JavaScript to a page and previewing it in a web browser: <script> alert(navigator.userAgent); </script>--> Chapter 16: Going Further with JavaScript 543 WORKING WITH STRINGS Navigator is one of a web browser’s objects, and userAgent is a property of the navigator object. The userAgent property contains a long string of information; for example, on Internet Explorer 10 running on Windows 8, the userAgent property is: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Trident/6.0). So, if you want to see if the Web browser was IE 10, you can just search the userAgent string for “MSIE 10”. One method of searching a string is the indexOf() method. Basically, after the string you add a period, indexOf(), and supply the string you’re looking for. The basic structure looks like this: string.indexOf('string to look for') The indexOf() method returns a number: If the search string isn’t found, the method returns –1. So if you want to check for Internet Explorer, you can do this: var browser = navigator.userAgent; // this is a string if (browser.indexOf('MSIE') != -1) { // this is Internet Explorer } In this case, if indexOf() doesn’t locate the string 'MSIE' in the userAgent string, it will return –1, so the condition tests to see if the result is not (!=) –1. When the indexOf() method does find the searched-for string, it returns a number that’s equal to the starting position of the searched-for string. The following example makes things a lot clearer: var quote = 'To be, or not to be.' var searchPosition = quote.indexOf('To be'); // returns 0 Here, indexOf() searches for the position of 'To be' inside the string 'To be, or not to be.' The larger string begins with 'To be', so indexOf() finds ‘To be’ at the first position. But in the wacky way of programming, the first position is considered 0, the second character (o) is at position 1, and the third character (a space in this case) is 2 (as explained on page 48, arrays are counted in the same way). The indexOf() method searches from the beginning of the string. You can also search from the end of the string by using the lastIndexOf() method. For example, in the Shakespeare quote, the word ‘be’ appears in two places, so you can locate the first 'be' using indexOf() and the last ‘be’ with lastIndexOf(): var quote = "To be, or not to be." var firstPosition = quote.indexOf('be'); // returns 3 var lastPosition = quote.lastIndexOf('be'); // returns 17 The results of those two methods are pictured in Figure 16-1. In both cases, if 'be' didn’t exist anywhere in the string, the result would be –1, and if there’s only one instance of the searched-for word, indexOf() and lastIndexOf() will return the same value—the starting position of the searched-for string within the larger string. 544 JAVASCRIPT & JQUERY: THE MISSING MANUAL WORKING WITH STRINGS FIGURE 16-1 The indexOf() and lastIndexOf() methods search for a particular string inside a larger string. If the search string is found, its position in the larger string is returned. Extracting Part of a String with slice() To extract part of a string, use the slice() method. This method returns a portion of a string. For example, say you had a string like http://www.sawmac.com and you wanted to eliminate the http:// part. One way to do this is to extract every character in the string that follows the http:// like this: var url = 'http://www.sawmac.com'; var domain = url.slice(7); // www.sawmac.com The slice() method requires a number that indicates the starting index position for the extracted string (Figure 16-2). In this example—url.slice(7)—the 7 indicates the eighth character in the string (remember, the first letter is at position 0). The method returns all of the characters starting at the specified index position to the end of the string. FIGURE 16-2 If you don’t supply a second argument to the slice() method, it just extracts a string from the specified position (7 in this example) all the way to the end of the string. You can also extract a specific number of characters within a string by supplying a second argument to the slice() method. Here’s the basic structure of the slice() method: string.slice(start, end); The start value is a number that indicates the position of the first character of the extracted string. The end value is a little confusing—it’s not the position of the last letter of the extracted string; it’s actually the position of the last letter + 1. For example, if you wanted to extract the first five letters of the string ‘To be, or not to be.’, you would specify 0 as the first argument, and 5 as the second argument. As you can see in Figure 16-3, 0 is the first letter in the string, and 5 is the sixth letter, but the Chapter 16: Going Further with JavaScript 545 FINDING PATTERNS IN STRINGS last letter specified is not extracted from the string. In other words, the character specified by the second argument is never part of the extracted string. TIP If you want to extract a specific number of characters from a string, just add that number to the starting value. For example, if you want to retrieve the first 10 letters of a string, the first argument would be 0 (the first letter) and the last would be 0 + 10 or just 10: slice(0,10). You can also specify negative numbers; for example, quote.slice(-6,-1). A negative number counts backwards from the end of the string, as pictured in Figure 16-3. FIGURE 16-3 The slice() method extracts a portion of a string. The actual string is not changed in any way. For instance, the string contained in the quote variable in this example isn’t changed by quote.slice(0,5). The method simply returns the extracted string, which you can store inside a variable, display in an alert box, or even pass as an argument to a function. TIP If you want, say, to extract a string that includes all the last X number of characters in a string, just give slice() a single value—a negative number that matches the number of letter you want. For example, to extract the last 6 letters of the quote string you’d write this: var end_of_string = quote.slice(-6); Finding Patterns in Strings Sometimes you wish to search a string, not for an exact value, but for a specific pattern of characters. For example, say you want to make sure when a visitor fills out an order form, he supplies a phone number in the correct format. You’re not actually looking for a specific phone number like 503-555-0212. Instead, you’re looking for a general pattern: three numbers, a hyphen, three numbers, another hyphen, and four numbers. You’d like to check the value the visitor entered, and if it matches the pattern (for example, it’s 415-555-3843, 408-555-3782, or 212-555-4828, and so on), then everything’s OK. But if it doesn’t match that pattern (for example, the visitor typed 823lkjxdfglkj), then you’d like to post a message like “Hey buddy, don’t try to fool us!” JavaScript lets you use regular expressions to find patterns within a string. A regular expression is a series of characters that define a pattern that you wish to search for. 546 JAVASCRIPT & JQUERY: THE MISSING MANUAL As with many programming terms, the name “regular expression” is a bit misleading. For example, here’s what a common regular expression looks like: FINDING PATTERNS IN STRINGS /^[-\w.]+@([a-zA-Z0-9][-a-zA-Z0-9]+\.)+[a-zA-Z]{2,4}$/ Unless you’re a super-alien from Omicron 9, there’s nothing very regular-looking about a regular expression. To create a pattern, you use characters like *, +, ?, and \w, which are translated by the JavaScript interpreter to match real characters in a string like letters, numbers, and so on. NOTE Pros often shorten the name regular expression to regex. Creating and Using a Basic Regular Expression To create a regular expression in JavaScript, you must create a regular expression literal, which is a series of characters between two forward slashes. For example, to create a regular expression that matches the word “hello”, you’d type this: var myMatch = /hello/; Just as an opening and closing quote mark creates a string, the opening / and closing / create a regular expression. There are several string methods that take advantage of regular expressions (you’ll learn about them starting on page 546), but the most basic method is the search() method. It works very much like the indexOf() method, but instead of trying to find one string inside another, larger string, it searches for a pattern (a regular expression) inside a string. For example, say you want to find ‘To be’ inside the string ‘To be or not to be.’ You saw how to do that with the indexOf() method on page 543, but here’s how you can do the same thing with a regular expression: var myRegEx = /To be/; // no quotes around regular expression var quote = 'To be or not to be.'; var foundPosition = quote.search(myRegEx); // returns 0 If the search() method finds a match, it returns the position of the first character matched, and if it doesn’t find a match, it returns –1. So in the above example, the variable foundPosition is 0 because ‘To be’ begins at the very beginning (the first character) of the string. As you’ll recall from page 543, the indexOf() method works in the same way. You might be thinking that if the two methods are the same, why bother with regular expressions? The benefit of regular expressions is that they can find patterns in a string, so they can make much more complicated and subtle comparisons than the indexOf() method, which always looks for a match to an exact string. For example, you could use the indexOf() method to find out if a string contains the Web address http://www.missingmanuals.com, but you’d have to use a regular expression to find any text that matches the format of a URL—exactly the kind of thing you want to Chapter 16: Going Further with JavaScript 547 FINDING PATTERNS IN STRINGS do when verifying if someone supplied a web address when posting a comment to your blog. However, to master regular expressions, you need to learn the often confusing symbols required to construct a regular expression. Building a Regular Expression While a regular expression can be made up of a word or words, more often you’ll use a combination of letters and special symbols to define a pattern that you hope to match. Regular expressions provide different symbols to indicate different types of characters. For example, a single period (.) represents a single character, any character, while \w matches any character (but not spaces, or symbols like $ or %). Table 16-1 provides a list of the most common pattern-matching characters. NOTE If this entire discussion of “regular” expressions is making your head hurt, you’ll be glad to know this book provides some useful regular expressions (page 553) that you can copy and use in your own scripts (without really knowing how they work). TABLE 16-1 Common pattern-matching symbols for regular expressions 548 CHARACTER MATCHES . Any one character—will match a letter, number, space, or other symbol. \w Any word character including a–z, A–Z, the numbers 0–9, and the underscore character: _. \W Any character that’s not a word character. It’s the exact opposite of \w. \d Any digit 0–9. \D Any character except a digit. The opposite of \d. \s A space, tab, carriage return, or new line. \S The opposite of the \s. Anything but a space, tab, carriage return, or newline. ^ The beginning of a string. This is useful for making sure no other characters come before whatever you’re trying to match. $ The end of a string. Use $ to make sure the characters you wish to match are at the end of a string. For example, /com$/ matches the string “com”, but only when it’s the last three letters of the string. In other words, /com$/ would match “com” in the string “Infocom”, but not ‘com’ in ‘communication’. \b A space, beginning of the string, end of string, or any nonletter or number character such as +, =, or ‘. Use \b to match the beginning or ending of a word, even if that word is at the beginning or ending of a string. [] Any one character between the brackets. For example, [aeiou] matches any one of those letters in a string. For a range of characters, use a hyphen: [a-z] matches any one lower case letter; [0-9] matches any one number (the same as \d). JAVASCRIPT & JQUERY: THE MISSING MANUAL FINDING PATTERNS IN STRINGS CHARACTER MATCHES [^ ] Any character except one in brackets. For example, [^aeiouAEIOU] will match any character that isn’t a vowel. [^0-9] matches any character that’s not a number (the same as \D). | Either the characters before or after the | character. For example, a|b will match either a or b, but not both. (See page 557 for an example of this symbol in action.) \ Used to escape any special regex symbol (*,.,\,/, for instance) to search for a literal example of the symbol in a string. For example, . in regex-speak means “any character,” so you need escape a period -- like this \. -- if you want to really match a period in a string. Learning regular expressions is a topic better presented by example, so the rest of this section walks you through a few examples of regular expressions to help you wrap your mind around this topic. Assume you want to match five digits in a row—perhaps to check if there’s a U.S. Zip code in a string: 1. Match one digit. The first step is simply to figure out how to match one number. If you refer to Table 16-1, you’ll see that there’s a special regex symbol for this, \d, which matches any single number. 2. Match five digits in a row. Because \d matches a single number, a simple way to match five numbers is with this regular expression: \d\d\d\d\d. (page 552, however, covers a more compact way to write this.) 3. Match only five digits. A regular expression is like a precision-guided missile: It sets its target on the first part of a string that it matches. So, you sometimes end up with a match that’s part of a complete word or set of characters. This regular expression matches the first five numbers in a row that it encounters. For example, it will match 12345 in the number 12345678998. Obviously, 12345678998 isn’t a Zip code, so you need a regex that targets just five digits. The \b character (called the word boundary character) matches any non-letter or non-number character, so you could rewrite your regular expression like this: \b\d\d\d\d\d\b. You can also use the ^ character to match the beginning of a string and the $ character to match the end of a string. This trick comes in handy if you want the entire string to match your regular expression. For example, if someone typed “kjasdflkjsdf 88888 lksadflkjsdkfjl” in a Zip code field on an order form, you might want to ask the visitor to clarify (and fix) her Zip code before ordering. After all, you’re really looking for something like 97213 (with no other characters in the string). In this case, the regex would be ^\d\d\d\d\d$. Chapter 16: Going Further with JavaScript 549 FINDING PATTERNS IN STRINGS NOTE Zip codes can have more than five digits. The ZIP + 4 format includes a dash and four additional digits after the first five, like this: 97213-1234. For a regular expression to handle this possibility, see page 553. 4. Put your regex into action in JavaScript. Assume you’ve already captured a user’s input into a variable named zip, and you want to test to see if the input is in the form of a valid five-number Zip code: var zipTest = /^\d\d\d\d\d$/; //create regex if (zip.search(zipTest) == -1) { alert('This is not a valid zip code'); } else { // is valid format } The regex example in these steps works, but it seems like a lot of work to type \d five times. What if you want to match 100 numbers in a row? Fortunately, JavaScript includes several symbols that can match multiple occurrences of the same character. Table 16-2 includes a list of these symbols. You place the symbol directly after the character you wish to match. For example, to match five numbers, you can write \d{5}. The \d matches one number, then the {5} tells the JavaScript interpreter to match five numbers. So \d{100} would match 100 digits in a row. Let’s go through another example. Say you wanted to find the name of any GIF file in a string. In addition, you want to extract the filename and perhaps use it somehow in your script (for example, you can use the match() method described on page 558). In other words, you want to find any string that matches the basic pattern of a GIF filename, such as logo.gif, banner.gif, or ad.gif. Here are the steps you should follow: 1. Identify the common pattern between these names. To build a regular expression, you first need to know what pattern of characters you’re searching for. Here, since you’re after GIFs, you know all the filenames will end in .gif. In other words, there can be any number of letters or numbers or other characters before .gif. But there should be at least one character before the .gif: a.gif is a valid filename, but just .gif isn’t 2. Find .gif. You’re after the literal string '.gif', so you might think that part of the regular expression would just be .gif. However, if you check out Table 4-3, you’ll see that a period has special meaning as a “match any character” character. So .gif would match .gif, but it would also match “tgif.” A period matches any single character so in addition to matching a period, it will also match the “t” in tgif. To create a regex with a literal period, add a slash before it; so \. translates to “find me the period symbol.” So the regex to find .gif would be \.gif. 550 JAVASCRIPT & JQUERY: THE MISSING MANUAL 3. Find one or more characters before .gif. You want to match something like a.gif, photo.gif, but not just .gif (that wouldn’t be a valid GIF file). To find at least one character, you can use .+, which translates to “find one character (.) zero at least once (+).” However, if you used that to create a regular expression like .+\.gif, you could end up matching more than just a filename: that regular expression matches all of the letters in any string. For example, if you have the string ‘the file is logo.gif’, the regex .+\.gif will match everything up to and including .gif. What you really want is just logo.gif. To do that, use the \S character, which matches any nonspace character: \S+\. gif translates to “find at least one non-space character (no tabs, spaces, carriage returns, or new lines) followed by .gif. That matches just logo.gif in the string. FINDING PATTERNS IN STRINGS 4. Make sure nothing follows gif. The regular expression now finds just a filename…or does it? Regular expressions can be really tricky. For example, if you use the regex you’ve created so far on a string like “e-mail alex.gifford@example”, you’d match “alex.gif,” which isn’t a filename at all. To make sure that doesn’t happen, you should also check to make sure that nothing follows the gif part. You can do that by adding a word boundary (\b)—like this \S+\.gif\b—to make sure you don’t match parts of a larger string that happens to include .gif in it. 5. Make the search case-insensitive. There’s one last wrinkle in this regular expression: It only finds files that end in .gif, but .GIF is also a valid file extension, so this regex wouldn’t pick up on a name like logo.GIF. To make a regular expression ignore the difference between upper and lowercase letters, you use the i argument when you create the regular expression: /\S+\.gif\b/i Notice that the i goes outside of the pattern and to the right of the / that defines the end of the regular expression pattern. 6. Put it into action: var testString = 'The file is logo.gif create by alex.gifford@example.com'; // the string to test var gifRegex = /\S+\.gif\b/i; // the regular expression var results = testString.match(gifRegex); var file = results[0]; // logo.gif This code pulls out the filename from the string. (You’ll learn how the match() method works on page 558.) Grouping Parts of a Pattern You can use parentheses to create a subgroup within a pattern. Subgroups come in very handy when using any of the characters in Table 16-2 to match multiple instances of the same pattern. Chapter 16: Going Further with JavaScript 551 FINDING PATTERNS IN STRINGS TABLE 16-2 Characters used for matching multiple occurrences of the same character or pattern CHARACTER MATCHES ? Zero or one occurrences of the previous character (or group of characters), meaning the previous item is optional, but if it does appear, it can only appear once. For example, the regex colou?r will match both “color” and “colour”, but not “colouur”. + One or more occurrences of the previous item. The previous item must appear at least once. * Zero or more occurrences of the previous item. The previous item is optional and may appear any number of times. For example, .* matches any number of characters, or, no characters at all! {n} An exact number of occurrences of the previous item. For example, \d{3} only matches three numbers in a row. {n, } The previous item n or more times. For example, a{2,} will match the letter “a” two or more times, which would match “aa” in the word “aardvark” and “aaaa” in the word “aaaahhhh”. {n,m} The previous item at least n times but no more than m times. So \d{3,4} will match three or four digits in a row (but not two digits in a row, nor five digits in a row). For example, say you want to see if a string contains either “Apr” or “April”—both of those begin with “Apr”, so you know that you want to match that, but you can’t just match “Apr” because you’d also match the “Apr” in “Apricot” or “Aprimecorp.” So, you must match “Apr” followed by a space or other word ending (that’s the \b regular expression character described in Table 16-1) or April followed by a word ending. In other words, the “il” is optional. Here’s how you could do that using parentheses: var sentence = 'April is the cruelest month.'; var aprMatch = /Apr(il)?\b/; if (sentence.search(aprMatch) != -1) { // found Apr or April } else { //not found } The regular expression used here—/Apr(il)?\b/—makes the “Apr” required, but the subpattern—(il)—optional (that ? character means zero or one time). Finally, the \b matches the end of a word, so you won’t match “Apricot” or “Aprilshowers.” (See the box “Using Subpatterns to Replace Text” on page 561 for another use of subpatterns.) To make this regular expression more foolproof, you could add a word boundary— \b—at the beginning of the regex as well: var aprMatch = /\bApr(il)?\b/; 552 JAVASCRIPT & JQUERY: THE MISSING MANUAL Adding the word boundary at the beginning of the regex would safeguard against encountering a mismatch like wApril, or SApr. (Granted, you aren’t likely to encounter strings like those, but better safe than sorry.) FINDING PATTERNS IN STRINGS TIP You can find a complete library of regular expressions at www.regexlib.com. At this website, you’ll find a regular expression for any situation. Useful Regular Expressions Creating a regular expression has its challenges. Not only do you need to understand how the different regular expression characters work, but you then must figure out the proper pattern for different possible searches. For example, if you want to find a match for a Zip code, you need to take into account the fact that a Zip code may be just five numbers (97213) or 5+4 (97213-3333). To get you started on the path to using regular expressions, here are a few common ones. NOTE If you don’t feel like typing these regular expressions (and who could blame you), you’ll find them already set up for you in a file named example_regex.txt in the chapter16 folder that’s part of the tutorial download. (See page 12 for information on downloading the tutorial files.) U.S. ZIP CODE Postal codes vary from country to country, but in the United States they appear as either five numbers, or five numbers followed by a hyphen and four numbers. Here’s the regex that matches both those options: \d{5}(-\d{4})? NOTE For regular expressions that match the postal codes of other countries, visit http://regexlib.com/ Search.aspx?k=postal+code. That regular expression breaks down into the following smaller pieces: • \d{5} matches five digits, as in 97213. • () creates a subpattern. Everything between the parentheses is considered a single pattern to be matched. You’ll see why that’s important in a moment. • -\d{4} matches the hyphen followed by four digits, like this: -1234. • ? matches zero or one instance of the preceding pattern. Here’s where the parentheses come in: (-\d{4}) is treated as a single unit, so the ? means match zero or one instance of a hyphen followed by four digits. Because you don’t have to include the hyphen + four, that pattern might appear zero times. In other words, if you’re testing a value like 97213, you’ll still get a match because the hyphen followed by four digits is optional. Chapter 16: Going Further with JavaScript 553 FINDING PATTERNS IN STRINGS NOTE To make sure an entire string matches a regular expression, begin the regex with ^ and end it with $. For example, if you want to make sure that someone only typed a validly formatted U.S. Zip code into a Zip code form field, use the regex ^\d{5}(-\d{4})?$. to prevent a response like “blah 97213 blah blah.” U.S. PHONE NUMBER U.S. phone numbers have a three-digit area code followed by seven more digits. However, people write phone numbers in many different ways, like 503-555-1212, (503) 555-1212, 503.555.1212, or just 503 555 1212. A regex for this pattern is: \(?\d{3}\)?[ .-]\d{3}[ .-]\d{4} NOTE For regular expressions that match the phone number format of other countries, visit http://regexlib. com/Search.aspx?k=phone+number. This regex looks pretty complicated, but if you break it down (and have a good translation like the following), it comes out making sense: • \( matches a literal opening parenthesis character. Because parentheses are used to group patterns (see the previous Zip code example), the opening parentheses has special meaning in regular expressions. To tell the JavaScript interpreter to match an actual opening parenthesis, you need to escape the character (just like escaping the quotes discussed on page 28) with the forward slash character. • ? indicates that the ( character is optional, so a phone number without parentheses like 503-555-1212 will still match. • \d{3} matches any three digits. • \)? matches an optional closing parenthesis. • [ .-] will match either a space, a period, or a hyphen. (Note that normally you have to escape a period like this \. in order to tell the JavaScript interpreter that you want to match the period character and not treat it as the special regular expression symbol that matches any character; however, when inside brackets, a period is always treated literally.) • \d{3} matches any three digits. • [ .-] will match either a space, period, or hyphen. • \d{4} matches any four digits. EMAIL ADDRESS Checking for a valid email address is a common chore when accepting user input from a form. A lot of people try to get away without trying to provide a valid email using a response like “none of your business,” or people just mistype their email 554 JAVASCRIPT & JQUERY: THE MISSING MANUAL address (missing@sawmac.commm, for example). The following regex can check to see if a string contains a properly formatted email address: FINDING PATTERNS IN STRINGS [-\w.]+@([A-z0-9][-A-z0-9]+\.)+[A-z]{2,4} NOTE This regex doesn’t check to see if an address is somebody’s real, working email address; it just checks that it’s formatted like a real email address. This regex breaks down like this: • [-\w.]+ matches a hyphen, any word character, or a period one or more times. So it will match “bob,” “bob.smith,” or “bob-smith.” • @ is the @ sign you find in an email address: missing@sawmac.com. • [A-z0-9] matches one letter or number. • [-A-z0-9]+ matches one or more instances of a letter, number, or hyphen. • \. is a period character, so it would match the period in sawmac.com (http:// www.sawmac.com). • + matches one or more instances of the pattern that includes the above three matches. This character allows for subdomain names like bob@mail.sawmac. com. • [A-z]{2,4} is any letter 2, 3, or 4 times. This matches the com in .com, or uk in .uk. NOTE The email regex listed above doesn’t match all technically valid email addresses. For example, !#$%&'*+-/=?^_`.{|}~@example.com is technically a valid email address, but the regex described here won’t match it. It’s designed to find email addresses that people would actually use. If you really want to be accurate, you can use the following regex. Type this expression on a single line: /^[\w!#$%&\'*+\/=?^`{|}~.-]+@(?:[a-z\d][a-z\d-]*(?:\.[a-z\d][a-z\d-]*)?)+\. (?:[a-z][a-z\d-]+)$/i DATE A date can be written in many different ways; for example, 09/28/2014, 9-28-2014, 09 28 2014, or even 09.28.2014. (And those are just formats for the United States. In other parts of the world, the day appears before the month, like 28.09.2014.) Because your visitors may enter a date in any one of these formats, you need a way to check to see if they supplied a validly formatted date. (In the box on page 570, you’ll learn how to convert any of these formats into a single, standard format, so you can make sure all the dates you receive on a form are formatted correctly.) Here’s the regex that checks for a correctly entered date: ([01]?\d)[-\/ .]([0123]?\d)[-\/ .](\d{4}) Chapter 16: Going Further with JavaScript 555 FINDING PATTERNS IN STRINGS • () surrounds the next two regex patterns to group them. Together they form the number for the month. • [01]? matches either 0 or 1 and the ? makes this optional. This is for the first number in a month. Obviously it can’t be bigger than 1—there’s no 22 month. In addition, if the month is January through September, you might just get 5 instead of 05. That’s why it’s optional. • \d matches any number. • [-\/ .] will match a hyphen, a forward slash, a period, or a space character. These are the acceptable separators between the month and day, like 10/21, 10 21, 10.21, or 10-21. • () is the next subpattern, which is meant to capture the day of the month. • [0123]? matches either 0, 1, 2, or 3 zero or one time. There’s no 40th day of the month, so you limit the first number of the month to one of these four digits. This pattern is optional (as determined by the ? character), because someone might just type 9 instead of 09 for the ninth day of the month. • \d matches any digit. • [-\/ .] is the same as above. • () captures the year. • \d{4} matches any four digits, like 1908 or 2880. NOTE While it’s possible to write form validation yourself using some of the regex patterns discussed here, it’s not your only alternative. Someone has already solved the problem, so why not use their hard work and free yourself to solve other problems? For an easier way to make sure your site’s visitors are supplying the correct type of information to web forms, use a jQuery plug-in like the jQuery Form Validation plug-in discussed on page 273. WEB ADDRESS Matching a web address is useful if you’re asking a visitor for his website address and you want to make sure he’s supplied one, or if you want to scan some text and identify every URL listed. A basic regular expression for URLs is: ((\bhttps?:\/\/)|(\bwww\.))\S* This expression is a little tricky because it uses lots of parentheses to group different parts of the expression. Figure 16-4 can help guide you through this regular expression. One set of parentheses (labeled 1) wraps around two other parenthetical groups (2 and 3). The | character between the two groups represents “or”. In other words, the regular expression needs to match either 2 or 3. 556 JAVASCRIPT & JQUERY: THE MISSING MANUAL FINDING PATTERNS IN STRINGS FIGURE 16-4 You can group expressions using parentheses and look for either one of two expressions by using the | (pipe) character. For example, the outer expression (1) will match any text that matches either 2 or 3. • ( is the start of the outer group (1 in Figure 16-4). • ( is the start of inner group (2 in Figure 16-4). • \b matches the beginning of a word. • http matches the beginning of a complete web address that begins with http. • s? is an optional s. A web page may be sent via a secure connection, so a valid web address may also begin with https. • :\/\/ matches ://. Because the forward slash has meaning in regular expressions, you need to precede it by a backslash to match the forward slash character. • ) is the end of the inner group (2 in Figure 16-4). Taken together, this group will match either http:// or https://. • | matches either one or the other group (2 or 3 in Figure 16-4). • ( is the start of second inner group (3 in Figure 16-4). • \b matches the beginning of a word. • www\. matches www.. • ) is the end of the second inner group (3 in Figure 16-4). This group will capture a URL that is missing the http:// but begins with www. • ) is the end of the outer group (1 in Figure 16-4). At this point, the regular expression will match text that begins with http://, https://, or www. • \S* matches zero or more nonspace characters. This expression isn’t foolproof (for example, it would match a nonsensical URL like http://#$*%&*@*), but it’s relatively simple, and will successfully match real URLs like http://www.sawmac.com/missing/js/index.html. TIP To see if a string only contains a URL (nothing comes before or after the URL), use the ^ and $ characters at the beginning and end of the regular expression and remove the \b characters: ^((https?:\/\/)|(www\.))\S*$. Chapter 16: Going Further with JavaScript 557 FINDING PATTERNS IN STRINGS Matching a Pattern The search() method described on page 547 is one way to see if a string contains a particular regular expression pattern. The match() method is another. You can use it with a string to not only see if a pattern exists within the string, but to also capture that pattern so you can use it later in your script. For example, say you have a text area field on a form for a visitor to add a comment to your site. Perhaps you want to check if the comments include a URL, and if so, get the URL for further processing. The following code finds and captures a URL using match(): // a string to test for a URL var text='my website is www.missingmanuals.com'; // create a regular expression var urlRegex = /((\bhttps?:\/\/)|(\bwww\.))\S*/ // find a match for the regular expression in the string var url = text.match(urlRegex); alert(url[0]); // www.missingmanuals.com First, the code creates a variable containing a string that includes the URL www. missingmanuals.com. This variable is just for test purposes here (so you can see what the match() method does. If you actually wanted to test the contents of a text area on a form, you could use code like this: var text = $('#comments').val() ; Next, the code creates a regular expression to match a URL (see page 556 for the details on this regex). Finally, it runs the match() method on the string. The match() function is a string method, so you start with the name of a variable containing a string, add a period, followed by match(). You pass the match() method a regular expression to match. In this example, the variable url holds the results of the match. If the regular expression pattern isn’t found in the string, then the result is a special JavaScript value called null. If there is a match, the script returns an array—the first value of the array is the matched text. For instance, in this example, the variable url contains an array, with the first array element being the matched text. In this case, url[0] contains www.missingmanuals.com (see page 44 for more on arrays). NOTE In JavaScript, a null value is treated the same as false, so you could test to see if the match() method actually matched something like this: var url = text.match(urlRegex); if (! url) { //no match } else { //match } 558 JAVASCRIPT & JQUERY: THE MISSING MANUAL The match() method also supplies some additional information. In addition to an array element whose first item is the matched string, match() also returns an index property that indicates the position within the string where the match begins. For example: FINDING PATTERNS IN STRINGS var string = 'To be or not'; ar regex = /be/; var result = string.match(regex); alert(result.index); // alerts the number 3 The variable result stores the values returned from the match() method. In this case, there’s an array, and the first and only item in the array is the matched string: result[0] contains the matched text “be”. The match() method also adds the index property to the result. In this example, that property has the value 3 because “be” starts in the fourth position in the string (remember, JavaScript counts from 0). This is the same value that would be returned by the regular search() method (page 547) and is similar to how the indexOf() method (page 543) returns the starting position for a substring within a larger string. Also, it’s the same value you’d use in the slice() method (page 545) to extract a substring from a larger string. The match() method also returns additional array elements, if you’ve used ( ) to create subpatterns, as described in the box on page 561. The first item in the array is always the matched string, but if you’ve used subpatterns, each additional array element contains the matched value within the subpattern. MATCHING EVERY INSTANCE OF A PATTERN The match() method works in two different ways, depending on how you’ve set up your regular expression. In the preceding example, the method returns an array with the first matched text and an index property containing the starting position of the match (as well as additional array elements if you used subpatterns in your regular expression). In other words, if you had a long string containing multiple URLs, only the first URL would be found. However, you can also turn on a regular expression’s global search property to search for more than one match in a string. You make a search global by adding a g at the end of a regular expression when you create it (just like the i used for a case-insensitive search, as discussed on page 551): var urlRegex = /((\bhttps?:\/\/)|(\bwww\.))\S*/g Notice that the g goes outside of the ending / (which is used to enclose the actual pattern). This regular expression performs a global search; when used with the match() method, it searches for every match within the string and will return an array of all matched text—a great way to find every URL in a blog entry, for example, or every instance of a word in a long block of text. You could rewrite the code from the top of this page using a global search, like this: // create a variable containing a string with a URL var text='there are a lot of great websites like ↵ www.missingmanuals.com and http://www.oreilly.com'; Chapter 16: Going Further with JavaScript 559 FINDING PATTERNS IN STRINGS // create a regular expression with global search var urlRegex = /((\bhttps?:\/\/)|(\bwww\.))\S*/g // find a match for the regular expression in the string var url = text.match(urlRegex); alert(url[0]); // www.missingmanuals.com alert(url[1]); // http://www.oreilly.com You can determine the number of matches by accessing the length property of the resulting array: url.length. This example would return the number 2 because two URLs were found in the tested string. In addition, you access each matched string by using the array’s index number (as described on page 48); so in this example, url[0] is the first match and url[1] is the second. Bear in mind, using a global regex search with the match() method doesn’t return an index value for string matches, nor will it return any information on subpatterns. A global search only returns an array containing each match within the searched string. Replacing Text You can also use regular expressions to replace text within a string. For example, say you have a string that contains a date formatted like this: 10.28.2014. However, you want the date to be formatted like this: 10/28/2014. The replace() method can do that. It takes this form: string.replace(regex,'replacement string'); The replace() method takes two arguments: The first is a regular expression that you wish to find in the string; the second is a string that replaces any matches to the regular expression. So, to change the format of 10.28.2008 to 10/28/2008, you could do this: 1 2 3 4 var date='10.28.2014'; // a string var replaceRegex = /\./g // a regular expression var date = date.replace(replaceRegex, '/'); // replace . with / alert(date); // 10/28/2014 Line 1 creates a variable and stores the string '10.28.2014' in it. In a real program, this string could be input from a form. Line 2 creates the regular expression: The / and / mark the beginning and end of the regular expression pattern; the \. indicates a literal period; and the g means a global replace—every instance of the period will be replaced. If you left out the g, only the first matched period would be replaced, and you’d end up with '10/28.2008'. Line 3 performs the actual replacement—changing each . to a /, and stores the result back into the date variable. Finally, the newly formed date—10/28/2014—is displayed in an alert box. 560 JAVASCRIPT & JQUERY: THE MISSING MANUAL FINDING PATTERNS IN STRINGS POWER USERS’ CLINIC Using Subpatterns to Replace Text The replace() method not only can replace matched text (like the . in 10.28.2008) with another string (like /), but it can also remember subpatterns within a regular expression and use those subpatterns when replacing text. A subpattern is any part of a regular expression enclosed in parentheses. For example, the (il) in the regular expression /Apr(il)?\b/ is a subpattern. The use of the replace() method demonstrated on page 560 changes 10.28.2008 to 10/28/2008. But what if you also want to put other formatted dates like 10 28 2008 or 10-28-2008 into the same 10/28/2008 format? Instead of writing multiple lines of JavaScript code to replace periods, spaces, and hyphens, you can create a general pattern to match any of these formats: var date='10-28-2008'; var regex = /([01]?\d)[-\/ .]([0123]?\d) [-\/ .](\d{4})/; date = date.replace(regex, '$1/$2/$3'); This example uses the regular expression described on page 555 to match a date. Notice the groups of patterns within parentheses—for example, ([01]?\d). Each subpattern matches one part of the date. The replace() method remembers matches to those subpatterns, and can use them as part of the replacement string. In this case, the replacement string is '$1/$2/$3'. A dollar sign followed by a number represents one of the matched subpatterns. $1, for example, matches the first subpattern—the month. So this replacement string translates to “put the first subpattern here, followed by a /, followed by the second subpattern match, followed by another /, and finally followed by the last subpattern.” Trying Out Regular Expressions You’ll find sample regular expressions in the example_regex.txt file in the testbed folder in the tutorial files. In addition, you’ll find a file named regex_tester.html in the testbed folder. You can open this web page in a browser and try your hand at creating your own regular expressions (Figure 16-5). Just type the string you’d like to search in the “String to Search” box, and then type a regular expression in the box (leave out the beginning and ending / marks used when creating a regex in JavaScript and just type the search pattern). You can then select the method you’d like to use—Search, Match, or Replace—and any options, like case-insensitivity or global search. Click the Run button and see how your regex works. Chapter 16: Going Further with JavaScript 561 WORKING WITH NUMBERS FIGURE 16-5 This sample page, included with the tutorial files, lets you test out regular expressions using different methods—like Search or Match—and try different options such as case-insensitive or global searches. Working with Numbers Numbers are an important part of programming. They let you perform tasks like calculating a total sales cost, determining the distance between two points, or simulating the roll of a die by generating a random number from 1 to 6. JavaScript gives you many different ways of working with numbers. Changing a String to a Number When you create a variable, you can store a number in it like this: var a = 3.25; However, there are times when a number is actually a string. For example, if you use the prompt() method (page 42) to get visitor input, even if someone types 3.25, you’ll end up with a string that contains a number. In other words, the result will be '3.25' (a string) and not 3.25 (a number). Frequently, this method doesn’t cause a problem—the JavaScript interpreter usually converts a string to a number when it seems like a number is called for. For example: 562 JAVASCRIPT & JQUERY: THE MISSING MANUAL WORKING WITH NUMBERS var a = '3'; var b = '4'; alert(a*b); // 12 In this example, even though the variables a and b are both strings, the JavaScript interpreter converts them to numbers to perform the multiplication (3 x 4) and return the result: 12. However, when you use the + operator, the JavaScript interpreter won’t make that conversion, and you can end up with some strange results: var a = '3'; var b = '4'; alert(a+b); // 34 In this case, both a and b are strings; the + operator not only does mathematical addition, it also combines (concatenates) two strings together (page 36). So instead of adding 3 and 4 to get 7, in this example, you end up with two strings fused together: 34. When you need to convert a string to a number, JavaScript provides several ways: • Number() converts whatever string is passed to it into a number, like this: var a = '3'; a = Number(a); // a is now the number 3 So the problem of adding two strings that contain numbers could be fixed like this: var a = '3'; var b = '4'; var total = Number(a) + Number(b); // 7 A faster technique is the + operator, which does the same thing as Number(). Just add a + in front of a variable containing a string, and the JavaScript interpreter converts the string to a number. var a = '3'; var b = '4'; var total = +a + +b // 7 The downside of either of these two techniques is that if the string contains anything except numbers, a single period, or a + or – sign at the beginning of the string, you’ll end up with a non-number, or the JavaScript value NaN, which means “not a number” (page 564). • parseInt() tries to convert a string to a number as well. However, unlike Number(), parseInt() will try to change even a string with letters to a number, as long as the string begins with numbers. This command can come in handy when you get a string like '20 years' as the response to a question about someone’s age: Chapter 16: Going Further with JavaScript 563 WORKING WITH NUMBERS var age = '20 years'; age = parseInt(age); //20 The parseInt() method looks for either a number or a + or – sign at the beginning of the string and continues to look for numbers until it encounters a nonnumber. So in the preceding example, it returns the number 20 and ignores the other part of the string, ' years'. In addition to a string value, the parseInt() method takes a second argument, called a radix value, which determines which numbering system to use. In most cases, you will use a base 10 system, which is the decimal system you’re used to. But that’s not the only way to count numbers; there are also base 8 or octal numbers and base 16 or hexadecimal numbers. NOTE Octal numbers begin with 0, so it’s possible to run into a situation where you’re using parseInt() on the string "010" and because the string begins with 0, the browser may think it’s an octal number and give you a weird result. In this case, the octal number 10 is the decimal value of 8. Some browsers default to octal numbers in this type of case, and other browsers (and the current JavaScript standard) default to decimal. In other words, you may end up with different results in different browsers. The upshot is, it’s always a safe practice to specify a decimal method for the parseInt() method: var age = '010' years; age = parseInt(age,10); // 10 • parseFloat() is like parseInt(), but you use it when a string might contain a decimal point. For example, if you have a string like '4.5 acres', you can use parseFloat() to retrieve the entire value including decimal places: var space = '4.5 acres'; space = parseFloat(space); // 4.5 If you used parseInt() for this example, you’d end up with just the number 4 because parseInt() only tries to retrieve whole numbers (integers). Which of these methods you use depends on the situation: If your goal is to add two numbers, but they’re strings, then use Number() or the + operator. However, if you want to extract a number from a string that might include letters, like '200px' or '1.5em', then use parseInt() to capture whole numbers (200, for example) or parseFloat() to capture numbers with decimals (1.5, for example). Testing for Numbers When using JavaScript to manipulate user input, you often need to verify that the information supplied by the visitor is of the correct type. For example, if you ask for people’s years of birth, you want to make sure they supply a number. Likewise, when you’re performing a mathematical calculation, if the data you use for the calculation isn’t a number, then your script might break. 564 JAVASCRIPT & JQUERY: THE MISSING MANUAL To verify that a string is a number, use the isNaN() method. This method takes a string as an argument and tests whether the string is “not a number.” If the string contains anything except a plus or minus (for positive and negative numbers) followed by numbers and an optional decimal value, it’s considered “not a number,” so the string '-23.25' is a number, but the string '24 pixels' is not. This method returns either true (if the string is not a number) or false (if it is a number). You can use isNaN() as part of a conditional statement like this: WORKING WITH NUMBERS var x = '10'; // is a number if (isNaN(x)) { // won't run } else { // will run } Rounding Numbers JavaScript provides a way to round a fractional number to an integer—for example, rounding 4.5 up to 5. Rounding comes in handy when you’re performing a calculation that must result in a whole number. For example, say you’re using JavaScript to dynamically set a pixel height of a <div> tag on the page based on the height of the browser window. In other words, the height of the <div> is calculated using the window’s height. Any calculation you make might result in a decimal value (like 300.25), but because there’s no such thing as .25 pixels, you need to round the final calculation to the nearest integer (300, for example). You can round a number using the round() method of the Math object. The syntax for this looks a little unusual: Math.round(number) You pass a number (or variable containing a number) to the round() method, and it returns an integer. If the original number has a decimal place with a value below .5, the number is rounded down; if the decimal place is .5 or above, it is rounded up. For example, 4.4 would round down to 4, while 4.5 rounds up to 5. Here’s an example: var decimalNum = 10.25; var roundedNum = Math.round(decimalNum); // 10 NOTE JavaScript provides two other methods for rounding numbers: Math.ceil() and Math. floor(). You use them just like Math.round(), but Math.ceil() always rounds the number up (for example, Math.ceil(4.0001) returns 5), while Math.floor() always rounds the number down: Math. floor(4.99999) returns 4. To keep these two methods clear in your mind, think a ceiling is up, and a floor is down. Formatting Currency Values When calculating product costs or shopping cart totals, you’ll usually include the cost, plus two decimals out, like this: 9.99. But even if the monetary value is a whole Chapter 16: Going Further with JavaScript 565 WORKING WITH NUMBERS number, it’s common to add two zeros, like this: 10.00. And a currency value like 8.9 is written as 8.90. Unfortunately, JavaScript doesn’t see numbers that way: It leaves the trailing zeros off (10 instead of 10.00, and 8.9 instead of 8.90, for example). Fortunately, there’s a method for numbers called toFixed(), which lets you convert a number to a string that matches the number of decimal places you want. To use it, add a period after a number (or after the name of a variable containing a number), followed by toFixed(2): var cost = 10; var printCost = '$' + cost.toFixed(2); // $10.00 The number you pass the toFixed() method determines how many decimal places to go out to. For currency, use 2 to end up with numbers like 10.00 or 9.90; if you use 3, you end up with 3 decimal places, like 10.000 or 9.900. If the number starts off with more decimal places than you specify, the number is rounded to the number of decimal places specified. For example: var cost = 10.289; var printCost = '$' + cost.toFixed(2); // $10.29 In this case, the 10.289 is rounded up to 10.29. NOTE The toFixed() method only works with numbers. So if you use a string, you end up with an error: var cost='10';//a string var printCost='$' + cost.toFixed(2);//error To get around this problem, you need to convert the string to a number as described on page 37, like this: var cost='10';//a string cost = +cost; // or cost = Number(cost); var printCost='$' + cost.toFixed(2);//$10.00 Creating a Random Number Random numbers can help add variety to a program. For example, say you have an array of questions for a quiz program (like the quiz tutorial on page 94). Instead of asking the same questions in the same order each time, you can randomly select one question in the array. Or, you could use JavaScript to randomly select the name of a graphic file from an array and display a different image each time the page loads. Both of these tasks require a random number. JavaScript provides the Math.random() method for creating random numbers. This method returns a randomly generated number between 0 and 1 (for example, .9716907176080688 or .10345038010895868). While you might not have much need for numbers like those, you can use some simple math operations to generate a whole number from 0 to another number. For example, to generate a number from 0 to 9, you’d use this code: 566 JAVASCRIPT & JQUERY: THE MISSING MANUAL Math.floor(Math.random()*10); This code breaks down into two parts. The part inside the Math.floor() method— Math.random()*10—generates a random number from 0 up to 10. That will generate numbers like 4.190788392268892; however, when using floor() the random number is never 10 (though it can be 0). To get a whole number, the random result is passed to the Math.floor() method, which rounds any decimal number down to the nearest whole number, so 3.4448588848 becomes 3 and .1111939498984 becomes 0. WORKING WITH NUMBERS If you want to get a random number between 1 and another number, just multiply the random() method by the uppermost number, and use the Math.ceil() method (which rounds a number up to the nearest integer). For example, if you want to simulate a die roll to get a number from 1 to 6: var roll = Math.ceil(Math.random()*6); // 1,2,3,4,5 or 6 RANDOMLY SELECTING AN ARRAY ELEMENT You can use the Math.random() method to randomly select an item from an array. As discussed on page 48, each item in an array is accessed using an index number. The first item in an array uses an index value of 0, and the last item in the array is accessed with an index number that’s 1 minus the total number of items in the array. Using the Math.random() method makes it really easy to randomly select an array item: var people = ['Ron','Sally','Tricia','Bob']; //create an array var random = Math.floor(Math.random() * people.length); var rndPerson = people[random]; // The first line of this code creates an array with four names. The second line does two things: First, it generates a random number from 0 up to (but not including) the number of items in the array (people.length)—in this example, a number from 0 up to 4. Then it uses the Math.floor() method to round down to the nearest integer, so it will produce the number 0, 1, 2, or 3. Finally, it uses that number to access one element from the array and store it in a variable named rndPerson. A FUNCTION FOR SELECTING A RANDOM NUMBER Functions are a great way to create useful, reusable snippets of code (page 85). If you use random numbers frequently, you might want a simple function to help you select a random number between any two numbers—for example, a number between 1 and 6, or 100 and 1,000. The following function is called using two arguments—the first is the lowest possible value (1 for example), and the second is the largest possible value (6 for example): function rndNum(from, to) { return Math.floor((Math.random()*(to - from + 1)) + from); } To use this function, add it to your web page (as described on page 85), and then call it like this: var dieRoll = rndNum(1,6); // get a number between 1 and 6 Chapter 16: Going Further with JavaScript 567 DATES AND TIMES Dates and Times If you want to keep track of the current date or time, turn to JavaScript’s Date object. This special JavaScript object lets you determine the year, month, day of the week, hour, and more. To use it, you create a variable and store a new Date object inside it like this: var now = new Date(); The new Date() command creates a Date object containing the current date and time. Once created, you can access different pieces of time and date information using various date-related methods as listed in Table 16-3. For example, to get the current year, use the getFullYear() method like this: var now = new Date(); var year = now.getFullYear(); NOTE new Date() retrieves the current time and date as determined by each visitor’s computer. In other words, if someone hasn’t correctly set his computer’s clock, then the date and time won’t be accurate. TABLE 16-3 Methods for accessing parts of the Date object METHOD WHAT IT RETURNS getFullYear() The year: 2014, for example. getMonth() The month as an integer between 0 and 11: 0 is January and 11 is December. getDate() The day of the month—a number between 1 and 31. getDay() The day of the week as a number between 0 and 6. 0 is Sunday, and 6 is Saturday. getHours() Number of hours on a 24-hour clock (a number between 0 and 23). For example, 11p.m. is 23. getMinutes() Number of minutes between 0 and 59. getSeconds() Number of seconds between 0 and 59. getTime() Total number of milliseconds since January 1, 1970 at midnight (see the box on page 570). Getting the Month To retrieve the month for a Date object, use the getMonth() method, which returns the month’s number: var now = new Date(); var month = now.getMonth(); However, instead of returning a number that makes sense to us humans (as in 1 meaning January), this method returns a number that’s one less. For example, January is 568 JAVASCRIPT & JQUERY: THE MISSING MANUAL 0, February is 1, and so on. If you want to retrieve a number that matches how we think of months, just add 1 like this: DATES AND TIMES var now = new Date(); var month = now.getMonth()+1; //matches the real month There’s no built-in JavaScript command that tells you the name of a month. Fortunately, JavaScript’s strange way of numbering months comes in handy when you want to determine the actual name of the month. You can accomplish that by first creating an array of month names, then accessing a name using the index number for that month: var months = ['January','February','March','April','May', 'June','July','August','September', 'October','November','December']; var now = new Date(); var month = months[now.getMonth()]; The first line creates an array with all twelve month names, in the order they occur (January–December). Remember that to access an array item you use an index number, and that arrays are numbered starting with 0 (page 47). So to access the first item of the array months, you use months[0]. So, by using the getMonth() method, you can retrieve a number to use as an index for the months array and thus retrieve the name for that month. Getting the Day of the Week The getDay() method retrieves the day of the week. And as with the getMonth() method, the JavaScript interpreter returns a number that’s one less than what you’d expect: 0 is considered Sunday, the first day of the week, while Saturday is 6. The name of the day of the week is usually more useful for your visitors, so you can use an array to store the day names and use the getDay() method to access the particular day in the array, like this: var days = ['Sunday','Monday','Tuesday','Wednesday', 'Thursday','Friday','Saturday']; var now = new Date(); var dayOfWeek = days[now.getDay()]; Getting the Time The Date object also contains the current time, so you can display the current time on a web page or use the time to determine if the visitor is viewing the page in the a.m. or p.m. You can then do something with that information, like display a background image of the sun during the day, or the moon at night. Chapter 16: Going Further with JavaScript 569 DATES AND TIMES POWER USERS’ CLINIC The Date Object Behind the Scenes JavaScript lets you access particular elements of the Date object, such as the year or the day of the month. However, the JavaScript interpreter actually thinks of a date as the number of milliseconds that have passed since midnight on January 1, 1970. For example, Wednesday, December 1, 2014, is actually 1417420800000 to the JavaScript interpreter. That isn’t a joke: As far as JavaScript is concerned, the beginning of time was midnight on January 1, 1970 at UTC (what used to be called “Greenwich Mean Time”). That date (called the “Unix epoch”) was arbitrarily chosen in the 70s by programmers creating the Unix operating system, so they could all agree on a way of keeping track of time. Since then, this way of tracking a date has become common in many programming languages and platforms. Whenever you use a Date method like getFullYear(), the JavaScript interpreter does the math to figure out (based on how many seconds have elapsed since January 1, 1970) what year it is. If you want to see the number of milliseconds for a particular date, you use the getTime() method: var sometime = new Date(); var msElapsed = sometime.getTime(); Tracking dates and times as milliseconds makes it easier to calculate differences between dates. For example, you can determine the amount of time until next New Year’s Day by first getting the number of milliseconds that will have elapsed from 1/1/1970 to when next year rolls around and then subtracting the number of milliseconds that have elapsed from 1/1/1970 to today: // milliseconds from 1/1/1970 to today var today = new Date(); // milliseconds from 1/1/1970 to next new year var nextYear = new Date(2015,0,1); // calculate milliseconds from today to next year var timeDiff = nextYear - today; The result of subtracting two dates is the number of milliseconds difference between the two. If you want to convert that into something useful, just divide it by the number of milliseconds in a day (to determine how many days) or the number of milliseconds in an hour (to determine how many hours), and so on: var second = 1000; // 1000 milliseconds in a second var minute = 60*second; // 60 seconds in a minute var hour = 60*minute; // 60 minutes in an hour var day = 24*hour; // 24 hours in a day var totalDays = timeDiff/day; // total number of days (In this example, you may have noticed a different way to create a date: new Date(2015,0,1). You can read more about this method on page 573.) You can use the getHours(), getMinutes(), and getSeconds() methods to get the hours, minutes, and seconds. So to display the time on a web page, add the following in the HTML where you wish the time to appear: var now = new Date(); var hours = now.getHours(); var minutes = now.getMinutes(); var seconds = now.getSeconds(); document.write(hours + ":" + minutes + ":" + seconds); 570 JAVASCRIPT & JQUERY: THE MISSING MANUAL This code produces output like 6:35:56 to indicate 6 a.m., 35 minutes, and 56 seconds. However, it will also produce output that you might not like, like 18:4:9 to indicate 4 minutes and 9 seconds after 6 p.m. One problem is that most people reading this book, unless they’re in the military, don’t use the 24-hour clock. They don’t recognize 18 as meaning 6 p.m. An even bigger problem is that times should be formatted with two digits for minutes and seconds (even if they’re a number less than 10), like this: 6:04:09. Fortunately, it’s not difficult to adjust the script to match those requirements. DATES AND TIMES CHANGING HOURS TO A.M. AND P.M. To change hours from a 24-hour clock to a 12-hour clock, you need to do a couple of things. First, you need to determine if the time is in the morning (so you can add 'am' after the time) or in the afternoon (to append 'pm'). Second, you need to convert any hours greater than 12 to their 12-hour clock equivalent (for example, change 14 to 2 p.m.). Here’s the code to do that: 1 2 3 4 5 6 7 8 9 10 11 12 13 var now = new Date(); var hour = now.getHours(); var am_pm; if (hour < 12) { am_pm = 'am'; } else { am_pm = 'pm'; } hour = hour % 12; if (hour==0) { hour = 12; } hour = hour + ' ' + am_pm; NOTE The column of numbers at the far left is just line numbering to make it easier for you to understand the following discussion. Don’t type these numbers into your own code! Lines 1 and 2 grab the current date and time and store the current hour into a variable named hour. Lines 3–7 determine if the hour is in the afternoon or morning; if the hour is less than 12 (the hour after midnight is 0), then it’s the morning (a.m.); otherwise, it’s the afternoon (p.m.). Line 8 introduces a mathematical operator called modulus and represented by a percent (%) sign. It returns the remainder of a division operation. For example, 2 divides into 5 two times (2 x 2 is 4), with 1 left over. In other words, 5 % 2 is 1. So in this case, if the hour is 18, 18 % 12 results in 6 (12 goes into 18 once with a remainder of 6). 18 is 6 p.m., which is what you want. If the first number is smaller than the number divided into it (for example, 8 divided by 12), then the result is the original number. For example, 8 % 12 just returns 8; in other words, the modulus operator doesn’t change the hours before noon. Chapter 16: Going Further with JavaScript 571 DATES AND TIMES Lines 9–11 take care of two possible outcomes with the modulus operator. If the hour is 12 (noon) or 0 (after midnight), then the modulus operator returns 0. In this case, hour is just set to 12 for either 12 p.m. or 12 a.m. Finally, line 12 combines the reformatted hour with a space and either “am” or “pm”, so the result is displayed as, for example, “6 am” or “6 pm”. PADDING SINGLE DIGITS As discussed on the previous page, when the minutes or seconds values are less than 10, you can end up with weird output like 7:3:2 p.m. To change this output to the more common 7:03:02 p.m., you need to add a 0 in front of the single digit. It’s easy with a basic conditional statement: 1 2 3 4 var minutes = now.getMinutes(); if (minutes < 10) { minutes = '0' + minutes; } Line 1 grabs the minutes in the current time, which in this example could be 33 or Line 2 simply checks if the number is less than 10, meaning the minute is a single digit and needs a 0 in front of it. Line 3 is a bit tricky because you can’t normally add a 0 in front of a number: 0 + 2 equals 2, not 02. However, you can combine strings in this way so '0' + minutes means combine the string '0' with the value in the minutes variable. As discussed on page 37, when you add a string to a number, the JavaScript interpreter converts the number to a string as well, so you end up with a string like '08'. You can put all of these parts together to create a simple function to output times in formats like 7:32:04 p.m., or 4:02:34 a.m., or even leave off seconds altogether for a time like 7:23 p.m.: function getTime(secs) { var sep = ':'; //separator character var hours, minutes, seconds, time; var now = new Date(); var am_pm; hours = now.getHours(); if (hours < 12) { am_pm = 'am'; } else { am_pm = 'pm'; } hours = hours % 12; if (hours == 0) { hours = 12; } time = hours; minutes = now.getMinutes(); 572 JAVASCRIPT & JQUERY: THE MISSING MANUAL if (minutes<10) { minutes = '0' + minutes; } time += sep + minutes; if (secs) { seconds = now.getSeconds(); if (seconds < 10) { seconds = '0' + seconds; } time += sep + seconds; } return time + ' ' + am_pm; DATES AND TIMES } You’ll find this function in the file getTime.js in the chapter16 folder in the Tutorials. You can see it in action by opening the file time.html (in that same folder) in a web browser. To use the function, either attach the getTime.js file to a web page, or copy the function into a web page or another external JavaScript file. To get the time, just call the function like this: getTime(), or, if you want the seconds displayed as well, getTime(true). The function will return a string containing the current time in the proper format. Creating a Date Other Than Today So far, you’ve seen how to use new Date() to capture the current date and time on a visitor’s computer. But what if you want to create a Date object for next Thanksgiving or New Year’s? JavaScript lets you create a date other than today in a few different ways. You might want to do this if you’d like to do a calculation between two dates: for example, “How many days until the new year?” When using the Date() method, you can also specify a date and time in the future or past. The basic format is this: new Date(year,month,day,hour,minutes,seconds,milliseconds); For example, to create a Date for noon on New Year’s Day 2015, you could do this: var ny2015 = new Date(2015,0,1,12,0,0,0); This code translates to “create a new Date object for January 1, 2015, at 12 o’clock, 0 minutes, 0 seconds, and 0 milliseconds.” You must supply at least a year and month, but if you don’t need to specify an exact time, you can leave off milliseconds, seconds, minutes, and so on. For example, to just create a date object for January 1, 2015, you could do this: var ny2015 = new Date(2015,0,1); NOTE Remember that JavaScript uses 0 for January, 1 for February, and so on, as described on page 568. Chapter 16: Going Further with JavaScript 573 DATES AND TIMES CREATING A DATE THAT’S ONE WEEK FROM TODAY As discussed in the box on page 570, the JavaScript interpreter actually treats a date as the number of milliseconds that have elapsed since midnight, Jan 1, 1970, UTC. Another way to create a date is to pass a value representing the number of milliseconds for that date: new Date(milliseconds); So another way to create a date for January 1, 2015, would be like this: var ny2015 = new Date(1420099200000); Of course, because most of us aren’t human calculators, you probably wouldn’t think of a date like this. However, milliseconds come in very handy when you’re creating a new date that’s a certain amount of time from another date. For example, when setting a cookie using JavaScript, you need to specify a date at which point that cookie is deleted from a visitor’s browser. To make sure a cookie disappears after one week, you need to specify a date that’s one week from today. NOTE The example code just shown—new Date(1420099200000);—won’t work for everyone. It only applies to the UTC-8 time zone, the Pacific time zone on the west coast of the United States. That’s because web browsers take time zone into account and adjust the browser’s clock based on the difference in UTC time as described in the box on page 570. To create a date that’s one week from now, you could do the following: var var var var now = new Date(); // today nowMS = now.getTime(); // get # milliseconds for today week = 1000*60*60*24*7; // milliseconds in one week oneWeekFromNow = new Date(nowMS + week); The first line stores the current date and time in a variable named now. Next, the getTime() method extracts the number of milliseconds that have elapsed from January 1, 1970, to today. The third line calculates the total number of milliseconds in a single week (1000 milliseconds/sec * 60 seconds/min * 60 minutes/hr * 24 hours/ day * 7 days/week). Finally, the code creates a new date by adding the number of milliseconds in a week to today. NOTE JavaScript’s Date object has many different functions to help with computing dates and dealing with different locations. You can find a complete reference for the Date object at https://developer.mozilla.org/ en-US/docs/Web/JavaScript/Reference/Global_Objects/Date. 574 JAVASCRIPT & JQUERY: THE MISSING MANUAL WRITING MORE EFFICIENT JAVASCRIPT POWER USERS’ CLINIC Dealing with Different Time Zones Computers do more than just keep track of seconds, minutes, and days. They also need to coordinate their time with the time of other computers located around the world in different time zones. After all, 8:00 p.m. in Moscow is not the exact same moment as 8:00 p.m. in San Francisco. Because those two cities are across the globe from each other, and the sun sets and rises at nearly the exact opposite time, 8:00 p.m. in Moscow is 8:00 a.m. in San Francisco and vice versa. (Or, if Daylight Saving Time is in effect, 8:00 p.m. in Moscow is 9:00 a.m. in San Francisco.) To help computers (and people) in different time zones keep in sync, software developers use a convention called UTC or Coordinated Universal Time. This time zone used to be called Greenwich Mean Time and is marked by the 0° longitude meridian. Unless you live in England, France, Spain, or the African nations that are vertically in line with Greenwich, England, you live in a time zone that is offset from UTC. San Francisco is UTC -8, which makes it is 8 hours behind UTC time. When it’s 9:15 p.m. in London, it’s 1:15 p.m. in San Francisco. Moscow is UTC +4, so when it’s 9:15 p.m. in London, it’s 1:15 a.m. in Moscow. (Again, these times will vary depending on whether Daylight Saving or Summer Time is in effect). JavaScript’s Date object provides a function for determining your local time offset (that is, how many hours your time differs from UTC time): var now = new Date(); var offset = now.getTimezoneOffset(); If you’re on a computer in San Francisco, and you check the offset, you’ll get a value of either 480 or 420. The number represents the total number of minutes different your computer is from UTC time, so 480 is 8 hours, and 420 is 7 hours (if it’s Daylight Saving time). If your region participates in Daylight Saving time, your computer and web browser keep track of that, too (aren’t computers smart?). In general, you don’t need to worry about converting time zones. JavaScript runs on your web visitors’ computers, so when you do time computations, like spitting out the current time, the browser will adapt to the visitor’s time zone and print a time that’s right for them. Writing More Efficient JavaScript Programming is a lot of work. Programmers are always looking for ways to do things faster and with fewer lines of code. While there are lots of tips and tricks, the following techniques are especially useful for working with JavaScript and jQuery. Putting Preferences in Variables One important lesson that programmers learn is how to extract details from scripts so they are more flexible and easier to update. For example, say you want to change the color of a paragraph of text to orange when a visitor clicks on it. You could do that with jQuery using the css() function (page 134) like this: $('p').click(function() { $(this).css('color','#F60'); }); In this case, the color orange (#F60) is hard-coded into this step. Say you apply this same color in other steps (maybe to add a background color when the visitor Chapter 16: Going Further with JavaScript 575 WRITING MORE EFFICIENT JAVASCRIPT mouses over a table cell). You might be tempted to write #F60 into those steps as well. A better approach is to place the color into a variable at the beginning of your script and then use that variable throughout your script: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 $(document).ready(function() { var hColor='#F60'; $('p').click(function() { $(this).css('color',hColor); }); $('td').hover( function() { $(this).css('backgroundColor',hColor); }, function() { $(this).css('backgroundColor','transparent'); } ); }); //end ready() In this example, the variable hColor now holds a hexadecimal color value—that variable is used both in the click event for the <p> tags, and in a hover event for the </p></div></div></span></span></span></div></button></div></div></div></a></div></div></div></div></article></div></div></div></div></div></div></ul></h1></ul></li></ul></li></ul></li></ul></div></div></div></div></div></div></div></div></h1></div></div></div></div></div></div></div></div></div></div></div></div></h1></div></h2></div></div></li></ul></ul></div></ul></li><table><tbody><tr><td> tags. If you later decide orange isn’t your thing, you can change the value stored in the variable—var hColor='#F33';—and now the script will use that color. You could make the above code even more flexible by uncoupling the connection between the color used for the <p> tags and </p></td><td> tags. Currently, they’re both set to the same color, but if you want to make it so you could eventually assign different colors to each, you could add an additional variable to your code: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 $(document).ready(function() { var pColor='#F60'; var tdColor=pColor; $('p').click(function() { $(this).css('color',pColor); }); $('td').hover( function() { $(this).css('backgroundColor',tdColor); }, function() { $(this).css('backgroundColor','transparent'); } ); }); //end ready() Now, the click and hover events use the same color—#F60 (because the tdColor variable is set to the value of pColor in line 3). However, if you later decide that you want the table cells to have a different color, just change line 3 like this: 576 JAVASCRIPT & JQUERY: THE MISSING MANUAL var tdColor='#FF3'; When writing a JavaScript program, identify values that you explicitly name in your code and turn them into variables. Likely candidates are colors, fonts, widths, heights, times (such as 1,000 milliseconds), filenames (such as image files), message text (such as alert and confirmation messages), and paths to files (such as the path for a link or an image). For example: var var var var var WRITING MORE EFFICIENT JAVASCRIPT highlightColor = '#33A'; upArrow = 'ua.png'; downArrow='da.png'; imagePath='/images/'; delay=1000; Put these variable definitions at the beginning of your script (or if you’re using jQuery, right inside the .ready() function). TIP It’s particularly useful to put text that you plan on printing to a page into variables. For example, error messages like “Please supply a valid email address,” or confirmation messages like “Thank you for supplying your mailing information” can be variables. When these messages are grouped together as variables at the beginning of a script, it’s easier to edit them later (and to translate the text if you ever need to reach an international audience). Putting Preferences in Objects There’s a slightly more advanced way to store options: using a JavaScript object. As you read on page 136, a JavaScript object literal is a way to store data into a single object using name/value (or key/value) pairs. The example at the top of this page used lots of individual variables to store commonly used values like colors, image paths, icon names, and so on. There’s nothing wrong with this approach, but you can group all of these values into a single object, and then reference individual properties using the dot syntax (page 56). For example, the list of 5 variables in the previous section could be stored in a single object, like this: var siteSettings = { highlightColor: '#33A', upArrow: 'ua.png', downArrow: 'da.png', imagePath: '/images/', delay: 1000 } When you use dot syntax, you don’t use an equals sign to assign a value to a name, so you write upArrow: 'ua.png', not upArrow='ua.png', and you add a comma after each name/value pair except the last one. To then use these settings in your program, use the dot syntax to access all of the object’s individual properties. For example, to retrieve the value of the highlightColor property, you’d write this: Chapter 16: Going Further with JavaScript 577 WRITING MORE EFFICIENT JAVASCRIPT siteSettings.highlightColor There are a couple of benefits to this approach. First, it’s more organized than repeating a big bunch of variables. Instead, you put all of your settings into a single object in one spot in your code. Second, it helps you avoid running into a problem where you use the same name for two different variables. For example, the name “delay” is pretty generic. If you create a delay variable in your programming and you had defined a delay variable at the beginning of your program to store a preference, the first version of delay would be wiped out. However, when you store your site-wide delay setting in an object—siteSettings.delay—it won’t conflict with another delay variable you might add to your program. NOTE You may recall from the discussion of jQuery plug-ins on page 236 that many jQuery plug-ins used object literals to pass information to the plug-in. The jQuery UI widgets (Chapters 10 and 11) use object literals to control how the widgets look and work. Ternary Operator It’s a common programming task to set the value of a variable based on some kind of condition. For example, say you want to set up a variable that contains text with the login status of a user. In your script there’s a variable named login, which contains a Boolean value—true if the user is logged in, or false if she isn’t. Here’s one way to create a new variable for this situation: var status; if (login) { status='Logged in'; } else { status='Not logged in'; } In this case, a basic conditional statement (page 61) sets the value of a variable named status based on whether the user is logged in or not. JavaScript offers a shortcut for this common procedure, called a ternary operator. A ternary operator provides a one-line approach to creating a simple conditional statement. The basic format of the ternary operator is: condition ? A : B Depending upon the result of the condition, either A (if the condition is true) or B (if the condition is false) is returned. The ? precedes the true result, while the : precedes the false result. So, for example, the above code could be rewritten like this: var status = login ? 'Logged in' : 'Not logged in'; What was once six lines of code is now a single line of code. Figure 16-6 diagrams how this code works. 578 JAVASCRIPT & JQUERY: THE MISSING MANUAL WRITING MORE EFFICIENT JAVASCRIPT FIGURE 16-6 The ternary operator lets you write one-line conditional statements. In this example, 1 is the condition. If it’s true, the code immediately following the ? mark is returned (2); if the condition is false, then the code following the : is returned (3). The ternary operator is simply a shortcut—you don’t have to use it, and some programmers find it too dense to easily understand and prefer the easier-to-read if/ else statement. In addition, the best use of the ternary operator is for setting the value of a variable based on a condition. It doesn’t work for every type of conditional statement; for example, you can’t use it for multiple-line statements where many lines of code are executed based on a particular condition. But even if you don’t use ternary operators, recognizing how they work will help you understand other peoples’ programs, as you’ll probably encounter them frequently. The Switch Statement There’s more than one way to skin a conditional statement. While the ternary operator is great for assigning a value to a variable based on the results of a condition, the switch statement is a more compact way of writing a series of if/else statements that depend on the value of a single variable. For example, say you ask visitors to your site to type their favorite color into a form field and then print a different message based on the color they submit. Here’s how you might write part of this code using the typical conditional statement. if (favoriteColor == 'blue') { message = 'Blue is a cool color.'; } else if (favoriteColor == 'red') { message = 'Red is a warm color.'; } else if (favoriteColor == 'green') { message = 'Green is the color of the leaves.'; } else { message = 'What kind of favorite color is that?'; } Notice that there’s an awful lot of favoriteColor == 'some value' in that code. In fact, 'favoriteColor ==' appears three times in just nine lines of code. If all you’re doing is testing the value of a variable repeatedly, then the switch statement provides a more elegant (and easy to read) solution. The basic structure of a switch statement is diagrammed in Figure 16-7. Chapter 16: Going Further with JavaScript 579 WRITING MORE EFFICIENT JAVASCRIPT FIGURE 16-7 The switch statement is a compact way to perform different actions based on the value of a variable. Don’t forget the break statement at the end of each case—the break statement exits the switch statement and prevents mistakenly running the code contained in the cases that follow. The first line of a switch statement begins with the keyword switch, followed by a variable name inside parentheses, followed by an opening brace symbol. Essentially, this code says, “Let’s get the value of this variable and see if it matches one of several other values.” Each test is called a case, and a switch statement has one or more cases. In Figure 16-7, there are three cases, numbered 1–3. The basic structure of a case looks like this: case value1: // do something break; The case keyword indicates the beginning of a case; it’s followed by some value and then a colon. This line is shorthand for the longer if (variable=='value1'). The value can be a number, string, or Boolean (or a variable containing a number, string, or Boolean), so if you want to test whether the variable is equal to 37, for example, then the case would look like this: case 37: //do something break; 580 JAVASCRIPT & JQUERY: THE MISSING MANUAL To test whether the variable is true or not, you’d write this: WRITING MORE EFFICIENT JAVASCRIPT case true: //do something break; After the first line, you add the statements you want to execute if the variable matches the test case value. Finally, you add a break; statement. This step is important—the break; statement exits the switch statement. If you leave out break, the JavaScript interpreter will actually run all the programming in all of the other cases that follow! In other words, once one case is matched, the JavaScript interpreter stops trying to find any other matches and just runs all the remaining code in the switch block. Here’s how the switch statement can help with the if/else if code from page 579: switch (favoriteColor) { case 'blue': message = 'Blue is a cool color.'; break; case 'red': message = 'Red is a warm color.'; break; case 'green': message = 'Green is the color of the leaves.'; break; default: message = 'What kind of favorite color is that?'; } This code is the equivalent to the if/else if code, but is easier to read and doesn’t require repeated conditions (if (favoriteColor === blue), for example). You can also put multiple case statements right after one another (if you want to run the same code for several values). For example: switch (favoriteColor) { case 'navy': case 'blue': case 'indigo': message = 'Blue is a cool color.'; break; case 'red': message = 'Red is a warm color.'; break; case 'green': message = 'Green is the color of the leaves.'; break; default: message = 'What kind of favorite color is that?'; } Chapter 16: Going Further with JavaScript 581 PUTTING IT ALL TOGETHER This is similar to using if (favoriteColor == 'navy' || favoriteColor == 'blue' || favoriteColor == 'indigo') in an if/else statement. Joining Arrays and Splitting Strings A JavaScript array is sort of like a shopping list. It’s a collection of values stored in a single variable. For example, you can create an array to hold the days of the week, like this: var days = ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday', 'Sunday']; Each item in the list is a separate value, and you can access them using the array notation described on page 47. To access the first item in the list, you’d type days[0]. But occasionally you want to get all of the items out of the list into a string, which is useful if you just want to print out everything that’s in the array. You can do that with the .join() method. This array method takes all of the items in the array and turns them into a single string. Each item in the array is separated by either a comma or another separator you specify. For example: var weekdays = days.join(); // Monday,Tuesday,Wednesday… If you don’t provide any arguments to the join() method, it uses a comma to separate each item in the string. However, you can supply any separator you’d like: var weekdays = days.join(':'); // Monday:Tuesday:Wednesday… JavaScript doesn’t insert any spaces between the list items and separators, so if you wanted, say, one item, followed by a comma and a space, you’d need to pass the string ‘, ‘ to the join() method: var weekdays = days.join(', '); // Monday, Tuesday, Wednesday… On the other hand, you can take a string and turn it into an array using the split() method as long as the string has some kind of separator (or delimiter) that indicates where one item ends the next begins. For example, say you have this string: var weekdays = 'Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday'; You could take that string and break it up into an array like this: var dayList = weekdays.split(','); // dayList now is array of 7 items Putting It All Together So far, you’ve seen lots of tasks that JavaScript can accomplish: form validation, image rollovers, photo galleries, user interface improvements like tabbed and accordion panels, and more. But you might be wondering, how do you put them together to work with your site? After all, once you start using JavaScript, you’ll probably want to use it to improve every page of your site. Here are some tips for working with multiple scripts on a site. 582 JAVASCRIPT & JQUERY: THE MISSING MANUAL Using External JavaScript Files As mentioned on page 15, external JavaScript files are an efficient way to share the same JavaScript code among web pages. An external file makes updating your JavaScript easier—there’s just one file to edit if you need to enhance (or fix) your JavaScript code. In addition, when an external JavaScript file is downloaded, it’s stored in the browser’s cache, so it doesn’t need to be downloaded a second time, making web pages feel more responsive and load more quickly. PUTTING IT ALL TOGETHER In the case of a JavaScript library like jQuery, external JavaScript files are a necessity. After all, your web pages would be unnecessarily large and difficult to maintain if you put the actual jQuery JavaScript code into each page. Furthermore, jQuery plug-ins are supplied as external files, so you need to link them to a web page if you want to use them. Linking to an external JavaScript file is as easy as this: <!--<script src="js/jquery-ui.min.js" type="text/javascript"></script>--> Putting your own JavaScript code into external JavaScript files can also help make your code more reusable and your site feel faster—but only if you actually share that code among web pages. For example, with the form validation script you created on page 286, it doesn’t make sense to put the code used to create the validation rules and error messages into an external file because all of those rules and error messages are specific to the form elements on that page, and wouldn’t work on a form that has different form fields. In that case, it’s best to just use the JavaScript to validate the form within the web page itself. However, the validation plug-in file you learned about on page 273 can be used for any form, so it makes sense to have that in a separate file. The same is true for any code that you’ll use in multiple pages. For example, on page 262 you learned how to focus the first field of a form using JavaScript—that’s something you might want to do for every form. Likewise, the box on page 266 presents the JavaScript necessary to prevent a visitor from hitting the submit button multiple times (and thus submitting the form data more than once), which is also useful for any form page. So, you might want to combine these two scripts into a single external file named something like forms.js. The JavaScript code would look something like this: 1 2 3 4 5 6 7 8 9 10 $(document).ready(function() { // focus first text field $(":text")[0].focus(); 11 }); //end ready // disable submit button on submit $('form').submit(function() { var subButton = $(this).find(':submit'); subButton.attr('disabled',true); subButton.val('...sending information...'); }); Chapter 16: Going Further with JavaScript 583 PUTTING IT ALL TOGETHER NOTE As mentioned on page 160, any scripts you place in the of a web page and which use jQuery require a $document.ready() function. jQuery can handle multiple $(document).ready() functions without a problem. For example, you can have several external JavaScript files that do various things to the page, and each file can have a $(document).ready() function, and you can include a $(document). ready() function within <!--<script type="text/javascript"> that appears only on that page. That’s perfectly fine with jQuery. You can avoid the $(document).ready() function altogether by placing your <script> tags at the bottom of the web page, just before the closing </body> tag. Using the same script across multiple pages requires a little planning. For example, line 3 places the cursor into the first text field on a web page. In most cases, that makes sense—you want the focus to be on the first field so a visitor can start filling out the form. However, if the page has more than one form, this code might not work as you want it to. For example, if you have a search box at the top of the page and a separate form for submitting a product order, the code in line 3 will put the focus on the search box and not the first text field in the order form. In a case like that, you need to think through the problem and come up with a way of making sure the proper text field has the focus when the page loads. Here are two possible solutions: • Add a class name to the field you want the focus on when the page loads. For example, say you add the class name focus to the text field, like this: <input type="text" class="focus" name="firstName"> You could then you use this JavaScript to make sure that field is focused: $('.focus').focus(); To use this code, you just need to make sure that you add the focus class to a text field on each form page, and make sure you link the external JavaScript file containing this code to each of those form pages. • You can get the same effect by adding a class name to the <form> tag itself, using this JavaScript: $('.focus :text')[0].focus(); This code automatically focuses the first text field of a form with the class focus. The benefit of this approach is that the first text field always gets the focus, so if you reorganize your form (add a few more text fields to the beginning, for example), you know that the first text field will get focus and not some other field (with the focus class) further down the page. Once you start using JavaScript, you might end up using several scripts on all (or nearly all) of your web pages. For example, you might have some rollover images (page 209), and use JavaScript to make sure links outside your site open in a new window (page 231). In this situation, it’s useful to create an external JavaScript file with all of the scripts you share among your site—you could call the file something like site_scripts.js or simply site.js. 584 JAVASCRIPT & JQUERY: THE MISSING MANUAL NOTE jQuery has a built-in mechanism to protect you from producing unwanted JavaScript errors. JavaScript usually spits out an error if you try to perform an action on something that doesn’t exist—for example, trying to select a text field on a page that doesn’t have a text field. Fortunately, jQuery ignores these kinds of errors. PUTTING IT ALL TOGETHER Creating Fast-Loading JavaScript Once you starting using external JavaScript files for your scripts, your visitors should start to feel like your site is faster. Thanks to a browser’s cache, once your external JavaScript files download for one page of your site, they don’t have to be downloaded a second time for a different page. However, there’s still another way to make your site download more quickly: compressing your external JavaScript files. NOTE Files sent securely via SSL (secure socket layer) aren’t usually cached. So if people access the pages of your site using https:// as the protocol (for example, https://www.oreilly.com), then any files they download, including external JavaScript files, will most like be downloaded every time they’re needed. (You can change settings on the web server to allow caching of securely sent files.) To make a script more understandable, programmers usually insert empty spaces, carriage returns, and comments to explain what the script does. These are all important additions for the programmer, but not necessary for the web browser, which can happily understand JavaScript without carriage returns, tabs, extraneous spaces, or comments. Using a compression program, you can minimize the space your JavaScript takes up. The version of jQuery recommended in this book, for example, is minified, and is nearly half the file size of the uncompressed version. There are several programs aimed at making JavaScript more petite. Douglas Crockford’s JSMin (http://crockford.com/javascript/jsmin.html) is one example, and Dean Edward’s Packer (http://dean.edwards.name/packer) is another. However, it’s a good idea to use the same compressor Yahoo! (and jQuery) use, because it achieves great file size savings without changing your code (some compressors actually rewrite your code and in some cases can break your scripts!). Yahoo!’s JavaScript compressor, YUI Compressor, lives at http://developer.yahoo. com/yui/compressor. Fortunately, there’s an easy to use online tool that lets you use the YUI compressor without installing it on your own computer: 1. Launch a web browser and visit http://www.refresh-sf.com/yui/. This is the site for the Online YUI Compressor. 2. Click the File(s) link. Alternatively, you can just copy the JavaScript code from your text editor and paste it into the large text box at the site’s homepage; you can then skip to step 4. 3. Click the Choose File button and locate the external JavaScript file on your computer. The file must contain only JavaScript. For example, you can’t select a HTML file that also has JavaScript programming in it. Chapter 16: Going Further with JavaScript 585 PUTTING IT ALL TOGETHER 4. Select the “Redirect to gzipped output” box (just above the Compress button). This option lets you download the minimized code in a new, zipped file. This will be your new, compressed, external JavaScript file, which you can save to your site. 5. Click the Compress button. The website processes your code and downloads the compressed file to your computer. You can then rename this file (because it’s always saved as min.js), and put it into your site for use. The Online YUI Compressor site provides a nice report after you compress a file, listing the original file size, the new, compressed file size, and a percentage that represents how much smaller the new file is. WARNING Make sure you keep the original JavaScript file on hand after using the Online YUI Compressor because the new, compressed version is unreadable and you’ll never be able to edit it if you wish to make changes to your original code. 586 JAVASCRIPT & JQUERY: THE MISSING MANUAL CHAPTER Troubleshooting and Debugging 17 E verybody makes mistakes, but in JavaScript, mistakes can keep your programs from running correctly—or at all. When you first start out with JavaScript, you’ll probably make a lot of mistakes. Trying to figure out why a script isn’t behaving the way it should can be frustrating, but it’s all a part of programming. Fortunately, with experience and practice, you’ll be able to figure out why an error has occurred and how to fix it. This chapter describes some of the most common programming mistakes, and, more importantly, teaches you how to diagnose problems in your scripts—debug them, as programmers say. In addition, the tutorial will take you step by step through debugging a problematic script. Top JavaScript Programming Mistakes There are countless ways a program can go wrong, from simple typos to more subtle errors that only pop up every now and again. However, there are a handful of mistakes that routinely plague beginning (and even advanced) JavaScript programmers. Go over the list in this section, and keep it in the back of your mind when programming. You’ll probably find that knowing these common mistakes makes it a lot easier to identify and fix problems in your own programs. Non-Closed Pairs As you’ve noticed, JavaScript is filled with endless parentheses, braces, semicolons, quotation marks, and other punctuation. Due to the finicky nature of computers, leaving out a single punctuation mark can stop a program dead in its tracks. One 587 TOP JAVASCRIPT PROGRAMMING MISTAKES of the most common mistakes is simply forgetting to include a closing punctuation mark. For example, alert('hello' ; will produce an error because the closing parenthesis is missing: alert('hello');. Leaving off a closing parenthesis will cause a syntax error (see page 21). This kind of “grammatical” error prevents scripts from running at all. When you give your script a test run, the browser lets you know if you’ve made a syntax error, but, confusingly, they all describe the problem differently. In the Firefox error console (page 22), you get an error message “SyntaxError: missing ) after argument list”; Internet Explorer’s console (page 21) reports this error as “Expected ‘)’”; Chrome’s error console provides a misleading “SyntaxError: Unexpected token ;” message; and Safari’s error console (page 23) gives you the helpful message “SyntaxError: Expected token ‘)’.” Firefox tends to provide the most understandable error messages, so it’s a good browser to start with when trying to figure out why a script isn’t working (Figure 17-1). FIGURE 17-1 Firefox’s Error Console lists all JavaScript errors that the browser encounters. You can display the console by choosing Web Developer→Error Console (Ctrl+Shift+K) on Windows, or Tools→Web Developer→Error Console (c-Option-K) on Macs. The console lists the errors it has encountered on all pages, so you’ll want to frequently erase the list by clicking the Clear button (circled). The syntax error in alert('hello' ; is pretty easy to spot. When you’ve got a nest of parentheses, though, it’s very easy to leave off a closing parenthesis and difficult to spot that error at a glance. For example: if ((x>0) && (y<10) { // do something } In this example, the final closing parenthesis for the conditional statement is missing—the one that goes directly after (y<10). The first line should really be: if ((x>0) and (y<10)) {. Again, Firefox provides the clearest description of the problem: “missing ) after condition.” Table 17-1 provides a list of Firefox’s error console syntax error messages. You’ll encounter a syntax error when you forget to include the second quote mark as well. For example, alert('hello); produces an error because the final single 588 JAVASCRIPT & JQUERY: THE MISSING MANUAL quote is missing: alert('hello');. In Firefox, if you forget to include one of the quote marks, you’ll get an “unterminated string literal” error, while Internet Explorer reports an “unterminated string constant”; and both Chrome and Safari calls this a “SyntaxError: Unexpected token ILLEGAL”. TOP JAVASCRIPT PROGRAMMING MISTAKES Braces also come in pairs, and you’ll use them in conditional statements (page 61), in loops (page 78), when creating functions (page 85), and with JSON (page 477): if (score==0) { alert('game over'); In this example, the closing } is missing, and the script will produce a syntax error. One approach to overcome the problem of missing closing punctuation marks is to always add them before adding other programming. For example, say you want to end up with the following code: if ((name=='bob') && (score==0)) { alert('You lose, but at least you have a great name'); } NOTE Many good text editors include syntax highlighting that highlights matching pairs of parentheses, brackets, and braces. Some editors even identify missing punctuation, so you can quickly fix errors. Start by typing the outside elements first, creating a basic skeleton for the condition like this: if () { } At this point, there’s not much code, so it’s easy to see if you’ve mistakenly left out any punctuation. Next, add more code, bit by bit, until the program is in place. The same is true when creating a complex JavaScript object literal like the one used to set the options for the Validation plug-in described on page 273, or like a JSON object described on page 477. Start with the basic structure: var options = { }; Then add more structure: var options = { rules : { }, messages : { } }; Chapter 17: Troubleshooting and Debugging 589 TOP JAVASCRIPT PROGRAMMING MISTAKES Then finish the object: var options = { rules : { name : 'required', email: 'email' }, messages : { name : 'Please type your name', email: 'Please type your e-mail address.' } }; This approach lets you check your work through various steps and makes it a lot easier to identify any mistakes in punctuation. Firefox’s Error Console (discussed on page 22) provides the clearest description of syntax error messages. When a script isn’t working, preview it in Firefox and review the Error Console. Table 17-1 shows a few of the most common error messages and what they mean. TABLE 17-1 Firefox’s Error Console’s most common error messages and what they mean. FIREFOX ERROR MESSAGE EXPLANATION Unterminated string literal Missing opening or closing quote mark: var name = Jane'; Error also appears with mismatched quote marks: var name = 'Jane"; Missing ) after argument list Missing closing parenthesis when calling a function or method: alert('hello" ; Missing ) after condition Missing closing parenthesis within a conditional statement: if (x==0 Missing ( before condition Missing opening parenthesis within a conditional statement: if x==0) Missing } in compound statement Missing closing brace as part of conditional loop: Missing } after property list Missing closing brace for JavaScript object: if (score == 0) { alert('game over'); // missing } on this line var x = { fName: 'bob', lName: 'smith' // missing } on this line Syntax Error 590 General problem that prevents JavaScript interpreter from reading the script. JAVASCRIPT & JQUERY: THE MISSING MANUAL FIREFOX ERROR MESSAGE EXPLANATION Missing ; before statement Lets you know when you’ve run two statements together on a single line, without separating them with a semicolon. You’ll also see this when you incorrectly nest quotation marks: TOP JAVASCRIPT PROGRAMMING MISTAKES var message='There's an error here.'; Missing variable name Appears if you attempt to use a JavaScript reserved word (page 31) for a variable name: var if="Syntax error."; Quotation Marks Quote marks often trip up beginning programmers. Quote marks are used to create strings of letters and other characters (called “string literals”) to use as messages on the page, or as variables in a program. JavaScript, like other programming languages, lets you use either double or single quote marks to create a string literal. So, var name="Jane"; is the same as: var name='Jane'; As you read in the previous section, you must include both the opening and closing quote marks, or you’ll end up with an “Unterminated string literal” error in Firefox (and all other browsers will give up on your script as well). In addition, as you read on page 28, you must use the same type of quote mark for each pair—in other words, both single quotes or both double quotes. So var name='Jane" will also generate an error. Another common problem can arise with the use of quotations within a string. For example, it’s very easy to make the following mistake: var message='There's an error in here.'; Notice the single quote in There's. The JavaScript interpreter treats that quote mark as a closing quote, so it actually sees this: var message='There', and the rest of the line is seen as an error. In the Firefox error console, you’ll get the message “Missing ; before statement,” because Firefox thinks that second quote is the end of a simple JavaScript statement and what follows is a second statement. You can get around this error in two ways. First, you can mix and match double and single quotes. In other words, you can put double quotes around a string with single quotes, or you can put single quotes around a string containing double quotes. For example, you can fix the above error this way: var message="There's no error in here."; Or, if the string contains double quotes: var message='He said, "There is no problem here."'; Chapter 17: Troubleshooting and Debugging 591 TOP JAVASCRIPT PROGRAMMING MISTAKES Another approach is to escape quote marks within a string literal. Escaping quote marks is discussed in greater detail in the box on page 28, but here’s a recap. To escape a character, precede it with a forward slash, like this: var message='There\'s no error here.'; The JavaScript interpreter treats \' as a single quote character and not as the symbol used to begin and end strings. UP TO SPEED Types of Errors There are three basic categories of errors that you’ll encounter as you program JavaScript. Some of these errors are immediately obvious, while others don’t always rear their ugly heads until the script is up and running: • Syntax Errors. A syntax error is essentially a grammatical mistake that makes a web browser’s JavaScript interpreter throw up its hands and say, “I give up.” Any of the errors involving a missing closing parenthesis, brace, or quote mark generates a syntax error. The web browser encounters syntax errors immediately, as it reads the script, so the script never has a chance to run. An error message for a syntax error always appears in a web browser’s error console. • Runtime errors. After a browser reads a script’s code successfully and the JavaScript interpreter interprets it, it can still encounter errors. Even if the program’s syntax is fine, other problems might pop up as the program runs—called runtime errors. For example, say you define a variable named message at the beginning of a script; later in the script, you add a click function to an image so an alert box appears when the image is clicked. Say the alert code for this example looks like this: alert(MESSAGE);. There’s nothing wrong with this statement’s syntax, but it references the variable MESSAGE instead of lowercase message. As mentioned on page 30, JavaScript is case-sensitive, so MESSAGE and message refer to two different variables. When a visitor clicks the image, the JavaScript interpreter looks for the variable MESSAGE (which doesn’t exist) and generates a runtime error. Another common runtime error occurs when you try to access an element on a page that either doesn’t exist 592 or the browser hasn’t yet read into its memory. See the discussion of jQuery’s $(document).ready() function on page 160 for more detail on this problem. • Logic errors. Sometimes even though a script seems to run, it doesn’t produce the results you’re after. For example, you may have an if/else statement (page 61) that performs step A if a condition is true or step B if it’s false. Unfortunately, the program never seems to get to step B, even if you’re sure the condition is false. This kind of error happens when you use the equality operator incorrectly (page 33). From the JavaScript interpreter’s perspective, everything is technically correct, but you’ve made a mistake in the logic of your programming that prevents the script from working as planned. Another example of a logic error is an infinite loop, which is a chunk of code that runs forever, usually causing your programming to hang up and sometimes even crashing the web browser. Here’s an example of an infinite loop: for (var i=1; i>0; i += 1) { // this will run forever } In a nutshell, this loop will run as long as the test condition (i>0) is true. Since i starts out with a value of 1 (var i=1), and each time it goes through the loop i is increased by 1 (i += 1), the value of i will always be greater than 0. In other words, the loop never stops. (Turn to page 78 if you need a refresher on for loops.) Logic errors are among the most difficult to uncover. However, with the debugging techniques described on page 597, you should be able to uncover many common problems. JAVASCRIPT & JQUERY: THE MISSING MANUAL Using Reserved Words As listed on page 31, the JavaScript language has many words that are reserved for its private use. These words include words used in the language’s syntax like if, do, for, and while, as well as words used as part of the browser object, like alert, location, window, and document. These words are not available to use as variable names. TOP JAVASCRIPT PROGRAMMING MISTAKES For example, the following code generates a syntax error: var if = "This won't work."; Since if is used to create conditional statements—as in if (x==0)—you can’t use it as a variable name. Some browsers, however, won’t generate an error if you use words that are part of the Browser Object Model for your variable names. For example, document refers to the HTML document. For example, look at the following code: var document='Something strange is happening here.'; alert(document); Browsers don’t generate an error, but instead pop up an alert with the text “[object HTMLDocument],” which refers to the HTML document itself. In other words, those browsers won’t let you overwrite the document object with a string. Single Equals in Conditional Statements Conditional statements (page 61) provide a way for a program to react in different ways depending upon a value of a variable, the status of an element on a page, or some other condition in the script. For example, a conditional statement can display a picture if it’s hidden or else hide it if it’s visible. Conditional statements only make sense, however, if a particular condition can be true or false. Unfortunately, it’s easy to create a conditional statement that’s always true: if (score=100) { alert('You win!'); } This code is supposed to check the value stored in the variable score—if the value is 100, then an alert box with the message “You win!” should appear. However, in this case, the alert message will always display, no matter what value is stored in score prior to the conditional statement. That’s because a single equals sign is an assignment operator, so score=100 stores the value 100 in score. The JavaScript interpreter treats an assignment operation as true, so not only does the code above always pop up the alert box, it also rewrites the value of score to 100. To avoid this error, make sure use the comparison equality operator when testing whether two values are the same: if (score===100) { alert('You win!'); } Chapter 17: Troubleshooting and Debugging 593 TOP JAVASCRIPT PROGRAMMING MISTAKES Case-Sensitivity Remember that JavaScript is case-sensitive, meaning that the JavaScript interpreter tracks not only the letters in the names of variables, functions, methods, and keywords, but also whether the letters are uppercase or lowercase. So alert('hi') is not the same as ALERT('hi') to the JavaScript interpreter. The first, alert('hi'), calls the browser’s built-in alert() command, while the second ALERT('hi') attempts to call a user-defined function named ALERT(). You can run into this problem if you use the long-winded DOM selection methods— getElementsByTagName() or getElementById()—because they use both upper and lowercase letters (another good reason to stick with jQuery). Likewise, if you include both upper and lowercase letters in variable and function names, you may run into this problem from time to time. If you see an “x is not defined” error message (where x is the name of your variable, function, or method), mismatched case may be the problem. Incorrect Path to External JavaScript File Another common mistake is incorrectly linking to an external JavaScript file. Page 15 discusses how to attach an external JavaScript file to a web page. Basically, you use the <script> tag’s src property to point to the file. So in the HTML page, you’d add the <script> tag to the <head> of the document like this: <script src="site_js.js"></script>--> The src property works like a link’s href property—it defines the path to the JavaScript file. As mentioned in the box on “URL Types”, there are three ways you can point to a file: absolute links (http://www.site.com/site_js.js), root-relative links ( /site_js.js), and document-relative links (site_js.js). A document-relative path describes how a web browser gets from the current page (the web page) to a particular file. Document-relative links are commonly used because they let you test your web page and JavaScript file right on your own computer. If you use root-relative links, you’ll need to set up a web server on your own computer to test your pages (or move them up to your web server to test them). You can read more about how link paths work on page 11. But, in a nutshell, if you find that a script doesn’t work and you’re using external JavaScript files, double check to make sure you’ve specified the correct path to the JavaScript file. TIP If you’re using the jQuery library and you get the error “$ is not defined” in the error console, you probably haven’t correctly linked to the jquery.js file (see page 107 for more). Incorrect Paths Within External JavaScript Files Another problem related to file paths occurs when using document-relative paths in an external JavaScript file. For example, you might create a script that displays images on a page (like a slideshow or just a “random image of the day” script). If the script 594 JAVASCRIPT & JQUERY: THE MISSING MANUAL uses document-relative links to point to the images, you can run into trouble if you put that script into an external JavaScript file. Here’s why: When an external JavaScript file is loaded into a web page, its frame of reference for document-relative paths is the location of the web page itself. So, any document-relative paths you include in the JavaScript file must be relative to the web page and not the JavaScript file. TOP JAVASCRIPT PROGRAMMING MISTAKES Here’s a simple example to illustrate this problem. Figure 17-2 represents the structure of a very simple website. There are two web pages (page.html and about.html), four folders (libs, images, pages, and about), an external JavaScript file (site_js.js inside the libs folder) and an image (photo.jpg in the images folder.) Say the site_js.js file references the photo.jpg file—perhaps to preload the image (page 212), or display it dynamically on a web page. FIGURE 17-2 Document-relative paths depend on both the location of the file that the path starts at as well as the location of the destination file. For example, the document-relative path from the site_js.js file to the photo.jpg file (#1) is ../images/photo.jpg; the path to the same file from the page.html file (#2) is images/photo. jpg; and the path from the about.html file (#3) is ../../images/ photo.jpg. From the site_js.js file’s perspective, a document-relative path to the photo.jpg file is ../images/photo.jpg (#1 in Figure 14-2). The path tells the browser to exit the libs folder (../), enter the images folder (images/), and select the photo.jpg file. However, from the perspective of the page.html file, the path to the photo.jpg file (#2 in Figure 14-2) is just images/photo.jpg. In other words, the path to the same photo differs between the two files. If you want to use the site_js.js script within the page.html file, then, you have to use path #2 in the site_js.js file to reference the location of photo.jpg (that is, specify a path relative to page.html). By the same token, you can’t use the site_js.js file in a web page located in another directory in your site because the relative path would be different for that file (#3 in Figure 17-2). Chapter 17: Troubleshooting and Debugging 595 TOP JAVASCRIPT PROGRAMMING MISTAKES There are a few ways around this problem. First, well, you may never encounter it—you may not find yourself listing paths to other files in your JavaScript files. But if you do, you can use site root-relative paths (page 11), which are the same from any page in the site. Alternatively, you can define the path to the files within each web page. For example, you can link to the external JavaScript file, and then, in each web page, define variables to hold document-relative paths from the current web page to the correct file. Finally, you could use an approach like the one used in the photo gallery on page 220. The paths come from the web page and are embedded within links on the page—the JavaScript simply pulls the paths out of the HTML. As long as those paths work in the HTML, they’ll work in a script as well. Disappearing Variables and Functions You may occasionally encounter an “x is not defined” error, where x is either the name of a variable or a function you’re trying to call. The problem may just be that you mistyped the name of the variable or function, or used the wrong case. However, if you look through your code and can clearly see that the variable or function is defined in your script, then you may be running into a “scope” problem. Variable and function scope is discussed in greater detail on page 92, but in a nutshell, if a variable is defined inside of a function, it’s only available to that function (or to other functions defined inside that function). Here’s a simple example: 1 2 3 4 5 function sayName(name) { var message = 'Your name is ' + name; } sayName(); alert(message); // error: message is not defined The variable message is defined within the function sayName(), so it only exists for that function. Outside the function, message doesn’t exist, so an error is generated when the script tries to access the variable outside the function (line 5). You may also encounter this error when using jQuery. On page 160, you read about the importance of the $(document).ready() function for jQuery. Anything inside that function only runs once the page’s HTML is loaded. You’ll run into problems if you define variables or functions within the $(document).ready() function and try to access them outside of it, like this: $(document).ready(function() { var msg = 'hello'; }); alert(msg); // error: msg is not defined So, when using jQuery, be sure to put all of your programming inside the $(document).ready() function: $(document).ready(function() { var msg = 'hello'; 596 JAVASCRIPT & JQUERY: THE MISSING MANUAL DEBUGGING WITH THE CONSOLE alert(msg); // msg is available }); UP TO SPEED Programming Tips to Reduce Errors The best way to deal with errors and bugs in your programs is to try to stop them as early as possible. It can be really difficult to track down the cause of errors in a program if you wait until you’ve written a 300-line script before testing it in a web browser. The two most important tips to avoiding errors are: counting the numbers of characters in the field, and then displaying that number on the page. You can try to write this script in one go, but you can also write the code for step 1 (responding to a keydown event) and then test it immediately in a web browser (using the alert() command or console.log() function, described on the next page, can help you see the results of a keydown event). If it works, you can then move on to step 2, test it, and so on. • Build a script in small chunks. As you’ve probably figured out by now, JavaScript programs can be difficult to read, what with all of the }, ), ', ifs, elses, functions, and so on. Don’t try to write an entire script in one go (unless you’re really good, the script is short, or you’re feeling lucky). There are so many ways to make a mistake while programming, and you’re better off writing a script in bits. For example, say you want to display the number of letters typed into a form field, right next to the field. In other words, as a visitor types into the field, a running total of the number of letters typed appears next to the box. (Some sites do this when they limit the amount a visitor can type into a field—say, 300 letters.) This task is pretty easy JavaScript, but it involves several steps: responding to the keydown event (when a visitor types a letter in the field), reading the value of that field, As you gain more experience, you won’t need to test such small steps. You can write a few steps at once, and then test that chunk. • Test frequently. You should also test your script in a web browser frequently. At a minimum, test after you complete each chunk of the program, as suggested in the previous point. In addition, you should test the script in different browsers—preferably Internet Explorer 8, and above; the latest versions of Chrome, Firefox, and Safari; and whatever other browsers you think your site’s visitors might be using. Debugging with the Console If you haven’t been using your web browser’s JavaScript console, you’ve been missing out on one of the best tools a web designer could have. All major web browser have a built-in JavaScript console that can help you improve your HTML, CSS, and JavaScript. Opening the Console To use the console, open a web page in your browser. Then use one of these methods: • Google Chrome. Click the Chrome settings button (circled in Figure 17-3) and choose Tools→JavaScript Console. Or use the keyboard shortcut, Ctrl-Shift-J (Windows) or c-Option-J (Mac). • Internet Explorer. Press the F12 key to open the Developer Tools panel. Click the Console tab to display the JavaScript console. Chapter 17: Troubleshooting and Debugging 597 DEBUGGING WITH THE CONSOLE • Firefox. To open the console, on Windows, click the Firefox tab in the top left of the browser window and choose Web Developer→Web Console. On a Mac, select Tools→Web Developer→Web Console. Or use the keyboard shortcuts Ctrl+Shift+I (Windows) and c-Option-K (Mac). • Safari. Safari’s error console is available from the Develop menu: Develop→Show Error Console (c-Option-C). However, the Develop menu isn’t normally turned on when Safari is installed, so you need to turn it on in Preferences. Choose Safari→Preferences. Once the Preferences window opens, click the Advanced button. Turn on the “Show Develop menu in menu bar” checkbox and then close the Preferences window. When you restart Safari, the Develop menu will appear between the Bookmarks and Window menus in the menu bar at the top of the screen on a Mac; and on Windows, you’ll find it under the page icon in the top right of the browser. Select Develop→Show Error Console to open the console. Viewing Errors with the Console The console lists any errors that occur in your JavaScript. First, it identifies the first syntax error on the page. As you read on page 18, syntax errors are like grammatical mistakes. When the browser’s JavaScript interpreter encounters a syntax error, it just throws up its hands and quits. It lets you know about that error, but, if there are more syntax errors on the page, you won’t know about them until you fix the first one. Once the syntax errors are fixed, you may begin encountering runtime errors (page 582)—errors that the browser tells you about as the program is running. For example, trying to access a variable that was never created causes an error. The console should be your first line of defense when you need to track down errors in your code (Figure 17-3). Using console.log() to Track Script Progress Once a script begins to run, it’s kind of like a black box. You don’t really know what’s going on inside the script and only see the end result, like a message on the page, a pop-up window, and so on. You can’t always tell exactly whether a loop is working correctly or see the value of a particular variable at any point in time. JavaScript programmers have long used the alert() method (page 12) to pop up a window with the current value of a variable. For example, if you want to know what value is being stored in the variable elementName as a loop is running, you can insert an alert command inside the loop: alert(elementName);. That’s one way to look into the “black box” of the script. However, the alert box is pretty intrusive: You have to click it to close it, and in a loop that might run 20 times, that’s a lot of pop-up alerts to close. The JavaScript console provides a better way to look into your program. It not only lists errors (see previous section), but can also be used to output messages from the program. The console.log() function works similar to the document.write() 598 JAVASCRIPT & JQUERY: THE MISSING MANUAL function (page 15), but instead of printing a message to the web page, console. log() prints a message to the console. DEBUGGING WITH THE CONSOLE FIGURE 17-3 The JavaScript console lists any JavaScript errors the browser has encountered on the current page. In Chrome, pictured here, you can open the console by clicking the Chrome Setting button (circled) and choosing Tools→JavaScript Console. To see the exact line of code on which the error was encountered, click the code snippet under the error. The browser then switches from the console tab to the Sources tab and highlights the line where the error happened. TIP All current browsers support the console.log() method. So you can use it in Chrome, Safari, Internet Explorer, Firefox, and Opera’s consoles. For example, you could print the current value of the variable elementName to the console using this code: console.log(elementName); Unlike the alert() method, this method won’t interrupt your program’s flow—you’ll just see the message in the console. To make the log message more understandable, you can include a string with additional text. For example, if you have a variable named name and you want to determine what value is stored in name at some point in your program, you can use the console.log() function like this: console.log(name); But if you wanted to precede the name with a message, you can write this: console.log('User name:', name); Chapter 17: Troubleshooting and Debugging 599 DEBUGGING WITH THE CONSOLE This line would print a single line to the console with “User name:” followed by the value stored in the name variable. But what if you wanted to place variable values somewhere within the string? For example, say you’re tracking a user’s name and score. You’d like to write a clear message to the console like “Jill has a score of 50 points.” In other words, you want to place the name at the beginning of the string and the score in the middle. To do this, you’d pass the console.log() function a string containing %s as a placeholder for each variable you wanted to insert in the string, followed by a comma, a variable name, another comma, and another variable name. For example: console.log('%s has a score of %s points', name, score); The special %s is way of saying “substitute the variable value with me.” In other words, the first %s gets replaced with the value of name, and the second %s gets replaces with the value of score. The log() function is merely a way to give you some information about the functioning of your script as you develop it. Once your program is finished and working, you should remove all of the console.log() code from your script. Tutorial: Using the Console In this tutorial, you’ll learn how to use the console.log() function to see what’s going on inside your code. You’ll create a script that displays the number of characters typed into a text box on a form. NOTE See the note on page 12 for information on how to download the tutorial files. This tutorial is shown in the Google Chrome browser. You can follow along in your favorite browser, but it may behave a bit differently from Chrome. 1. Open the file console.html in a text editor. This script uses the jQuery library. The external jQuery file is already attached to the page, and the opening and closing <!--<script type="text/javascript"> tags are in place. You’ll start by adding jQuery’s $(document).ready() function. 2. Between the <script> tags near the top of the page, add the code in bold below: <script> $(document).ready(function() { }); // end ready </script>--> You learned about the basic $(document).ready() function on page 160, which makes the browser load all of the page’s code before starting to run 600 JAVASCRIPT & JQUERY: THE MISSING MANUAL any JavaScript. You’ll first use the console.log() function to simply print out a message that the script has executed the .ready() function. DEBUGGING WITH THE CONSOLE 3. Add the bolded code below to the script: <!--<script type="text/javascript"> $(document).ready(function() { console.log('READY'); }); // end ready </script>--> The console.log() function runs wherever you place it in the script. In other words, after this page’s HTML is loaded (that’s what the ready() function waits for), the browser writes “READY” to the console. Adding the ready() function is a pretty common and basic move, so you may not always add a console. log() function here, but for this tutorial, you’ll add one to see how the log() function works. In fact, you’ll be adding a lot of log messages to this page to get the hang of the console.log() function. 4. Save the file, and open it in Chrome. If the console isn’t already open, type Ctrl+Shift+J (Windows) or c-Option-J (Macs). The word READY should appear in the console (circled in Figure 17-4). The script you’re creating will display the number of characters typed into a form’s text field each time your visitor types a character. To accomplish this, you’ll add a keyup event (page 152) to that text box. During each step of this script, you’ll also add a console.log() function, to clue you in to what’s happening. 5. After the line of code you added in step 3, add the following: $('#comments').keyup(function() { console.log('Event: keyup'); }); // end keyup Make sure you place this code inside the $(document).ready() function. The <textarea> tag on this page has an ID of comments, so you can select that element using jQuery ($('#comments')) and add a function to the keyup event (see page 152 if you need a refresher on adding events). In this case, the console.log() function is just printing a status message to the JavaScript console telling you each time the keyup event is triggered. This function is an easy way to see whether an event function is actually running or something’s preventing the event from happening. Save the page; reload it in the browser and type a few characters into the text box. Make sure the JavaScript console is open, and you should see “Event: keyup” in the console. A number will also appear near this message (on the left of the log message in some cases and to the right in others). The number indicates how many times this particular console.log() message has been printed. Chapter 17: Troubleshooting and Debugging 601 DEBUGGING WITH THE CONSOLE Now that the keyup event is working, you might want to retrieve the contents of the text box and store it in a variable. To be sure you’re getting the information you’re after, you’ll print the contents of the variable to the console. FIGURE 17-4 You can use the browser’s console to write secret messages. But, it’s more useful for displaying notes as you debug a program. In this case, a simple message— “Ready”—indicates that the program has successfully run jQuery's $(document). ready() function. 6. Add lines 3 and 4 to the code you typed in step 5: 1 2 3 4 5 $('#comments').keyup(function() { console.log('Event: keyup'); var text = $(this).val(); console.log('Contents of comments:',text); }); // end keyup Line 3 retrieves the value from the text box and stores it inside a variable named text (see page 255 for more information on extracting the value from a form field). Line 4 writes a message to the console. In this case, it combines a string 'Contents of comments:' and the value currently stored in the text box. When a program isn’t working correctly, a very common diagnostic step is to print out the values of variables in the script to make sure the variable contains the information you’re expecting it to have. 602 JAVASCRIPT & JQUERY: THE MISSING MANUAL 7. Save the file, reload it in your browser, and type some text into the comments box. DEBUGGING WITH THE CONSOLE The console should now display the contents in the comments box each time you type a letter into the field. By now you should be getting the hang of the console, so you’ll add one more message, and then finish this script. 8. Edit the keyup event function by adding two more lines (5 and 6): 1 2 3 4 5 6 7 $('#comments').keyup(function() { console.log('Event: keyup'); var text = $(this).val(); console.log('Contents of comments:',text); var chars = text.length; console.log('Number of characters:',chars); }); // end keyup Line 5 counts the number of characters stored inside the text variable (see page 541 for more on the length property) and stores it inside the variable chars. Just to make sure the script is correctly calculating the number of characters, use the log() function (line 6) to print a message to the console. There’s just one last thing to do: Finish the script so it prints the number of characters typed so your visitor can see it. 9. Add one last line to the end of the keyup event function (line 10), so the completed script for the page looks like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 <script> $(document).ready(function() { console.log('READY'); $('#comments').keyup(function() { console.log('Event: keyup'); var text = $(this).val(); console.log('Contents of comments: %s',text); var chars = text.length; console.log('Number of characters: %s',chars); $('#count').text(chars + " characters"); }); // end keyup }); // end ready </script> 10. Save the file, and preview it in your browser. The console should now look something like Figure 17-5. You’ll find a finished version of this tutorial—complete_console.html—in the chapter17 folder in this chapter’s tutorial files. NOTE Once you have functioning code, you should remove all console.log() code from your script. The log() function will generate errors in some browsers. Chapter 17: Troubleshooting and Debugging 603 DEBUGGING WITH THE CONSOLE More Powerful Debugging The JavaScript console is a great way to print out messages so you can see what’s going on when a program runs. But sometimes a program zips by so quickly it’s hard to see what’s going on during each step. You need a way to slow things down. Fortunately, browsers contain powerful JavaScript debuggers, which let you step through a script line by line so you can see what’s happening at each step of the program. NOTE The Chrome is shown in this section, but you’ll find similar JavaScript debuggers in Firefox, Opera, Safari, and Internet Explorer. Debugging is the process of fixing an incorrectly functioning program—getting the bugs out. To really understand how a program is functioning (or malfunctioning), you need to see how the program works, step by step. To use the debugger, you mark certain lines of code as breakpoints. A breakpoint is a spot where the JavaScript interpreter stops running and waits. You can then use controls inside the debugger that let you run a program one line at a time. In this way, you can see exactly what’s happening at any particular line. Here’s the basic process. 1. Open a web page in a web browser. Remember, these instructions are shown in the Chrome web browser and its debugger. In other browsers’ debuggers, the exact steps and panels will differ. 2. Open the JavaScript console. Follow the instructions on page 18 for opening your browser’s developer tools. In Chrome, you can open the JavaScript console with the keyboard shortcuts Ctrl+Shift+J (Windows) or c-Option-J (Mac). 3. Click the Sources tab and, from the files list, select the file containing the JavaScript you wish to debug (Figure 17-6). In Chrome, the Sources tab lists the source code for the file you wish to debug. In the case of a script that’s written into a web page, you see the source code for the entire web page (including the HTML). For an external JavaScript file, you see just the JavaScript in that file. 4. Select the file with the script you wish to debug from the list of files on the left of the debugger (Figure 17-6). It’s common to have scripts placed in different files: the web page itself, or one or more external JavaScript files. If your page uses scripts from multiple files, you need to select the file containing the script you wish to debug. 5. Add breakpoints. To add a breakpoint, click to the left of the line’s number. A marker appears around the line number. 604 JAVASCRIPT & JQUERY: THE MISSING MANUAL DEBUGGING WITH THE CONSOLE FIGURE 17-5 The JavaScript console is a great way to print out diagnostic information as a program is running. You can also group together a series of log entries (for example, to group all the log messages printed during a loop) by adding console. group() before the first console. log() message in the group, and console. groupEnd() after the last message. NOTE Adding a breakpoint to a line that only contains a comment has no effect—the debugger won’t stop on that line. Only add breakpoints to lines containing actual JavaScript code. 6. Reload the web page. Because you have to view your web page in the browser to add breakpoints, the JavaScript you want to debug may have already run (before you added any breakpoints). In this case, you need to reload the page so you can start the JavaScript over again. If you added a breakpoint in a function that responds to an event (for example, you want to debug the code that runs when you click a button or mouse over a link), then you need to trigger that event—click the button, mouse over the link, or whatever—to reach the breakpoint and start the debugging process. After the script begins to run, as soon as a breakpoint is reached, the script stops. The program is frozen in time, waiting to execute the line from the first breakpoint. Chapter 17: Troubleshooting and Debugging 605 DEBUGGING WITH THE CONSOLE FIGURE 17-6 A debugger lets you set breakpoints (lines where the script stops and waits), control the execution of the script, and watch variables in the Watch list. As the debugger executes the script, the current line (the one that’s about to run) is highlighted. 7. Use the debugger’s controls to step through the execution of the program. Most debuggers provide four controls (Figure 17-7) that dictate how the program runs after stopping at the breakpoint. You can read about these controls in the next section. 8. Monitor program conditions in the watch list (Figure 17-7). The point of stepping through a program is to see what’s going on inside the script at any particular line. The watch list provides basic information about the program’s condition and lets you add additional variables you want to watch. For example, if you wanted to track the value of the variable score as the script runs, you can do that in the watch list. You’ll find out how to use the watch list on page 608. 9. Fix your script in a text editor. Hopefully, in stepping through your script you’ll find out what’s going wrong—for example, why the value of a particular variable never changes, or why a conditional statement never evaluates to false. With that information, you can then 606 JAVASCRIPT & JQUERY: THE MISSING MANUAL jump to your text editor and modify your script (you’ll run through an example of fixing a script in the tutorial on page 609). DEBUGGING WITH THE CONSOLE 10. Test the page in the browser, and, if necessary, repeat the previous steps to keep debugging your script. CONTROLLING YOUR SCRIPT WITH THE DEBUGGER Once you’ve added breakpoints to the script and reloaded the page, you’re ready to step through the script line by line. If you added a breakpoint to part of the script that runs when the page loads, the script will stop at the breakpoint; if you added a breakpoint to a line that only runs after an event (like clicking a link), you need to trigger that event before you can get to the breakpoint. When the debugger stops the program at a breakpoint, it doesn’t run that line of code; it stops just before running it. You can then click one of the four buttons on the debugger to control what the debugger does next (Figure 17-7): • Play. The Play button simply starts the script running. The script won’t stop again until the JavaScript interpreter encounters another breakpoint, or until the script has finished running. If there’s another breakpoint, the script stops again and waits for you to click one of the four debugger controls. Use the Play button if you just want run the program through or skip to the next breakpoint. • Step Over. This useful option runs the current line of code, then stops at the next line in the script. It’s named Step Over because if the current line of code includes a call to a function, it won’t display the function’s code or stop at the first line inside the function—it simply runs the function (steps over it) and stops at the next line of code. This option is great if you know the function that’s being called works flawlessly. For example, if your script calls a jQuery function, you’ll want to step over the call to that function—otherwise, you’ll be spending a lot of time viewing the scary jQuery programming line by line. You’ll choose the Step Over option, unless you’re at a line of code that calls a function you’ve created—then you’ll probably want to see what happens inside that function using the Step Into option described next. • Step Into. Step Into takes the debugger into a function call. That is, if you’re on a line that includes a call to a function, the debugger enters the function and stops at the first line of that function. This option is the way to go when you’re not sure if the problem is in the main script or within a function you wrote. Skip this option if you’re sure that the function being called works—for example, if the function is one you’ve used dozens of times before. You also want to use Step Over instead of Step Into when you’re debugging a line of code that includes a jQuery selector or command. For example, $('#button') is a jQuery way to select an element on the page. However, it’s also a function of the jQuery library, so if you click the Step Into button when you encounter a jQuery function, you’ll jump into the complex world of the jQuery library. (And Chapter 17: Troubleshooting and Debugging 607 DEBUGGING WITH THE CONSOLE if that happens, you’ll know because the script tab will change to show all of the JavaScript code for the jQuery file.) If, when using the debugger, you find yourself lost within a function, or in the code of a JavaScript library like jQuery, you can use the control described next to get out. • Step Out. The Step Out button gets the debugger out of a function call. You’ll usually use it after using Step Into. When you do, the function runs as normal, but you won’t stop at each line of the function as you would if you clicked the Step Over or Step Into buttons. When you click this button, the debugger returns to the line where the function was originally called and then stops. WATCHING YOUR SCRIPT While the buttons at the top of the debugger let you control how the script executes, the whole point of a debugger is to see what’s going on inside the script. That’s where the watch list comes in (Figure 17-7). The watch list provides a listing of variables and functions within the context of the current executing line of code. All that means is if you put a breakpoint within a function, you’ll see a list of all of the variables that are defined within that function; if you put a breakpoint in the main body of your script, you’ll see a list of all variables that are defined there. You’ll also see any functions that you’ve created listed in the watch list. You can add your own variables and expressions using the yellow bar with the label “New watch expression…”. Just click the yellow bar, and a text field appears. Type the name of a variable you’d like to track, or even a JavaScript statement you’d like to execute. For example, because the debugger doesn’t keep track of a counter variable in a for loop (page 82), you can add this variable, and as you go step by step through the loop, you can see how the counter changes each time through the loop. You can think of this watch list as a kind of a continual console.log() command. It prints out the value of a particular variable or expression at the time a particular line of code is run. The watch list offers valuable insight into your program, providing a kind of freezeframe effect so you can find exactly where in your script an error occurs. For example, if you know that a particular variable holds a number value, you can go step by step through the script and see what value gets stored in the variable when it’s first created and see how its value gets modified as the program runs. If, after you click the Step Through or Step Into buttons, you see the variable’s value change to something you didn’t expect, then you’ve probably found the line where the error is introduced. NOTE Keep in mind that when the program is paused, the debugger highlights the line of code that’s going to run next. So if that line sets the value of a variable, you won’t see that new value in the watch list until you click the Step Through button. 608 JAVASCRIPT & JQUERY: THE MISSING MANUAL DEBUGGING TUTORIAL FIGURE 17-7 A debugger’s watch list shows the value of different variables as the code runs. You can add your own expressions to the list, which appear as grey stripes at the top of the window. Debugging Tutorial In this tutorial, you’ll use Firebug to debug a file that’s filled with various types of errors (syntax errors, runtime errors, and logic errors). The page is a simple quiz program that poses three questions and prints quiz results. (Open the complete_debugger.html file in the chapter17 folder in any web browser to see how the page is supposed to work.) NOTE See the note on page 12 for information on how to download the tutorial files. Chapter 17: Troubleshooting and Debugging 609 DEBUGGING TUTORIAL Like the other tutorials in this chapter, this one is run in Chrome. You can try it with another web browser, but the JavaScript Console and debugger may look different than what you see on these pages. 1. Start Chrome and open the file debugger.html from the chapter17 tutorials folder. Open the JavaScript console: click the Chrome settings button and choose Tools→JavaScript Console. Or, use the keyboard shortcut, Ctrl+Shift+J (Windows) or c-Option-J (Mac). The Console reports two errors on this page. You’ll tackle the second one first. That error is listed as an “Uncaught SyntaxError: Unexpected token ; ” error. The meaning is not immediately obvious, but it says that the browser didn’t expect to run into a ; at this point. Given that the semicolon marks the end of a statement, there must be something wrong with that statement. Notice, also, that the line number of the error is listed (circled in Figure 17-8). 2. Click the line number (circled at top in Figure 17-8). Chrome opens the Sources panel, and highlights the line with the problem. Remember that a lot of bugs are often simple typos. One common mistake is forgetting to add a closing, matching punctuation mark like a ), “, ] or }, so you may be able to spot the problem right away. In this case, you’ve got an array that starts on line 11—var quiz = [—but there’s no end to the array, no closing ]. 3. Launch your text editor and open the file debugger.html . Locate line 15 (it’s a single ; on a line by itself). Type a closing square bracket before the ; so the line looks like this: ]; This bracket ended a nested array that contained all of the questions and answers for the quiz. 4. Save the file; return to Chrome, and reload the page. One of the original errors is still there. And, there’s another error! This time the error console says “$ is not defined” and points to line 8 containing jQuery’s $(document).ready() function. When a browser reports that something’s “not defined,” it means the code is referring to something that doesn’t exist, which could be the name of a variable or a function that hasn’t yet been created. Or you might just have a typo in the code. In this case, the code looks OK. The culprit is actually earlier on the page, in this code: <script src="_js/jquery.min.js"></script> A common problem when working with external scripts is accidentally typing the wrong path to the script. In this case, the jquery.min.js file is located inside a folder named _js that’s outside this file’s folder. The code here says that the file should be inside a folder named _js that’s in the same folder as this web page; 610 JAVASCRIPT & JQUERY: THE MISSING MANUAL because the browser can’t find the jquery.min.js file (where jQuery’s special $() function is defined), it spits out an error. DEBUGGING TUTORIAL FIGURE 17-8 You can jump from the console to the spot in your code where an error occurs by clicking the line number listed next to the error in the console (circled). The Sources panel appears, and the spot where the error was found is highlighted. 5. Change the <script> tag to read: <script src="../_js/jquery.min.js"></script> Chapter 17: Troubleshooting and Debugging 611 DEBUGGING TUTORIAL The ../ indicates that the js folder is outside this folder, and the path is now correctly pointing to the jQuery file. What else could be wrong with this program? 6. Save the file; return to the browser and reload the page. No errors—because both errors were caused by the same problem. The first error said that the jQuery file wasn’t found, and because the browser couldn’t find that file, it didn’t know what the $ meant. Looks like the page is fixed…or is it? 7. Click the Start Quiz button on the web page. Bam! Another error. This time the console reports that “askQuestions is not defined” and points to line 69 near the end of the script. Because this error appears only while the program is running, it’s called a runtime error (see the box on page 592). The problem appears toward the end of the script, within this conditional statement: if (quiz.length>0) { askQuestions(); } else { giveResults(); } By now it’s probably dawning on you that when something’s not defined, it’s often just because of a simple typo. In this case, askQuestions() is a call to a function, so take a moment now to look through the code and try to find this function. Did you find it? While there isn’t an askQuestions() function, you should have noticed an askQuestion() function (without an s). 8. Return to your text editor, and then remove the last s from askQuestions() in line 69 (near the end of the script). Save the file, reload it, and then click the Start Quiz button again. Now, a quiz question appears along with five multiple-choice options. Unfortunately, the last option has a label of “undefined.” Smells like an error. However, the JavaScript console is empty, so technically there’s no JavaScript error. Something must be wrong with the program’s logic. To get to the bottom of the trouble, you’ll need to use the debugger. 9. In Chrome, click the Sources tab and select debugger.html from the file list (Figure 17-9). The Sources tab gives you access to the page’s JavaScript. If the page includes JavaScript and you’ve linked to other external JavaScript files, the Source menu lets you choose which JavaScript code you wish to debug. Because the “undefined” radio button seems to be out of place, the code that creates the radio buttons is a good place to start looking for this bug. If you had written this script, you’d probably know just where to look in your code; 612 JAVASCRIPT & JQUERY: THE MISSING MANUAL however, if you were just handed this buggy script, you’d have to hunt around until you found that part of the script. DEBUGGING TUTORIAL In this case, the radio buttons are created within a function named buildAnswers(), whose purpose is to build a series of multiple choice options represented by radio buttons. That function is passed an array that includes a list of values for each radio button. When the function is done, it returns a string containing the HTML for the radio buttons. So this function’s a good place to start debugging. FIGURE 17-9 In Firebug, you can debug any scripts that the current page uses. The Source menu lets you select the JavaScript embedded in the current web page or from any attached external JavaScript file. 10. In the middle pane of the Sources tab (the part listing the HTML and JavaScript for the page) scroll down until you see line 47. Click to the left of 46 to insert a breakpoint (circled in Figure 17-9). That line number is highlighted, indicating a breakpoint, or a spot in the code, where the JavaScript interpreter stops running the script. In other words, when this script runs again, the moment the JavaScript interpreter hits that line, it stops, and you’ll be able to step line by line through the code to see what’s happening under the hood. The debugger also lets you look at the values of variables as the program runs, much as you used the console.log() function on page 598. You’ll tell the debugger what variables you want to track next. Chapter 17: Troubleshooting and Debugging 613 DEBUGGING TUTORIAL 11. In the right side of the window, click the + button (just to the right of “Watch Expressions”), type i, and then press the Return (or Enter) key. This step adds the variable i to the Watch list. That variable is used in the for loop as a counter to track how many times the loop runs (see page 78 for more on for loops). As the script runs, you’ll be able to see how that value changes. Next, you’ll add another variable to watch. 12. Click the New Watch Expression bar again, type answers.length, and then hit Return. Don’t worry about the value the debugger displays at this point (it probably says that answers.length is undefined). You can’t track the values of many variables until you’re actually running the debugger and are inside the function where the variable lives. Now it’s time to take a look inside the script. 13. Click the Reload button or press Ctrl+R (c-R). When the page reloads, click the Start Quiz button on the web page. The script starts, and the first question is written to the web page. But when it comes time to create the radio buttons, the debugger stops at line 46 (see the top image in Figure 17-10). Notice that in the Watch tab, the value for i is not available. That’s because the breakpoint stops the program just before the line is executed. In other words, the loop hasn’t started, and the i variable hasn’t yet been created. However, the value of answers.length is set to 4. The array answers is an array of answers that was passed to the function. An array’s length property indicates the number of items in the array; in this case there are four, so you should get four radio buttons when the function’s completed. 14. Click the Step Over button (Figure 17-10). This button takes you to the next line in the program. Now you can see that i is set to 0. You’ll keep clicking through this loop. 15. Click the Step Over button until you see the value of i change to 5 in the watch list (bottom image in Figure 17-10). Although there are only four items in the answers array, you can see that the for loop is actually running five times (the value of i). So something’s funny about how the loop is terminated. Remember that in a for loop, the middle expression in the for statement is the condition that must be true for the loop to run (page 82). In this case, the condition is i<=answers.length;. In other words, the loop starts out with i containing 0 and continues to run as long as i is less than or equal to the number of items in the answers array. In other words, i will be 0, 1, 2, 3, and 4 before it terminates—that’s five times. However, because there are only four items in the answers array, the fifth time through the loop there are no more answers to print: “undefined” is printed because there is no fifth item in the answers array. 614 JAVASCRIPT & JQUERY: THE MISSING MANUAL DEBUGGING TUTORIAL 16. Return to your text editor, and change the for loop at line 46 to read: for (i=0;i<answers.length;i++) { Now the loop only runs for the number of items in the answers array, creating one radio button for each possible answer. FIGURE 17-10 The watch list can display more than just the variables or expressions that you add. The Scope Variables section, for example, lists all of the variables inside the “scope” of the current function. In this example (top image) you can see that the variable answerHTML and answers are both variables accessible within the buildAnswers() function. 17. Save the file, and preview it in the browser. You can turn off the breakpoint by clicking its highlighted line number in the Sources panel to see the finished page run without interruption. The page complete_debugger.html contains the completed version of this tutorial. As you can see, finding bugs in a program can take a lot of work. But a debugging tool makes it a lot easier to see inside a program’s “guts” and find out what’s going wrong. Chapter 17: Troubleshooting and Debugging 615 PART Appendix APPENDIX A: JavaScript Resources 6 APPENDIX JavaScript Resources A T his book provides enough information and real-world techniques to get your JavaScript career off to a great start. But no one book can answer all of your JavaScript or jQuery questions. There's plenty to learn when it comes to JavaScript programming, and this appendix gives you taking-off points for further research and learning. References Sometimes you need a dictionary to read a book. When programming in JavaScript, it's great to have a complete reference to the various keywords, terms, methods, and other assorted bits of JavaScript syntax. You can find references both online and in books. Websites • The ECMAScript site (www.ecmascript.org) houses documentation and information about ECMAScript (the official name for JavaScript). It’s where to learn about the current state (and future) of JavaScript. • Mozilla Developer Center Core JavaScript Reference (https://developer. mozilla.org/en-US/docs/Web/JavaScript/Reference) provides a complete reference to JavaScript. It's very detailed, but sometimes hard to understand because it's aimed at a technical audience. • WebPlatform.org (http://www.webplatform.org) covers JavaScript, DOM, and CSS and tells you which features are supported by each browser. It's a kind of encyclopedia for Web developers. 619 BASIC JAVASCRIPT • MSDN JavaScript Language Reference (http://msdn.microsoft.com/en-us/library/ d1et7k7c(v=VS.94).aspx) from Microsoft is an excellent resource if you're developing with Internet Explorer. While it provides technical information on the JavaScript used in other browsers, this resource provides a lot of IE-only information. Books • JavaScript: The Definitive Guide by David Flanagan (O'Reilly) is the most thorough printed encyclopedia on JavaScript. It's a dense, heavy tome, but it has all the details you need to thoroughly understand JavaScript. Basic JavaScript JavaScript isn't easy to learn, and it never hurts to use as many resources as possible to learn the ins and outs of programming for the Web. The following resources provide help with the basics of the JavaScript language (which can sometimes be quite difficult). Websites • The W3 Schools JavaScript tutorial (www.w3schools.com/js) is a thorough (though not always thoroughly explained) tutorial that covers most aspects of JavaScript programming. • An Introduction to JavaScript from howtocreate.co.uk (www.howtocreate. co.uk/tutorials/javascript/introduction) provides a free, detailed discussion of JavaScript. Of course, since you're using jQuery you won't need a lot of the information on this site; it covers much of the traditional methods of selecting and manipulating DOM elements. Books • Head First JavaScript Programming by Eric Freeman and Elisabeth Robson (O'Reilly) is a lively, highly illustrated introduction to JavaScript programming. It provides lots of information on JavaScript and is presented in a playful style. jQuery Much of this book covered the jQuery JavaScript library, but there's still lots to learn about this powerful, timesaving, and fun programming library. Websites • The jQuery Blog (http://blog.jquery.com) keeps you up to date on all things jQuery. • jQuery's documentation is a go-to resource for all aspects of jQuery (http:// api.jquery.com). Every feature, function, and facet of jQuery is well documented. 620 JAVASCRIPT & JQUERY: THE MISSING MANUAL Working examples demonstrate each jQuery function so you can see how a function is supposed to be used and how it works. ADVANCED JAVASCRIPT • jQuery Fundamentals (http://jqfundamentals.com) provides a unique hands-on instructional approach to jQuery. Not only does the site explain basic jQuery concepts, but it also provides a JavaScript "sandbox" built into each page of the site, so you can fiddle with code and watch the results live. Books • jQuery in Action by Bear Bibeault and Yehuda Katz (Manning) covers jQuery thoroughly with lots of example programming. It assumes some JavaScript and programming knowledge. • jQuery Cookbook (O'Reilly) features tons of "recipes" for some of the most common tasks and problems you'll face as a programmer. It's written by a cast of characters, many of them the brilliant minds behind jQuery. Advanced JavaScript Oh yes, JavaScript is even more complicated than this book leads you to believe. Once you become proficient in JavaScript programming, you may want to expand your understanding of this complex language. Articles and Presentations • JS-Must-Watch (https://github.com/bolshchikov/js-must-watch/) is a GitHub repository dedicated to listing the best JavaScript presentations and videos on the Web. Websites • Eloquent JavaScript (http://eloquentjavascript.net) is an online JavaScript book. It's organized well, with creative ways of teaching lessons. Although it's supposed to be a beginner JavaScript tutorial site, the author writes as though he's talking to a bunch of computer scientists, so it's not the best place to start if you're new to JavaScript or programming. It's also available as a print book. • The JavaScript section of Douglas Crockfords' World Wide Web (http:// javascript.crockford.com) provides a lot of (complex) information about JavaScript. There's a lot of information on the site, some of it requiring a computer science degree just to understand. • Mozilla Developers Network JavaScript section (https://developer.mozilla. org/en-US/docs/Web/JavaScript) contains tons of JavaScript information including the JavaScript reference mentioned at the beginning of this appendix, but also a detailed guide that covers the different versions of JavaScript as well as detailed tutorials for beginner to advanced JavaScript programmers. Appendix A: JavaScript Resources 621 CSS Books • The Principles of Object-Oriented JavaScript by Nichola Zakas is a short book (fewer than 100 pages) dedicated to advanced methods of organizing code. This is pro stuff, and worth a read. • JavaScript Patterns by Stoyan Stefanov (O'Reilly). This book is a bit dated, but still full of great information for pushing your JavaScript programming forward. This book provides programming "patterns" that solve common tasks including how best to work with object literals, JSON, and arrays. Heavy duty programming; not for beginners. • JavaScript: The Good Parts by Douglas Crockford (O'Reilly) is an oldie but a goodie. It uncovers the most useful parts of JavaScript, sidestepping bad programming techniques. Douglas should know what he's talking about, as he's a Senior JavaScript Architect at Yahoo! and the inventor of JSON. The book is short and dense, but contains a lot of wisdom about how to use JavaScript well. CSS If you're tackling this book, you're probably already pretty comfortable with CSS. JavaScript can really take advantage of the formatting power of CSS to control not only the look of elements, but even to animate them across the screen. If you need a CSS refresher, here are a few helpful resources. Websites • The Complete CSS Guide from WestCiv (www.westciv.com/style_master/ academy/css_tutorial) covers pretty much every part of Cascading Style Sheets. You won't learn a lot of different techniques here, but the basics of what CSS is and how to create styles and style sheets are thoroughly covered. • The Mozilla Developer Network CSS Reference (https://developer.mozilla. org/en-US/docs/Web/CSS/Reference) is an A to Z guide to CSS properties. • Selectutorial (http://css.maxdesign.com.au/selectutorial) is a great way to learn CSS selector syntax. jQuery is pretty much founded on the idea of using CSS selectors to manipulate the HTML of a page, so it pays to have a very good understanding of this concept. Books • CSS3: The Missing Manual by David Sawyer McFarland (O'Reilly) is a thorough, tutorial-driven book on Cascading Style Sheets. It includes in-depth coverage of CSS as well as real-world examples and troubleshooting tips for making sure your CSS works in a cross-browser world. • CSS: The Definitive Guide by Eric Meyer (O'Reilly). The name says it all; this book covers CSS in such detail that your brain will definitely hurt if you try to read it all in one sitting. 622 JAVASCRIPT & JQUERY: THE MISSING MANUAL Index Symbols <a> (anchor) tags, xviii += (add and assign) operator, 39 ++ (adds 1 to variable) operator, 39,66,79–80 & (ampersand), as part of query string, 464–465 && (AND operator), 70–71 * (asterisk), as multiplication operator, 34–36 *= (multiply and assign) operator, 34 <body> tags about, xviii putting templates before closing, 325 <body> tags, in DOM, 117 { } (braces) in conditional statements, 63–64,73– 75 in declaration block of CSS style, xx in JSON, 477 in loops, 82 in user-defined functions, 86 leaving off closing brace, 589 [ ] (brackets), creating arrays using, 46 <> (bracket symbols), in HTML tags, xvii <button> element tags, 367–368,383– 384 , (comma), using to separate name/ value pairs in object literal, 247 <div> tags as wrapped block-level element, 189 hiding form fields, 266,272 in accordion widgets, 338 inserting empty, 458,460 turning into draggable item, 401,409 turning into droppable item, 416 using in relationships, 532 using in Tabs widget, 324–326 using to sort items, 427–429 $ (dollar sign), in variable names, 30,177,504 $() function, jQuery() and, 521–522 $.get() function, 471–478 $.getJSON() function, 478– 483,486,490–491 $.post() functions, 470,476–477 == (equality operator), in conditional statements, 593 = (equal sign) as assignment operator, 32–33 errors in conditional statements using, 74,593 == (equality operator), in conditional statements, 64–65,74 === (strict equality operator), in conditional statements, 64 <form> tags, 251,259 / (forward slash) as division operator, 34–36 in closing HTML tags, xvii in URL root-relative path, 11 623 // (FORWARD SLASHES), FOR SINGLE LINE COMMENTS 624 // (forward slashes), for single line comments, 58,63 > (greater than operator), in conditional statements, 64 >= (greater than or equal to operator), in conditional statements, 64 <h1> (heading 1) tags, xix,189 <h2> (heading 2) tags, xix <head> tags about, xviii in DOM, 117 putting $(document).ready() function in, 161,584 <html> tag about, xviii in DOM, 117 - (hyphens), using CSS properties with, 191–192 <img> tags, 123,137,210,213,532 !important rule, 394 != (inequality operator), in conditional statements, 63–64 <input> tags, 252,254 <label> tags, 252–253 < (less than operator), in conditional statements, 64 <= (less than or equal to operator) in conditional statements, 64 <link> tags, 245 <li> tags, 242–244,344,502–503 <message> tags, 471 .min (minified), using in file name, 282,304 - (minus sign) as subtraction operator, 34–36 on web pages, 179 /*...*/ multi-line comments, 58 * (multiplication operator), 34–36 *= (multiply and assign) operator, 39 ! (NOT operator), 72 <ol> tags, 427 <option> tags, 255,361 || (OR operator), 71–72 () parentheses identifying functions with, 26 in calling functions, 87 leaving off closing, 588–590 using to group mathematical operations, 36 INDEX </p> (closing paragraph tag), xviii % (percent sign), modulus operator represented by, 571–572 + (plus sign) as addition operator, 34–36 as concatenation operator, 36–38 on web pages, 179 # (pound sign), in ID selectors, 120 <p> tags as opening paragraph tag, xviii as wrapped block-level element, 189 “ “ or ‘ ‘ (quote marks) debugging, 588–591 empty strings using, 43 enclosing strings with, 21,28 escaping, 592 marking strings in JSON with, 477 ↵ (return) symbol in code, 81,270 <script> tags about, 7–8 creating templates inside of, 324 in both head and body of page, 76 including $(document).ready() function within, 584 <select> tags, 252,255,361 ; (semicolon) in chained jQuery functions, 127 in declaration part of declaration block, xxi in statements, 25–26 <span> tags, 502–503 === (strict equality operator), in conditional statements, 64 !== (strict not equal to operator), in conditional statements, 64 <strong> tag, xviii <style> tags, formatting error messages using, 295 -= (subtract and assign) operator, 39 -- (subtracts 1 from variable) operator, 39 <textarea> tags, 252 <ul> tags, xix,242–244,427–429 _ (underscore) in variable names, 30 preceding name of folder, 155 A absolute path, URL, 11 absolute positioning, of effects, 187 accept option, Droppable widget, 414–415 accordion() function, jQuery, 341–342 accordion widgets components of, 338 options, 340–341 saving space with, 338–343 tutorials for creating, 342–343 activate event Droppable widgets, 418 Sortable widget, 434 activeClass option, Droppable widget, 414 active property accordion widget, 340 setting tabbed panels, 330 :active pseudo-class, 203 active state category, in ThemeRoller clickable elements, 389 add and assign operator (+=), 39 addClass() function, jQuery, 132,226,410,444,504 addition operator (+), 34–36 adds 1 to variable operator (++), 39,66,79–80 adjacent sibling selectors, 123 after() function, jQuery, 130,537 Ajax (Asynchronous JavaScript and XML) about, 447–449 about jQuery Docs Site on, 528 asynchronous meaning in, 454 basics of, 449–454 client-side and server-side using, 8 formatting data to send to web server using, 463–469 getting autocomplete data from server with, 376–377 handling errors, 470 JavaScript method for escaping strings, 465 jQuery functions for about, 455 error(), 470 get(), 453,462–466,467–475,476 html(), 467 load(), 455–457,470 post(), 453,462–466,471,476 serialize(), 466 text(), 467 tutorials using $.get() function, 471–477 processing data from web server and, 466–469 alert boxes, JavaScript, 14,159,169,305 alert() function, JavaScript, 13,157,432 “Allow blocked content” message, in Internet Explorer browser, 14 AMP (Apach, MySQL, and PHP), 451 ampersand (&), as part of query string, 464–465 ancestors, in family trees, 118 ancestor tags, 167 anchor (<a>) tags, xviii AND operator (&&), 70–71 AngularJS, 107 animate() function, jQuery, 192,197– 202,247,272,433–434,522 animate property, accordion widget, 340–341 animations, jQuery about, 191–192 color, 191 CSS3 and, 202–208 easing, 192–194,442–443 in to-do list application, 510 of changes between classes, 443– 444 performing actions after completed effect, 194–197 tutorials for, 197–202 anonymous functions, 138–140,153– 154,163 API key, 484 append() function, jQuery, 129,523,524,537 appendTo() function, jQuery, 294 application servers, Ajax and, 451 Aptana Studio, for programming JavaScript, xxiii arguments, passing, 89–90 array literal vs Array keyword, 46 array notation, 478–479 array of coordinates, for Draggable widget containment option, 403 arrays about, 44–45 accessing items in, 47–48 adding items to, 48–50 as zero-indexed, 47 INDEX ARRAYS 625 ASSIGNMENT OPERATOR (=) creating, 46–48 creating queues, 51 deleting items from, 50 in JSON, 481–482 lining up values in code, 47 loops and, 80–81 multidimensional, 97 nesting, 97 randomly selecting elements in, 567 splitting strings and joining, 582 using for autocomplete, 372–375 using toArray() function, 437–438 writing to web pages using, 51–55 assignment operator (=), 32–33 asterisk (*), as multiplication operator, 34–36 Atom software, for programming JavaScript, xxiii attr() function, jQuery, 137–138,210– 211,213,217,459 attribute, in hyperlink, xviii attribute selectors, 123–124 autocomplete() function, jQuery, 372– 374 autocomplete() widget about, 370–372,381 getting data from server, 376–378 setting properties of, 378–379 using arrays with, 372–375 automatic loops, 126 axis option Draggable widget, 402 Sortable widget, 429 B background color settings, in ThemeRoller, 388 background texture opacity settings, in ThemeRoller, 388 background texture settings, in ThemeRoller, 388 BBEdit editor, for programming JavaScript, xxiii before() function, jQuery, 130,537 beforestop event, sortable widget, 434 Bibeault, Bear, jQuery in Action, 621 bind() function, jQuery, 168 blind effect, jQuery UI, 440 blinds effect, jQuery UI, 312 626 INDEX block-level element, as component of accordion widget, 338 blur event, 151,260–261 blur() method, window object, 234 <body> tags about, xviii putting templates before closing, 325 <body> tags, in DOM, 117 boldface type, displaying HTML in, xviii Boolean data type about, 29–30 using, 66 using in disabling form field, 265 border color settings, in ThemeRoller, 388 bounce effect, jQuery UI, 312,440 braces { } in conditional statements, 63–64,73– 75 in declaration block of CSS style, xx in JSON, 477 in loops, 82 in user-defined functions, 86 leaving off closing brace, 589 brackets ([ ]), creating arrays using, 46 Brackets software, for programming JavaScript, xxii bracket symbols (<>), in HTML tags, xvii browsers. See also individual browsers adding new CSS properties, 205 Ajax and about, 449 XMLHttpRequest object feature, 452 animating CSS properties, 203 error console in. See also debugging, using console for tracking down errors, 18–24 troubleshooting typing mistakes, 199 handling events in, 152 handling of JavaScript, xiv–xv layout (rendering) engine in, 6–7 local storage feature, 516 testing pop-up windows, 233 using load() function with, 459 viewing rendered HTML in, 132 waiting for HTML to load, 160–162 window creating new, 231–236 opening external links to new, 229–231 built-in functions, JavaScript, 26 bulleted list, creating, 242–244 bulleted list tags, xix <button> element tags, 367–368,383– 384 button() function, jQuery, 369,499– 500 buttons adding to dialog box, 314–320 determining if checked on form, 257 improving, 368–370,383–384 styling buttons, 366–368 to-do list application adding, 496–497,500–501 formatting buttons, 500–501 naming, 500 :button selector, 254 buttonset() function, jQuery, 368– 370,383–384 Button widget, 366–368 C callback functions argument for status of response to, 467 creating processResponse(), 468 get() and post() functions for no, 463 in to-do list application, 510–511,514 JavaScript, 453 jQuery, 183–184,194–197,224 processContacts(), 481 calling functions, 87 cancel() functions, jQuery, 435 cancel option Draggable widget, 402 Sortable widget, 429 carousels (sliders), programming, 236 carriage returns, in JavaScript, 34 Cascading Style Sheets (CSS) about, 122 about jQuery Docs Site on, 527 absolute positioning of effects using, 187 achieving rollover effect with, 220 adding style to web pages, xix–xxi changing and reading properties using jQuery, 134–137 choosing jQuery UI files for, 304 in building navigation bar, 244 jQuery transitions and animations. See CSS3 jQuery UI files about, 391–392 overriding styles with, 392–397 providing web page presentational layer, xvi resources for, 187,622 selectors about, 119,526–527 advanced, 122–124 basic, 119–121 class, 131–132 filtering, 124–126 form, 254–255 optimizing, 525 removing or replacing selections, 130 specificity and, 393–394 understanding, 126–127 specificity in, 393–394 transformations, 410 transitions vs. jQuery UI class animations, 443 using properties with hyphens, 191– 192 web browser makers adding new properties, 205 web browsers animating CSS properties, 203 website for finding, 121 case-sensitivity of variables, 30 troubleshooting, 594 CDN (content distribution network), jQuery about, 107–108 linking to jQuery from, 108–109 tip in using Google, 112 ceil() function, JavaScript, 565 chaining functions, jQuery, 127,136,500 change event as form event, 151,262–263 Sortable widget, 434 INDEX CHANGE EVENT 627 CHANGEMONTH PROPERTY, DATEPICKER WIDGET 628 changeMonth property, Datepicker widget, 353 changeYear property, Datepicker widget, 353 checkboxes determining if checked on form, 257 improving, 366–368,383–384 in to-do list application, 508–513 validating, 292–295 :checkbox selector, 254 checked attribute, adding to form, 257 :checked filter, 255 children() function, jQuery, 533 child selectors, 122–123 Chrome error console. See error console, web browser listing errors, 588–590 opening, 597 tracking down errors, 19–21 troubleshooting typing mistakes, 199 tutorials using, 600–609 preventing alert boxes in, 305 using Firebug plug-in, 609–615 viewing rendered HTML in, 132 class animations, jQuery UI, 443–444 class selectors, 121,131–132 clickable elements, ThemeRoller categories for, 389 click-and-load method, assessing HTML with about, 456,458 using jQuery to replace, 458–462 click event, 149,153,223,227– 228,236,261 click() function, jQuery, 189– 190,205,222,225,228,422,499–500 client side vs. server side, 8 clip effect, jQuery UI, 440 clone() function, jQuery, 131 close() method, window object, 234 closest() function, jQuery, 534 closing HTML tags, xvii CoffeeCup Free HTML Editor, xxii collapsible property accordion widget, 340 setting tabbed panels, 330–331 INDEX comma (,), using to separate name/ value pairs in object literal, 247 comments, 58,63,113 compiled vs. scripting languages, 5 The Complete CSS Guide from WestCiv (website), 622 compressor programs, 585–586 concatenating, strings, 36–38,223 conditional statements about, 61–62 AND operator (&&) in, 70–71 Boolean values in, 66 condition in, 63 else clause in, 66–67 else if statements, 68–70 nesting, 73–74 NOT operator (!) in, 72 OR operator (||) in, 71–72 parts to, 63 switch statements and, 70 tips for writing, 73–75 troubleshooting, 593 using, 74–78 connectToSortable option, Draggable widget, 402 connectWith option, Sortable widget, 429–430 console, in web browsers listing errors, 588–591 opening, 597–598 setting breakpoints, 604–605 tracking down errors, 18–24 tracking script progress, 598–600 troubleshooting typing mistakes, 199 tutorials for, 600–609 viewing errors, 598 console.log() function tracking script progress, 598–600 tutorial for, 600–604 container, as component of Tabs widget, 326–327 containment option Draggable widget, 403–404 Sortable widget, 430 :contains() filter, 125 Content category, in ThemeRoller, 389–390 content distribution network (CDN), jQuery about, 107–108 linking to jQuery from, 108–109 tip in using Google, 112 Coordinated Universal Time (UTC), 575 corner radius setting, in ThemeRoller, 388 CouchDB, 8 create event, Sortable widget, 433 creditcard validation rules, for forms, 277 Crockford, Douglas The JavaScript section of Douglas Crockfords’ World Wide Web (website), 621 JavaScript: The Good Parts, 622 Crockford, Douglas, JSMin by, 585 CSS3 jQuery animations and, 202– 204,205–208 jQuery transitions and, 204–206 CSS3: The Missing Manual (McFarland), xvii,122,204,622 CSS (Cascading Style Sheets) about, 122 about jQuery Docs Site on, 527 absolute positioning of effects using, 187 achieving rollover effect with, 220 adding style to web pages, xix–xxi changing and reading properties using jQuery, 134–137 choosing jQuery UI files for, 304 in building navigation bar, 244 jQuery transitions and animations. See CSS3 jQuery UI files about, 391–392 overriding styles with, 392–397 providing web page presentational layer, xvi resources for, 187,622 selectors about, 119,122 advanced, 122–124 basic, 119–121 class, 131–132 filtering, 124–126 form, 254–255 optimizing, 525 removing or replacing selections, 130 specificity and, 393–394 understanding, 126–127 specificity in, 393–394 transformations, 410 using properties with hyphens, 191– 192 web browser makers adding new properties, 205 web browsers animating CSS properties, 203 website for finding, 121 css() function, jQuery, 134– 137,270,410,422,433–434,529–530 CSS styles, xix–xxi CSS: The Definitive Guide (Meyer), 622 CSS: The Missing Manual (McFarland), 187 currency values, formatting, 565–566 cursorAt option Draggable widget, 404–405 Sortable widget, 430 cursor option Draggable widget, 403 Sortable widget, 430 DATEPICKER WIDGET D database servers, Ajax and, 451 databases, using JavaScript, 8 data functions, jQuery, 528 data property, event object, 165 data types about, 27–29 Boolean, 29–30,66,265 numbers as, 27 storing in variables, 32–33 strings as, 27–28 working with, 33–40 dateFormat property, Datepicker widget, 354,357 date object, 570,574 datepicker() function, jQuery, 353,358,381 Datepicker widget, 115 about, 300,351 setting colors or pattern to header in, 388 setting properties of, 353–357 INDEX 629 DATES 630 tutorial for, 357–360,380–382 using, 352–353 dates. See also time creating new, 573–574 regular expressions for, 555 tracking about, 568–570 functions for, 568 getting day of week, 568–569 getting month, 568–569 date validation rules, for forms, 277 dblclick (doubleclick) event, 149 dblclick() function, jQuery, 156–158 deactivate event Droppable widgets, 419–420 Sortable widget, 434 debugging, using console for. See also troubleshooting about, 604 listing errors, 588–591 opening console, 597–598 Play button on debugger, 607,609 setting breakpoints, 604–605 Step Into button debugger, 607–609 Step Out button debugger, 608–609 Step Over button debugger, 607,609 tracking down errors, 18–24 tracking script progress, 598–600 troubleshooting typing mistakes, 199 tutorials for, 600–609 viewing errors, 598 debugging, using Firebug plugin, 609–615 declaration block, in CSS style, xx declarations, in CSS style declaration block, xxi default state category, in ThemeRoller clickable elements, 389 deferred objects, 528 delay option, Sortable widget, 431 delay property, autocomplete() widget, 378 delegate() function, jQuery, 168 descendant selectors, 122 descendants, in family trees, 118 destroy() functions, jQuery, 435 detach() function, jQuery, 510,514 determining if buttons and boxes are checked, 257 development server, setting up, 452 INDEX dialog boxes. See also dialog widget adding buttons to, 314–320 adding to to-do list application, 498– 502 creating, 306–308 opening with events, 313–315 passing options to, 311–312 positioning, 318 setting colors or pattern to header in, 388 setting properties of, 308–311 setting property for modal, 310,390 dialog() function, jQuery, 308,311– 314,317,498,507 dialog widget about, 299–300 dialog box using. See also dialog boxes adding buttons to, 314–320 creating, 306–308 opening with events, 313 positioning using, 318 setting properties of, 308–311 setting property for modal, 310 in to-do list application, 508 passing options to, 311–312 using, 305–306 website for options of, 310 digits validation rules, for forms, 277 Dinkov, Vasil, jQuery SmartMenus plug-in by, 244 disabled option Draggable widget, 404 Droppable widget, 414 disable() functions, jQuery, 436 distance option bounce effect, 440 Sortable widget, 431 divide and assign (/=) operator, 39 divide and assign operator (/=), 39 division operator (/), 34–36 <div> tags as wrapped block-level element, 189 in accordion widgets, 338 inserting empty, 458,460 turning into draggable item, 401,409 turning into droppable item, 416 using in relationships, 532 using to sort items, 427–429 doctypes, xvii,xix document.getElementById() method, 118 document.getElementsByClassName( ) method, 118 document.getElementsByTagName() method, 118 Document Object Model (DOM) about, 117–119 jQuery functions for navigating page of, 178 manipulation of web pages, 527 transversing, 531–536 document.querySelectorAll() method, 118 $(document).ready() function adding comments to, 113 adding Draggable widget to web page, 400–401 adding html() to tooltip, 326 handling multiple instances of, 584 in adding Tabs widget, 332–333 in animated dashboard, 198–202 in creating accordion widget, 342 in creating dialog box, 308 in styling buttons, 366–368 in to-do list application, 514–515 putting in <head> tag, 161,584 putting programming inside of, 596– 597 using with console.log() function, 601 with autocomplete feature, 372 with Datepicker widget, 352–353,357 with Draggable widget, 400–401,421 with Droppable widget, 413–414 with Selectmenu widget, 361 with Sortable widget, 428 document-relative paths, 595 document-relative path, URL, 11 document values for Draggable widget containment option, 403 for Sortable widget containment option, 430 document.write() command, 41,56,76,82 Dojo Toolkit (library), 107 dollar sign ($), in variable names, 30,177,504 DOM (Document Object Model) about, 117–119 jQuery functions for navigating page of, 178 manipulation of web pages, 527 transversing, 531–536 dot syntax, 478–479 doubleclick (dblclick) event, 149 double slashes (//), for single line comments, 58 do/while loops, 84–86 Download Builder, jQuery UI, 302–303 Download Theme button, on ThemeRoller page, 390 drag event, Draggable widget, 411 draggable() function, jQuery, 400,404,407,408,421–422 draggable property, setting dialog box, 308 Draggable widgets about, 399–400 adding to web page, 400–401 events, 408–410,423–425 options for, 402–409 Dreamweaver editor, for programming JavaScript, xxiii drop effect, jQuery UI, 312,440 drop event, Droppable widgets, 416– 418,425 droppable() function, jQuery, 413,424–425 Droppable widgets about, 412 events, 416–420,425 options for, 414–417 tutorial for, 420–426 using, 413–414 drop shadows, in ThemeRoller, 390 drop zone, 414–419,424 ECMASCRIPT E each() function, jQuery, 138– 141,216,226–227,481–483,491– 492,517 easing animations, 192–194 easing functions, jQuery UI, 442–443 Eclipse software, for programming JavaScript, xxii ECMAScript, xv INDEX 631 EDITPLUS EDITOR, FOR PROGRAMMING JAVASCRIPT 632 EditPlus editor, for programming JavaScript, xxiii Edward, Dean, Packer by, 585 effect() function, jQuery, 439–440,514 effects, jQuery about, 183–184 about jQuery Docs Site on, 527 absolute positioning of, 187 fading elements in and out, 185–186 hiding and showing of elements, 184–185 keywords for setting speed of, 184 passing to dialog box, 310 performing actions after completed, 194–197 photo gallery with, 220–225 sliding elements, 185–186 tutorials for, 188–191 effects, jQuery UI about, 300,438 animating changes between classes, 443–444 easing functions, 442–443 explode, 425 functions for adding, 439 functions for animating class changes, 443–444 options for, 440–442 passing to dialog box, 310,312,316 using, 439–440 Eich, Brendan, xiv elements in DOM, 117 setting attributes of HTML, 527 element selectors, 121 Eloquent JavaScript (website), 621 else clause, conditional statements, 66–67,100,178,474– 475 else if statements, 68–70 email addresses, regular expressions for, 554–555 email validation rules, for forms, 277 Ember.js, 107 empty arrays, 46 empty() function, jQuery, 539 empty strings, 43 em unit (measurement), xx “Enable blocked content” box, in Internet Explorer, 18 INDEX enable() functions, jQuery, 436 encodeURIComponent() function, JavaScript, 465 encoding (escaping) strings, 464–465 end() function, jQuery, 536 equality operator (==), in conditional statements, 64–65,74,593 equal sign (=) as assignment operator, 32–33 errors in conditional statements using, 74,593 equalTo validation rules, for forms, 282 Error category, in ThemeRoller, 389– 390 error console, web browser listing errors, 588–591 opening, 597–598 setting breakpoints, 604–605 tracking down errors, 18–24 tracking script progress, 598–600 troubleshooting typing mistakes, 199 tutorials for, 600–609 viewing errors, 598 error() function, jQuery, 470 error messages “$ is not defined” error, 594 formatting, 295–296 from argument for status of response to callback function, 467 validating forms, 275,278–279,283– 285,289–296 “x is not defined” error, 596 errorPlacement objects, 294 errors. See also troubleshooting Ajax handling, 470 built-in mechanism to protect against, 585 reducing programming, 597 types of, 592 escape (encode), special characters, 464–465 escaping float, 348–349 escaping quote marks, 592 :even filter, 125 event bubbling, 167 event delegation, 168,508–513 event handler, adding in to-do list application, 508 event helpers, 152 event objects, jQuery, 164–165 event property accordion widget, 341 setting tabbed panels, 331 events about, 147–148 about jQuery Docs Site on, 527 assigning, 153 delegating, 171–174 Draggable widget, 408–410,423–425 Droppable widget, 416–420,425 form, 151,257–262 hover, 198 keyboard, 151–152 mouse, 148–150 mouseEnter, 198,219 mouseLeave, 198,219 onload, 159 opening dialog boxes with, 313–315 opening new window, 235–236 passing function to, 153–154 removing, 166–167 Sortable widget, 432–435 stopping normal behavior of, 165–167 tutorials for, 155–159,174–179 using jQuery, 152–155 using on() function for, 167–174 window object, 150 evt variable, 165 example files, getting, xxvii explode effect, jQuery UI, 310,312,316,425,440 external JavaScript files attaching to web page, 15–18 compressing, 585 incorrect paths of, 594–596 using, 8–11,583–584 F fade effect, jQuery UI, 440 fadeIn() function, jQuery, 180,185,194– 197,224,272,522 fadeOut() function, jQuery, 138,180,185,224,272 fadeTo() function, jQuery, 186,194,532 fadeToggle() function, jQuery, 186– 187,189–190 false value, Boolean, 29,66,265 “falsy” values, 69 family trees, 118 fast-loading JavaScript, creating, 585–586 fields, in forms about jQuery Docs Site on, 527–528 autocomplete feature about, 370–372,381 getting data from server, 376–378 property options for, 378–379 using arrays with, 372–375 checkboxes in improving, 366–368,383–384 in to-do list application, 508–513 validating, 292–295 checking value of form element, 257 clicking on, 261 dialog box with attached, 314 disabling, 264–265,268–271 enabling, 264–265 focusing on, 259–260,262–263,267 getting and setting value of, 256 hiding, 265–266,271–273 picking dates using Datepicker on about, 351 setting properties of, 353–357 tutorial for, 357–360,380–382 using, 352–353 radio buttons improving, 366–368 selecting, 270 validating, 292–295 selecting, 253,264,270 showing, 265–266 styling buttons, 366–368 styling select menus using Selectmenu widget, 360–365,383 triggering blur event, 260–261 tutorials for form widgets, 379–384 validating. See also Validation plugin, jQuery about, 273 advanced, 279–286,289–296 basic, 276–279,287–289,292 checkboxes, 292–295 error messages, 275,278– 279,283–285,289–296 keeping in external JavaScript file, 583 preventing malicious input, 277 radio buttons, 292–295 FIELDS, IN FORMS INDEX 633 :FILE SELECTOR rules for, 275–278,280–284,289– 292 server-side, 277,284 tutorials for, 286–296 :file selector, 254 filtering, 255 filters, jQuery selection, 124–126,255 find() function, jQuery, 433– 434,525,532–533 Firebug plug-in, 22,609–615 Firefox error console. See also error console, web browser about, 22–23 listing errors, 588–591 opening, 598 JavaScript Web Console, 199 viewing rendered HTML in, 132 :first filter, 125 fit value, for Droppable widget tolerance option, 416–417 flags, Booleans creating, 66 Flanagan, David JavaScript: The Definitive Guide, 620 Flash, 8 Flickr Feed, adding to website about, 484 constructing URL, 484–486 getting Flickr ID, 485 maximum images retrieved, 493 retrieving photos from Flickr group, 489 tutorial for, 488–493 Flickr JSON Feed, 487–488 floor() function, JavaScript, 565 focus event, 151,259–260,262 focus() function, jQuery, 263 focus() method, window object, 234 fold effect, jQuery UI, 440 Font Settings category, in ThemeRoller, 386 for loops, 82–83 forms (web forms) about, 251–253 about jQuery Docs Site on, 527–528 autocomplete feature about, 370–372,381 getting data from server, 376–378 property options for, 378–379 using arrays with, 372–375 634 INDEX checkboxes in improving, 366–368,383–384 in to-do list application, 508–513 validating, 292–295 determining if buttons and boxes are checked, 257 dialog box with attached, 314 events for, 151,257–262 fields in checking value of form element, 257 clicking on, 261 disabling, 264–265,268–271 enabling, 264–265 focusing on, 259–260,262– 263,267 getting and setting value of, 256 hiding, 265–266,271–273 selecting, 253–254,264,270 showing, 265–266 triggering blur event, 260–261 getting and setting value of form element, 255–256 hiding form options, 265–266,271– 273 picking dates using Datepicker on about, 351 setting properties of, 353–357 tutorial for, 357–360,380–382 using, 352–353 radio buttons improving, 366–368 selecting, 270 validating, 292–295 selecting form elements, 253– 254,270 showing form options, 265–266 stopping multiple submissions, 266 styling buttons, 366–368 styling select menus using Selectmenu widget, 360–365,383 tutorial for enhancing, 266–272 tutorials for form widgets, 379–384 validating. See also Validation plugin, jQuery about, 273–274 advanced, 279–286,289–296 basic, 276–279,287–289,292 checkboxes, 292–295 error messages, 275,278– 279,283–285,289–296 keeping in external JavaScript file, 583 preventing malicious input, 277 radio buttons, 292–295 rules for, 275–278,280–284,289– 292 server-side, 277,284 tutorials for, 286–296 <form> tags, 251 forward slash (/) as division operator, 34–36 in closing HTML tags, xvii in URL root-relative path, 11 forward slashes (//), for single line comments, 58 fragments, creating page, 336 Freeman, Eric, Head First HTML with CSS and XHTML, xvii Freeman, Eric, Head First JavaScript Programming, 620 full stack JavaScript, xv,8 function() [ ], as outer shell in jQuery, 156 functions, JavaScript adding comments after, 113 alert(), 13–14,157,169,432 assigning values to variables within, 95 callback functions, 453 calling, 87 ceil(), 565 encodeURIComponent(), 465 floor(), 565 getData(), 517 getDate(), 568 getDay(), 568–569 getElementById(), 118 getElementsByClassName( ), 118 getElementsByTagName(), 118,121 getFullYear(), 568 getHours(), 568,570–571 getMinutes(), 568,570–571 getMonth(), 568–569 getSeconds(), 568,570–571 getTime(), 568,572–573 global scope of, 94 global variables in, 94 isNaN(), 26,261,565 JavaScript built-in, 26 join(), 82 local variables in, 94 methods as, 26 new Date(), 568,571,573–574 Number(), 38–39,563 openExt(), 230 parentheses in identifying, 26 parseFloat(), 564 parseInt(), 563–564 pop(), 51–52 processContacts(), 478 processData(), 474 prompt(), 43,76,562 push(), 49–50 querySelectorAll( ), 118 random(), 566–567 round(), 565 scope of, 93–95 shift(), 51–52 troubleshooting disappearing functions, 596 unshift(), 49–50 write(), 41,56,76,82 writing about, 84–86 calling functions, 87 giving information to functions, 89–90 parameters for functions, 89–91 passing arguments, 89–90 returning values from functions, 91–93 scope of functions, 93–95 tutorials for, 87–88,96–101 functions, jQuery $(), jQuery() and, 521–522 accordion(), 341–342 addClass(), 132,226,410,504 adding comments after, 113 after(), 130,537 animate(), 192–193,197– 202,247,272,433–434,522 anonymous, 138–140,153–154,163 append(), 129,523,524,537 appendTo(), 294 attr(), 137–138,210–211,213,217,459 autocomplete(), 372–374 before(), 130,537 bind(), 168 INDEX FUNCTIONS, JQUERY 635 FUNCTIONS, JQUERY 636 button(), 369,499–500 buttonset() function, 368–370,383– 384 callback, 183–184,194–197,224 cancel(), 435 chaining, 127,136,500 children(), 533 click(), 189– 190,205,222,225,228,422,459,499– 500 clone(), 131 closest(), 534 css(), 134–137,270,410,422,433– 434,529–530 data functions, 528 datepicker(), 353,358,381 dblclick(), 156–158 delegate(), 168 destroy(), 435 detach(), 510,514 dialog(), 308,311–314,317,498,507 disable(), 436 draggable(), 400– 402,404,407,408,421–422 droppable(), 413,424–425 each(), 138–141,216,226– 227,254,481–483,491–492,517 easing, 442 effect(), 439,514 empty(), 539 enable(), 436 error(), 470 fadeIn(), 180,185,194– 197,224,272,522 fadeOut(), 138,180,185,272 fadeTo(), 186,194,532 fadeToggle(), 186–187,189–190 find(), 433–434,525,532–533 focus(), 263 for manipulating HTML, 535–539 for navigating page of DOM, 178 get(), 453,462–466,467–476 getData(), 517 hide(), 121,184– 185,265,324,425,439,510 hover(), 162–164,199,214–215,218–219 html(), 128–129,325,467,523,535 indexOf(), 543–545,547 is(), 178 ive(), 168 INDEX jQuery(), $() function and, 521–522 lastIndexOf(), 544–545 load(), 470 load() function, 455–462 match(), 559 menu(), 346,349 mouseover(), 154,158,422 next(), 178,535 noConflict(), 522 not(), 230 off(), 166–168 on(), 167–174,513 parent(), 533–534 passing to event, 153–154 post(), 453,462–466,471,476–477 prepend(), 129–130,475,506,523,537 prev(), 535 preventDefault(), 165– 166,222,228,259,313,460 reading jQuery Docs Site on, 529– 531 ready(), 156–158,160–161. See also $(document).ready() function remove(), 130,225,514,537 removeAttr(), 137–138 removeClass(), 133 replace(), 493,560 replaceWith(), 211–212,537 search(), 558 selectmenu(), 361–362,383 serialize(), 436–437,466 show(), 184,228,265,439,504,510 siblings(), 534–535 slice(), 545–546 slideDown(), 179–180,186,247,272,511 slideToggle(), 187,189–190 slideUp(), 180,186,272,510 sortable(), 428–430 split() function, 582 stop() function, 201–202 stopPropagation(), 167 tabs(), 329–330,332–337 text(), 129,467,505,523,535 toArray(), 437–438 toFixed(), 257,566 toggle(), 164,184,189–190,439 toggleClass(), 133,190,205 tooltip(), 321,324 troubleshooting disappearing functions, 596 unbind(), 168 unwrap(), 539 val(), 159,253–254,256,502 validate(), 275–276,280–285,289– 292 wrap(), 537–538 wrapInner(), 538 G getData() function, JavaScript, 517 getDate() function, JavaScript, 568 getDay() function, JavaScript, 568– 569 getElementById() function, JavaScript, 118 getElementsByClassName( ) function, JavaScript, 118 getElementsByTagName() function, JavaScript, 118,121 getFullYear() function, JavaScript, 568 get() function, jQuery, 453,462– 466,467–476 getHours() function, JavaScript, 568,570–571 getMinutes() function, JavaScript, 568,570–571 getMonth() function, JavaScript, 568– 569 getSeconds() function, JavaScript, 568,570–571 getTime() function, JavaScript, 568,572–573 global scope, of functions, 94 global variables, in functions, 94 greater than operator (>), in conditional statements, 64 greater than or equal to operator (>=), in conditional statements, 64 grid option Draggable widget, 404–405 Sortable widget, 431 Gupta, Gaurav, 3 H <h1> (heading 1) tags, xix,189 <h2> (heading 2) tags, xix handle option Draggable widget, 405 Sortable widget, 431 :has() filter, 125 Header category, in ThemeRoller, 388–390 Head First HTML with CSS and XHTML (Robson and Freeman), xvii Head First JavaScript Programming (Freeman and Robson), 620 Head First PHP & MySQL (O’Reilly), 455 headline containing text, as component of accordion widget, 338 <head> tags about, xviii in DOM, 117 putting $(document).ready() function in, 161,584 heighth of objects, functions for determining, 528 height property, setting dialog box, 309–310 heightStyle property accordion widget, 341 setting tabbed panels, 331 hello world program, writing JavaScript, 12–15 helper option, Draggable widget, 405 Henick, Ben, 3 :hidden filter, 125–126 :hidden selector, 178,254 hide() function, jQuery, 121,184– 185,265,324,425,439,510 hide property setting dialog box, 310 setting tabbed panels, 330 tooltip widget, 322 highlight effect, jQuery UI, 441 hoverClass option, Droppable widget, 415–416 hover event, jQuery, 198 hover() function, jQuery, 162– 164,199,214,218–219 :hover pseudo-class, 203,511 hover state category, in ThemeRoller clickable elements, 389 HTML5 adding checked attribute to form, 257 form validation in, 273 special date field in, 353 INDEX HTML5 637 HTML5 FORMS (HENICK) support of placeholder attribute for forms, 260 HTML5 Forms (Henick), 3 HTML attributes, handling with jQuery, 137–138 HTML editors. See also text editors using monospaced fonts, 52 html() function, jQuery, 41,56,76,82,128– 129,325,467,523,535 HTML (Hypertext Markup Language) adding in tooltip, 324–327 creating templates inside of <script> tags, 324 elements setting attributes of, 527 transversing, 527 functions for manipulating, 535–539 providing web page structural layer, xvi–xvii representing nested structure of web pages, 118 tag commands in, xvii–xviii using jQuery for assessing, 458–462 validating, xix viewing rendered, 132 HTML-Kit editor, for programming JavaScript, xxii <html> tag about, xviii in DOM, 117 HTML tags, xvii–xviii HTML validator, xix hyperlinks, creating web page, xviii hyphens (-), using CSS properties with, 191–192 I icon color settings, in ThemeRoller, 388 icons property accordion widget, 341 Button widget, 367–368 Selectmenu widget, 363 ID selectors about, 120 in jQuery UI, 327–328 using, 525 IE (Internet Explorer) “Allow blocked content” message in, 14 638 INDEX console. See also error console, web browser about, 21–22 listing errors, 588–590 opening, 597 troubleshooting typing mistakes, 199 “Enable blocked content” box in, 18 handling events in, 152 JavaScript and, xiv viewing rendered HTML in, 132 if (conditional) statements about, 63–64 AND operator (&&) in, 70–71 Boolean values in, 66 condition in, 63 else clause in, 66–67,100,178,474– 475 else if statements, 68–70 nesting, 73–74 NOT operator (!) in, 72 OR operator (||) in, 71–72 switch statements and, 70 tips for writing, 73–75 using, 74–78 IIS, on Windows 8, 452 images adding in tooltip, 324 photo gallery with effects, tutorial, 220–225 preloading, 212–213,217 retrieving from Flickr Feed about, 484 constructing URL, 484–486 getting Flickr ID, 485 maximum images retrieved, 493 retrieving from Flickr group, 489 tutorial for, 488–493 understanding Flickr JSON Feed, 487–488 rollover, 213–220 swapping about, 209 changing src attribute of image, 209–211 with jQuery, 211–220 :image selector, 254 <img> tags, 123,137,210,213,532 indenting code, 18 indexOf() function, jQuery, 543– 545,547,559 inequality operator (!=), in conditional statements, 63–64 infinite loops, 80 :input selector, 254 <input> tags, 252,254 instances of objects, 56–57 interactions, jQuery UI about, 300,399 Draggable widgets about, 399–400 adding to web page, 400–401 events, 408–410 options for, 402–409 tutorial for, 420–424 Droppable widgets about, 412 events, 416–420 options for, 414–417 tutorial for, 420,424–426 using, 413–414 Sortable widgets events, 432–435 functions in, 435–438 options for, 429–432 using, 427 interactive effects, 4 internals, 528 Internet Explorer (IE) “Allow blocked content” message in, 14 console. See error console, web browser about, 21–22 listing errors, 588–590 opening, 597 troubleshooting typing mistakes, 199 “Enable blocked content” box in, 18 handling events in, 152 JavaScript and, xiv viewing rendered HTML in, 132 interpreter, in scripting language, 5 intersect value, for Droppable widget tolerance option, 416–417 An Introduction to JavaScript (website), 620 is() function, jQuery, 178 isNaN() function, JavaScript, 26,261,565 items option, Sortable widget, 431 ive() function, jQuery, 168 J Java programming language vs. JavaScript, xiv JavaScript about, xiii–xv adding to web page, 6–11 Ajax and about, 450 method for escaping strings, 465 arrays. See arrays as event-driven language, 147 built-in functions, 26 conditional statements. See conditional statements creating fast-loading, 585–586 data types, 27–29. See also data types functions. See functions, JavaScript Java programming language vs., xiv keywords, 31–32 libraries, 105–107 methods, 26,56 minified files (.min), 110 modifying web pages with, 113–115 object literals about, 135 as positioning property, 318 as values inside JSON, 479–482 sending data to server and, 465 separating name/value pairs in, 247,281 using with css() function, 136 widgets using, 578 objects, 55–57 programming about, 4–5 client side vs. server side, 8 relationship to jQuery, xvi resources for, 619–622 software for programming, xxii–xxiii statements, 25–26 “undefined” values, 53 variables in, 29–30. See also variables writing, 13 about, 6–7 coding multiple lines, 81,270 errors in. See troubleshooting hello world program, 12 INDEX JAVASCRIPT 639 JAVASCRIPT COMPRESSOR, YAHOO 640 indenting code, 18,270 joining arrays and splitting strings, 582 putting preferences in objects, 577–578 putting preferences in variables, 575–577 putting text for printing in variables, 577 reducing programming errors, 597 steps in, 94–95 switch statements in, 579–582 ternary operator in, 578–579 tracking down errors, 18–24 troubleshooting typing mistakes, 21,199 writing hello world program in, 12–15 JavaScript compressor, Yahoo, 585– 586 JavaScript libraries about, xvi JavaScript Patterns (Stefanov), 622 The JavaScript section of Douglas Crockfords’ World Wide Web (website), 621 JavaScript: The Definitive Guide (Flanagan), 620 JavaScript: The Good Parts (Crockford), 622 join() function, JavaScript, 82 jPanel plug-in, 249 jQuery about, xv,105–106 about doc page for, 526–531 acting on elements in selections, 138–141 adding content to web pages, 127– 130,523–524 adding to web page, 112–113 adding to web page pull quotes using, 141–145 Ajax, functions for about, 455 about jQuery Docs Site on, 528 error(), 470 get(), 453,462–476 html(), 467 load(), 455–462 post(), 453,462–466,471,476 INDEX serialize(), 466 text(), 467 tutorials using $.get() function, 471–477 animations about, 191–192 color, 191 CSS3 and, 202–204,205–208 easing, 192–194 performing actions after completed effect, 194–197 tutorials for, 197–202 chaining functions, 127,136 changing and reading CSS properties, 134–137 controlling behavior of links, 225– 229 data functions, 528 deferred objects, 528 downloading, 110–111 effects about, 183–184 about jQuery Docs Site on, 527 absolute positioning of, 187 fading elements in and out, 185– 186 hiding and showing of elements, 184–185 keywords for setting speed of, 184 passing to dialog box, 310 performing actions after completed, 194–197 sliding elements, 185–186 tutorials for, 188 events about, 147–148 about jQuery Docs Site on, 527 delegating, 171–174 form, 151,257–262 hover, 198 keyboard, 151–152 mouse. See mouse events mouseEnter, 198,219 mouseLeave, 198,219 onload, 160 removing, 166–167 stopping normal behavior of, 165–167 tutorials for, 155–159 using, 152–155 using on() function for, 167–174 window object, 150 filters, jQuery selection, 253–254 forms using. See also fields, in forms about jQuery Docs Site on, 527– 528 determining if buttons and boxes are checked, 257 disabling fields, 264–265,268–271 enabling fields, 264–265 events for, 151,257–262 focusing on first field, 262–263 getting and setting value of form element, 255–256 hiding form options, 265– 266,271–273 selecting form elements, 253– 254,270 showing form options, 265–266 stopping multiple submissions, 266 tutorial for enhancing, 266–272 functions. See also functions, jQuery reading jQuery Docs Site for, 529–531 getting, 107–111 handling HTML attributes, 137–138 internals, 528 links controlling behavior of, 225–229 opening in new window external, 229–231 modifying web pages with, 113–115 offset category on jQuery Docs Site, 529 plug-ins about, 236–237 choosing, 237–239 jPanel, 249 Multi-level Push Menu, 249 object literals, 578 setting up, 239–241 SmartMenus, 241–242,245,247– 249 Validation. See Validation plug-in, jQuery website for finding, 249 resources for, 620–621 saving lists with Prototype library, 516–517 saving selections into variables, 522– 523 selectors about, 119,526–527 advanced, 122–124 basic, 119–121 class, 131–132 filtering, 124–126 form, 254–255 optimizing, 525 removing or replacing selections, 130 specificity and, 393–394 understanding, 126–127 setting and reading tag attributes, 131–136 setting attributes of HTML, 527 setting attributes of HTML elements, 527 swapping images with about, 211–212 photo gallery with effects, tutorial, 213–220 preloading images, 211–212 rollover images, 213–220 tips and information, 521–525 to-do list application, building about, 495–496 adding buttons, 496–497,500– 501 adding dialog box, 498–502 adding tasks, 502–513 as ongoing project, 517 confirming deletions, 516 deleting tasks, 513–515 editing tasks, 515 formatting buttons, 500–501 transitions class animations vs., 443 CSS3 and, 204–206 transversing HTML elements, 527 underscore (_) preceding name of folder, 155 utilities, 528 versions of, 109,111 The jQuery Blog (website), 620 jQuery Cookbook (O’Reilly), 621 jQuery Foundation, 300 INDEX JQUERY FOUNDATION 641 JQUERY() FUNCTION, $() FUNCTION AND 642 jQuery() function, $() function and, 521–522 jQuery Fundamentals (website), 621– 622 jQuery in Action (Bibeault and Katz), 621 jQuery objects, 119 jQuery’s documentation (website), 620 jQuery UI about, 299–300 adding to web page, 304–305 advantages of, 300–301 alternatives to, 302 class animations, 443–444 customizing look of CSS files and, 391–392 overding styles, 392–397 using ThemeRoller, 385–390 Download Builder, 302–303 downloading, 303–304 effects about, 300,438 animating changes between classes, 443–444 easing functions, 442–443 explode, 425 functions for adding, 439 functions for animating class changes, 444 options for, 440–442 passing to dialog box, 310,312 using, 439–440 events custom, 335,337 Draggable widget, 408–410,423– 425 Droppable widget, 416–420,425 opening dialog boxes with, 313– 315 Sortable widget, 432–435 interactions. See interactions, jQuery UI themes adding new themes to websites, 390–391 downloading and using new themes, 390–392 overriding styles, 392–397 to-do list application, building about, 495–496 INDEX adding buttons, 496–497,500– 501 adding dialog box, 498–502 adding tasks, 502–513 as ongoing project, 517 confirming deletions, 516 deleting tasks, 513–515 editing tasks, 515 formatting buttons, 500–501 saving lists, 516–517 using easing methods from, 193–194 website for finding, 302 widgets. See also widgets, jQuery UI user interface, 115 jScript, xiv js file extension, 9,11 JSMin, 585 JS-Must-Watch (website), 621 JSON (JavaScript Object Notation) about, 476–478 accessing data, 478–479 adding format to URL, 485 arrays in, 481–482 creating complex collections of data, 479–482 sending information to server using, 466 understanding Flickr JSON Feed, 487–488 JSONP (JSON with padding) about, 483 adding callback to URL, 485 K Katz, Yehuda, jQuery in Action, 621 Kendo UI, 302 keyboard events about, 151–152 keydown, 152 keypress, 152 keyup, 152 keywords, JavaScript, 31–32 L <label> tags, 252–253 :last filter, 125 lastIndexOf() function, jQuery, 544– 545 layout (rendering) engine, in web browsers, 6–7 Learning PHP, MySQL, and JavaScript (O’Reilly), 455 less than operator (<), in conditional statements, 64 less than or equal to operator (<=), in conditional statements, 64 libraries about, 15 about JavaScript, 105–107 Prototype, 522 user interface, 302 libs file extension, 11 lightbox effect, website, 168–169 linear method, in easing animations, 193 links about, 225–226 creating web page, xviii determining destination of, 226–227 opening in new window external, 229–231 selecting with jQuery, 226 stopping, 227–228 <link> tags, 245 load event, window object, 150 load() function, jQuery, 455–462,470 local storage feature, web browsers, 516 local variables, in functions, 94 logic errors, 592 loops about, 78 arrays and, 80–81 automatic, 126–127 do/while loops, 84–86 for loops, 82–83 infinite loops, 80 return (↵) symbol in code, 81 tutorials for, 96–101 while loops, 78–80 M Mac OS X operating system (Yosemite), using JavaScript, xv MAMP, 452 manipulation, of web pages DOM, 527 Mastering HTML5 Forms (Gupta), 3 match() function, jQuery, 559 mathematical operations, 33–36,38– 40 maxDate property, Datepicker widget, 355–356,381,382 maxlength validation rules, for forms, 282 max validation rules, for forms, 282 McFarland, David Sawyer CSS3: The Missing Manual, xvii,122,204,622 CSS: The Missing Manual, 187 menu() function, jQuery, 346,349 menus, styling select, 360–365 Menu widget adding to web page, 343–349 creating horizontal navigation bar, 346–349 <message> tags, 471 methods, JavaScript, 26,56. See also functions, JavaScript Meyer, Eric, CSS: The Definitive Guide, 622 minDate property, Datepicker widget, 355–356,382 minLength property, autocomplete() widget, 378–379 minlength validation rules, for forms, 282 .min (minified), using in file name, 16,110 minus sign (-) as subtraction operator, 34–36 on web pages, 179 modal dialog box, setting property for, 310,316,390 modulus operator (%), 571 MongoDB, 8 monospaced fonts, HTML editors using, 52 monthNames property, Datepicker widget, 354 Mootools (library), 107 mouseEnter event, jQuery, 198,219 mouse events about, 148–149 click, 149,153,223,227–228,236 doubleclick (dblclick), 149 mousedown, 149 mousemove, 149–150 mouseout, 149,162–164 mouseover, 149,153,162–164,166 mouseup, 149 INDEX MOUSE EVENTS 643 MOUSELEAVE EVENT, JQUERY mouseLeave event, jQuery, 198,219 mouseover() function, jQuery, 154,158,422 mousing, over tooltips, 324 moveBy() method, window object, 234 moveTo() method, window object, 235 Mozilla Developer Center Core JavaScript Reference (website), 619 The Mozilla Developer Network CSS Reference (website), 622 Mozilla Developers Network JavaScript section (website), 621 MSDN JavaScript Language Reference (website), 620 multidimensional arrays, 97 Multi-level Push Menu plug-in, 249 multi-line comments (/*...*/), 58 multiple submissions of forms, stopping, 266 multiplication operator (*), 34–36 multiply and assign operator (*=), 39 N Nabors, Rachel, bringing together CSS3 animations and jQuery, 203 NaN value, 37 navigation bar, building responsive about, 241–242 controlling pop-up menus, 244 creating nested list, 242–244 placing navigation buttons, 244 tutorials for, 244–249 using jQuery SmartMenus plugin, 241–242,244 navigation bar, creating horizontal, 346–349 nesting arrays, 97 conditional statements, 73–74 lists, 243–244 Netscape Navigator, xiv new Date() function, JavaScript, 568,571,573–574 next() function, jQuery, 178,535 noConflict() function, jQuery, 522 node.js, xv,8 nodes, in DOM, 117 644 INDEX non-closed pairs, errors caused by, 587–591 Notepad, for programming JavaScript, xxii Notepad++, for programming JavaScript, xxii :not() filter, 125 not() function, jQuery, 230 NOT operator (!), 72 null values, 558 Number() function, JavaScript, 38– 39,563 numberOfMonths property, Datepicker widget, 353,354 numbers about, 562 as data types, 27 changing strings to, 562–563 combining with strings, 37–38 creating random numbers, 566–567 formatting currency values, 565–566 in variable names, 30 octal, 564 rounding numbers, 565 testing for, 564–565 number validation rules, for forms, 277 O object literals about, 135 as positioning property, 318 as values inside JSON, 479–482 sending data to server and, 465 separating name/value pairs in, 247,281 using with css() function, 135 widgets using, 578 objects about, 55–57 instances of, 56–57 putting preferences in, 577–578 string, 57 window, 57 octal numbers, 564 :odd filter, 125 off() function, jQuery, 166–168 offset category, onjQuery Docs Site, 529 <ol> tags, 427 on() function, jQuery about, 168–169 deleting tasks and, 513 format of, 168 using, 169–174 onload event, 159 opacity option Draggable widget, 405 Sortable widget, 431 openExt() function, JavaScript, 230 opening HTML tags, xvii open() method window object, 231–236 XHR, 453 Opera. See also error console, web browser debuggers, 604 viewing rendered HTML in, 132 order of operations, 35–36 OR operator (||), 71–72 out event Droppable widgets, 420 Sortable widget, 434 over event Droppable widgets, 419 Sortable widget, 434–435 P Packer, 585 page fragments, creating, 336 pageX property, event object, 165 pageY property, event object, 165 parameters, for user-defined functions, 89–91 parent() function, jQuery, 533–534 parentheses () identifying functions with, 26 in calling functions, 87 leaving off closing, 588–590 using to group mathematical operations, 36 parent values for Draggable widget containment option, 403 for Sortable widget containment option, 430 parseFloat() function, JavaScript, 564 parseInt() function, JavaScript, 563– 564 :password selector, 254 patterns, in strings about, 546–547 finding for dates, 555 for email addresses, 554–555 for phone numbers, 554 for web addresses, 556–557 for zip codes, 550,553 using indexOf() function, 543– 545,547,559 using match() function, 559 using regular expressions, 546– 552 using replace() function, 560–561 using search() function, 558 matching, 558–560 replacing text within, 560–561 percent sign (%), modulus operator represented by, 571–572 phone numbers, regular expressions for, 554 photo gallery with effects, tutorial, 220–225 photos, retrieving from Flickr Feed. See also images about, 484 constructing URL, 484–486 Flickr group, 489 getting Flickr ID, 485 maximum images retrieved, 493 tutorial for, 488–493 understanding Flickr JSON Feed, 487–488 pipe characters (||), as OR operator, 71–72 placeholder attribute, for forms, 260 placeholder object, in Sortable widget start event, 434 placeholder option, Sortable widget, 432 Play button, on debugger, 607,609 plug-ins about, 106 Firebug, 22 user interface, 302 plug-ins, jQuery. See also jQuery UI: widgets choosing, 237–239 jPanel, 249 Multi-level Push Menu, 249 PLUG-INS, JQUERY INDEX 645 PLUS SIGN (+) 646 object literals, 578 setting up, 239–241 SmartMenus, 241–242,244–245,247– 249 Validation about, 273–275 advanced validation using, 279– 286,289,294 basic validation using, 276– 279,287,292 keeping in external JavaScript file, 583 website for finding, 249 plus sign (+) as addition operator, 34–36 as concatenation operator, 36–38 on web pages, 179 pointer value, for Droppable widget tolerance option, 416 pop() function, JavaScript, 51–52 pop-up dialog boxes. See dialog boxes pop-up menus, controlling, 244,374 pop-up windows about, 235–236 testing, 233 position property Selectmenu widget, 363 setting dialog box, 311 tooltip widget, 323 position property, setting dialog box, 318 post() function, jQuery, 453,462– 466,471,476–477 pound sign (#), in ID selectors, 120 preloading images, 212–213,217 prepend() function, jQuery, 129– 130,475,506,523,537 preventDefault() function, jQuery, 165– 166,222,228,259,313,460 prev() function, jQuery, 535 The Principles of Object-Oriented JavaScript (Zakas), 622 processContacts() function, 481 processContacts() function, JavaScript, 478 processData() function, JavaScript, 474 programming about, 4–5 INDEX client side vs. server side, 8 reducing errors, 597 sliders, 236 programs, writing JavaScript about, 6–7 coding multiple lines, 81,270 errors in. See troubleshooting indenting code, 18,270 joining arrays and splitting strings, 582 putting preferences in objects, 577– 578 putting preferences in variables, 575–577 putting text for printing in variables, 577 reducing programming errors, 597 steps in writing, 94–95 switch statements in, 579–582 ternary operator in, 578–579 tracking down errors, 18–24. See also debugging techniques troubleshooting typing mistakes, 13,21,199 writing JavaScript hello world program, 12–14 progressive enhancement, 459 prompt() function, JavaScript, 43,76,562 property part, in declaration block, xxi protocol-relative URLs, 110 Prototype library, 522 <p> tags as opening paragraph tag, xviii as wrapped block-level element, 189 puff effect, jQuery UI, 441 pull quotes, adding to web page, 141– 145 pulsate effect, jQuery UI, 441 push() function, JavaScript, 49–50 Q querySelectorAll( ) function, JavaScript, 118 query strings, 463–465 queues, creating, 51 quote marks (“ “ or ‘ ‘) debugging errors using, 588–591 empty strings using, 43 enclosing strings with, 21,28 errors using, 588–591 escaping, 592 marking strings in JSON with, 477 R radio buttons disabling form, 269 improving, 366–368,383–384 selecting, 270 validating, 292–295 :radio selector, 254 random() function, JavaScript, 566– 567 random numbers, creating, 566–567 rangelength validation rules, for forms, 282 range validation rules, for forms, 282 Raphaël (library), 107 ready() function, jQuery, 156–158,160– 161. See also $(document).ready() function receive event, Sortable widget, 435 regular expressions (regex) about, 218,546–547 building, 548–552 case-sensitive searches using, 551– 552 characters for pattern-matching using, 548–549 creating, 547–548,553 for dates, 555 for email addresses, 554–555 for phone numbers, 554 for web addresses, 556–557 for zip codes, 550,553 grouping parts of patterns, 551–552 matching patterns, 558–560 replacing text with using replace() function, 560–561 using subpatterns, 561 searching for file extensions, 550– 551 trying out, 561–562 website library of, 553 remote panel content, tabs with, 335– 338 removeAttr() function, jQuery, 137– 138 removeClass() function, jQuery, 133,444 remove event, Sortable widget, 435 remove() function, jQuery, 130,225,514,537 rendered HTML, viewing, 132 rendering (layout) engine, in web browsers, 6–7 replace() function, jQuery, 493,560– 561 replaceWith() function, jQuery, 211– 212,537 required validation rules, for forms, 277 reserved words, using, 593 reset event, 151 :reset selector, 254 resizable property, setting dialog box, 309 resizeBy() method, window object, 235 resize event, window object, 150 resizeTo() method, window object, 235 return key word, JavaScript, 92 return (↵) symbol in code, 81,270 revertDuration option, Draggable widget, 406 revert option, Draggable widget, 405–406 Robson, Elisabeth, Head First HTML with CSS and XHTML, xvii Robson, Elisabeth, Head First JavaScript Programming, 620 rollover images, 213–220 root element, 471 root-relative path, URL, 11 round() function, JavaScript, 565 rules for JavaScript object literals, 281 for validating forms, 275–278,280– 284,289–292 runtime errors, 592 SAFARI S Safari error console, 199. See also error console, web browser about, 23–24 listing errors, 588–590 opening, 598 INDEX 647 SAFARI® BOOKS ONLINE 648 updating for Windows, 24 using load() function with, 459 viewing rendered HTML in, 132 Safari® Books Online, xxviii scale effect, jQuery UI, 310,441 scope, in functions, 93–95 scope option Draggable widget, 406–407 Droppable widget, 415 screenX property, event object, 165 screenY property, event object, 165 scripting languages vs. compiled, 5 scripts, finding online, xiv <script> tags about, 7–8 in both head and body of page, 76 scrollBy() method, window object, 235 scroll event, window object, 150 scrollTo() method, window object, 235 search() function, jQuery, 558 searching, strings, 543–545 selectmenu() function, jQuery, 361– 362,364,383 Selectmenu widget about, 360–361,383 performing action for selected option, 363–365 setting properties of, 362–363,383 using, 361–362 selector, in CSS style, xx selectors, CSS about, 119,122,526–527 adjacent sibling selectors, 123 append() function using with, 129 attribute selectors, 123–124 child selectors, 122–123 class, 131–132 class selectors, 121 descendent selectors, 122 element selectors, 121 filtering, 124–126,255 form, 254–255 html() function using with, 128–129 ID selectors, 120 optimizing, 525 prepend() function using with, 129– 130 removing or replacing selections, 130 INDEX specificity and, 393–394 text() function using with, 129 understanding, 126–127 website for finding, 121 selector values for Draggable widget containment option, 403 for Sortable widget containment option, 430 <select> tags, 252,255,361 Selectutorial (website), 622 semicolon (;) in chained jQuery functions, 127 in declaration part of declaration block, xxi in statements, 25–26 send() function, jQuery, 454 serialize() function, jQuery, 466 serialize() functions, jQuery, 436–437 servers. See also web servers, Ajax and application, 451 definition of, 451 development, 452 server-side client side vs., 8 programming to use Ajax, 455 validation of forms, 277,284 7-Zip utility, 11 shake effect, jQuery UI, 441–442 shift() function, JavaScript, 51–52 shiftKey property, event object, 165 show() function, jQuery, 184,228,265,504,510 show() functions, jQuery, 439 show property setting dialog box, 310 setting tabbed panels, 330 tooltip widget, 322 siblings() function, jQuery, 534–535 size effect, jQuery UI, 442 slice() function, jQuery, 545–546 slideDown() function, jQuery, 179– 180,186,247,272,511 slide effect, jQuery UI, 442 sliders (carousels), programming, 236 slideToggle() function, jQuery, 187,189–190 slideUp() function, jQuery, 180,186,272,510 SmartMenus plug-in, jQuery, 241– 242,244–245,247–249 snapMode option, Draggable widget, 407 snap option, Draggable widget, 407 snapTolerance option, Draggable widget, 408 software, for programming JavaScript, xxii–xxiii sortable() function, jQuery, 428–430 Sortable widgets about, 426 events, 432–435 functions in, 435–438 options for, 429–432 using, 427 sort event, Sortable widget, 434 source property, autocomplete() widget, 378 space characters, in JavaScript, 34 <span> tags, 502–503 specificity, in CSS, 393–394 split() function, jQuery, 582 src attribute changing image, 209–211 of <script> tag, 9 start event Draggable widget, 409–411 Sortable widget, 433–434 statements, JavaScript, 25–26 Stefanov, Stoyan, JavaScript Patterns, 622 Step Into button, debugger, 607–609 Step Out button, debugger, 608–609 Step Over button, debugger, 607,609 stop event Draggable widget, 411,423–424 Sortable widget, 432,434 stop() function, jQuery, 201–202 stopPropagation() function, jQuery, 167 strict equality operator (===), in conditional statements, 64 strict not equal to operator (!==), in conditional statements, 64 string objects, 57 strings about, 541 as data types, 27–28 changing case of, 542–543 changing to numbers, 562–563 concatenating, 36–38 determining length of, 541–542 enclosing with quote marks (‘ ‘ or “ “), 21,28 extracting part of, 545–546 finding patterns in about, 546–547 for dates, 555 for email addresses, 554–555 for phone numbers, 554 for web addresses, 556–557 for zip codes, 550,553 useful regular expressions, 553– 558 using indexOf() function, 543– 545,547,559 using match() function, 559 using regular expressions, 546– 552 using replace() function, 560–561 using search() function, 558 joining arrays and splitting, 582 marking in JSON, 477 matching patterns, 558–560 replacing text within, 560–561 searching, 543–545,558 working with, 541–546 style fixes, escaping float in, 348–349 styles (rules), CSS, xix–xxi <style> tags, formatting error messages using, 295 styling error messages, in validating forms, 285 SublimeText editor, for programming JavaScript, xxiii submit event, 151,258–259 :submit selector, 254 subpatterns, using to replace text, 561 subtract and assign operator (-=), 39 subtraction operator (-), 34–36 subtracts 1 from variable operator (--), 39 swing method, in easing animations, 193 switchClass() function, jQuery, 444 switch statements, 70,579–582 syntax about, 5 errors about, 592 debugging quote mark, 588–591 INDEX SYNTAX 649 TAB CHARACTERS, IN JAVASCRIPT missing closing punctuation marks, 588–590 fixing errors, 21 T tab characters, in JavaScript, 34 tabs, as component of Tabs widget, 327 tabs() function, jQuery, 329–330,332– 337 Tabs widget, adding about, 326–330 components of, 326–327 keyboard navigability of, 328 options for, 330–331 tutorials for, 331–334 with remote panel content, 335–338 tagmode, 486 tags about, 485 adding to URLs keyword of, 486 HTML, xvii–xviii target property, event object, 165 ternary operator, using in writing JavaScript, 578–579 <textarea> tags, 252 text color settings, in ThemeRoller, 388 TextEdit, for programming JavaScript, xxii text editors for programming JavaScript, xxii identifying errors in, 589 text() function, jQuery, 129,467,505,523,535 text property, Button widget, 368 :text selector, 254 TextWrangler software, for programming JavaScript, xxii ThemeRoller about, 385–387 adding to website new theme, 390– 391 categories in, 387–390 downloading and using new themes, 390–392 themes adding new themes to websites, 390–391 650 INDEX downloading and using new themes, 390–392 overriding jQuery UI styles, 392–397 this keyword, 139 $(this) variable applies to element receiving event, 179 getting hold of element with, 459 in referring to element that in event handler, 174–175,190 in referring to element that in loop, 217 in referring to element that is clicked, 171,223 in to-do list application, 513 in traversing the DOM, 531,534–535 referring to checkbox being clicked, 272 referring to page element with attached event, 199 referring to trashcan, 426 selecting list items, 509 this vs., 139–140 time. See also dates changing from 24-hour clock to 12hour clock, 571–572 dealing with time zones, 575 getting about, 569 functions for, 568,570–571 padding single digits, 572–573 times option, bounce effect, 440 toArray() functions, jQuery, 437–438 to-do list application, building about, 495–496 adding dialog box, 498–502 adding tasks, 502–513 as ongoing project, 517 buttons adding, 496–497,500–501 formatting, 500–501 naming, 500 confirming deletions, 516 deleting tasks, 513–515 editing tasks, 515 saving lists, 516–517 toFixed() function, jQuery, 257,566 toggleClass() function, jQuery, 133,190,205,444 toggle() function, jQuery, 164,184,189– 190,439 tolerance option, Droppable widget, 416–417,419 Toolbar category, in ThemeRoller, 388 tooltipClass property, tooltip widget, 323–324 tooltip() function, jQuery, 321,324 tooltip widget about, 321–322 adding, 322–323 adding HTML in, 324–327 mousing over, 324 options, 322–323 positioning boxes using, 318 providing information with, 321–325 touch value, for Droppable widget tolerance option, 416 track property, tooltip widget, 322 transitions class animations vs. CSS, 443 CSS3 and, 204–206 transversing DOM, 531–536 HTML elements, 527 triggering element, 318 troubleshooting. See also debugging, using console for; errors case-sensitivity, 594 functions disappearing, 596 logic errors, 592 paths of external JavaScript file, 594–596 reducing programming errors, 597 runtime errors, 592 syntax errors about, 592 debugging quote mark, 588–591 fixing, 21 leaving off closing brace, 589 missing closing punctuation marks, 588–590 typing mistakes in programs, 13,21,34,199 using error console in web browsers, 18–24 using reserved words, 593 variables disappearing, 596 true value, Boolean, 29,66,265 “truthy” values, 69 24-hour clock to 12-hour clock, changing time from, 571–572 typeof operator, 57 typing mistakes, troubleshooting programs for, 13,21,34,199 UTC (COORDINATED UNIVERSAL TIME) U ui parameters in drop event, 417,422 in selected menus, 364–365 in start event Draggable widget, 410–412 Sortable widget, 433–434 <ul> tags, 427–429 unbind() function, jQuery, 168 Uncaught SyntaxError, in Chrome JavaScript console, 21 Uncaught TypeError, in Chrome JavaScript console, 21 “undefined” values, JavaScript, 53 underscore (_) in variable names, 30 preceding name of folder, 155 Underscore.js, 107 underscore (_), preceding name of folder, 155 “Unexpected Token” message, in Chrome JavaScript console, 20–21 unload event, window object, 150 unshift() function, JavaScript, 49–50 “Unterminated string constant” message, in Internet Explorer browser, 21 “Unterminated string literal” message, in Firefox browser, 21 unwrap() function, jQuery, 539 update event, Sortable widget, 434 URL (Uniform Resource Locator) constructing for Flickr Feed, 484– 486 protocol-relative, 110 types of, 11 using query string in, 463 url validation rules, for forms, 277 user interface libraries, 302 User Interface Library, Yahoo, 107 UTC (Coordinated Universal Time), 575 INDEX 651 VAL() FUNCTION, JQUERY 652 V :visible filter, 126 val() function, jQuery, 159,253– 254,256,502 validate(), 276 validate() function, jQuery, 275– 276,280–285,289–292 validating forms about, 273–274 advanced, 279–286,289–296 basic, 276–279,287–289,292 checkboxes, 292–295 error messages, 275,278–279,283– 285,289–296 preventing malicious input, 277 radio buttons, 292–295 rules for, 275–278,280–284,289–292 server-side, 277,284 tutorials for, 286–296 Validation plug-in, jQuery about, 273–275 advanced validation using, 279– 286,289,294 basic validation using, 276– 279,287,292 keeping in external JavaScript file, 583 validity testing, using conditional statements, 66 value, in hyperlink, xviii value part, in declaration block, xxi variables about, 29–30 asking for information using, 42–44 assigning values within functions to, 95 changing values in, 38–40 concatenating, 36 creating, 30–32 creating messages using, 40–42 evt variable, 165 global, 94 local, 94 putting preferences in, 577 putting text for printing in, 577 saving selections into, 522–523 using, 32–33 working with, 33–40 variable scope, 94 var keyword, declaring variables using, 33 The W3 Schools JavaScript tutorial (website), 620 WAMP, 452 web addresses, regular expressions for, 556–557 web browsers. See also individual browsers adding new CSS properties, 205 Ajax and about, 449 XMLHttpRequest object feature, 452 animating CSS properties, 203 error console in. See also debugging, using console for listing errors, 588–591 tracking down errors, 18–24 troubleshooting typing mistakes, 199 handling events in, 152 handling of JavaScript, xiv–xv layout (rendering) engine in, 6–7 local storage feature, 516 testing pop-up windows, 233 using load() function with, 459 waiting for HTML to load, 160–162 window creating new, 231–236 opening external links to new, 229–231 web forms. See forms (web forms) web pages adding content to web pages, 127– 130,523–524 adding Draggable widget to, 400– 401 adding JavaScript to, 6–11 adding jQuery to, 112–113 adding jQuery UI to, 304–305 adding menus to, 343–349 adding messages with dialog boxes adding buttons to, 314–320 creating, 306–308 opening with events, 313–315 passing options to, 311–312 positioning, 318 setting properties of, 308–311 INDEX W adding pull quotes to, 141–145 adding styles (rules) to, xix–xxi adding tabbed panels about, 326–330 components of, 326–327 keyboard navigability of, 328 options for, 330 tutorials for, 331–334 with remote panel content, 335– 338 attaching external JavaScript files to, 15–18 creating fragments, 336 delaying JavaScript until HTML loads, 160–162 interactive, 147 layers of, xvi links controlling behavior of, 225–229 creating, xviii modifying, 113–115 representing nested structure of HTML, 118 retrieving photos from Flickr Feed about, 484 constructing URL, 484–486 getting Flickr ID, 485 maximum images retrieved, 493 retrieving photos from Flickr group, 489 tutorial for, 488–493 understanding Flickr JSON Feed, 487–488 using arrays for writing to, 51–55 using HTML tags, xvii–xviii validating, xix viewing rendered HTML in, 132 writitng text on, 14 WebPlatform.org (website), 619 web servers, Ajax and about, 451 processing data from, 466–469 receiving XML from, 471 responding to request in JSON, 477 saving lists in to-do list application, 517 setting up, 452 talking to, 452 using for formatting data to send to, 463–469 using get() function vs. post() function for submitting data to, 464 websites adding Flickr Feed to about, 484 constructing URL, 484–486 getting Flickr ID, 485 maximum images retrieved, 493 retrieving photos from Flickr group, 489 tutorial for, 488–493 understanding Flickr JSON Feed, 487–488 building responsive navigation bar for, 241–248 lightbox effect on, 168–169 which property, event object, 165 while loops, 78–80 widgets accordion components of, 338 saving space with, 338–343 setting properties of, 340–341 tutorials for creating, 338 adding html to a tooltip, 324 adding tabbed panels about, 326–330 keyboard navigability of, 328 options for, 330–331 tutorials for, 331–334 with remote panel content, 335– 338 autocomplete() about, 370–372,381 getting data from server, 376–378 setting properties of, 378–379 using arrays with, 372–374 button, 366–370,383–384 custom events, 335,337 Datepicker about, 351 setting colors or pattern to header in, 388 setting properties of, 353–357 tutorial for, 357–360,380–382 using, 352–353 Draggable about, 399–400 adding to web page, 400–401 INDEX WIDGETS 653 WIDGETS, JQUERY UI events, 408–410 options for, 402–409 Droppable about, 412 events, 416–420 options for, 414–417 tutorial for, 420,424–426 using, 413–414 jQuery UI styling, 395–397 Menu adding to web page, 343–349 creating horizontal navigation bar, 346–349 Selectmenu, 360–365,383 Sortable about, 426 events, 432–435 functions in, 435–438 options for, 429–432 using, 427 tooltip about, 321–322 adding, 322–323 adding HTML in, 324–327 options, 322–323 positioning boxes using, 318 providing information with, 321– 325 tutorials for form, 379–384 using object literals, 578 using ThemeRoller with, 385–390 widgets, jQuery UI Datepicker, 115,300 dialog about, 299–300 creating dialog box. See dialog boxes in to-do list application, 508 passing options to, 311–312 setting properties of, 308–311 using, 305–306 website for options of, 310 in jQWidgets, 302 interface, 115 in Wijmo UI, 302 positioning boxes using tooltip, 318 using Download Builder for choosing, 303 width of objects, functions for determining, 528 654 INDEX width property setting dialog box, 309–310 with Selectmenu widget, 362– 363,383 Wijmo UI, 302 window object (browser window) about, 57 creating new, 231–236 events for, 150 external link for opening new window, 229–231 properties of, 232–233 testing, 233 window values for Draggable widget containment option, 403 for Sortable widget containment option, 430 World Wide Web Consortium (W3C), free online validator, xix wrap() function, jQuery, 537–538 wrapInner() function, jQuery, 538 wrapping block-level elements, 189 write() function, JavaScript, 41,56,76,82 writing functions, JavaScript about, 84–86 calling functions, 87 giving information to functions, 89– 90 parameters for functions, 89–91 passing arguments, 89–90 returning values from functions, 91– 93 scope of functions, 93–95 tutorials for, 87–88,96–101 writing JavaScript about, 6–7 coding multiple lines, 81 errors in. See troubleshooting indenting code, 18,270 joining arrays and splitting strings, 582 putting preferences in objects, 577– 578 putting preferences in variables, 575–577 putting text for printing in variables, 577 reducing programming errors, 597 ZIP CODES, REGULAR EXPRESSIONS FOR steps in, 94–95 switch statements in, 579–582 ternary operator in, 578–579 tracking down errors, 18–24 troubleshooting typing mistakes, 13,199 X XHR (XMLHttpRequest) object about, 449 creating instance of, 452 open() method, 453 sending off request to server using, 466,472 send() method, 454 XHTML, xvii adding checked attribute to form, 257 XHTML editor, xxii–xxiii XML receiving from web server, 471 sending information to server using, 466 XMLHttpRequest (XHR) object, about, 449 creating instance of, 452 open() method, 453 sending off request to server using, 466,472 send() method, 454 Y Yahoo JavaScript compressor, 585– 586 Yahoo User Interface Library, 107 yearRange property, Datepicker widget, 356 Yosemite (Mac OS X) operating system, using JavaScript, xv Z Zaefferer, Jörn, Validation plug-in created by, 273–275 Zakas, Nichola, The Principles of Object-Oriented JavaScript, 622 zero-indexing, 47 zIndex option, Draggable widget, 408,423–424 zip codes, regular expressions for, 550,553 INDEX 655 TH JavaScript & jQuery E NG CD I S S MI no ’s There ook; b s i . ith th w 5.00 D $ C d e t sav s u j you nd file, a e c i t prac this ress, ed in d n d o i a t n Web e me com ingle e softwar s uals. n y r a e l v m b ada sing ad, e n). Inste of downlo ble at mis D ico ks, C a l e i g c a n n pie issi is av t of li book click the M a tidy lis ( ter. l find chap you’l y b e r d e Th ize organ </pre><hr>Source Exif Data: <br /><pre>File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : Yes Author : McFarland, David Sawyer Create Date : 2014:10:10 08:48:17Z EBX PUBLISHER : O'Reilly Media Modify Date : 2014:10:10 13:48:51+01:00 Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26 Format : application/pdf Creator : McFarland, David Sawyer Title : JavaScript & JQuery: The Missing Manual Creator Tool : Adobe InDesign CS6 (Macintosh) Metadata Date : 2014:10:10 13:48:51+01:00 Producer : Adobe PDF Library 10.0.1 Trapped : False Ebx Publisher : O'Reilly Media Document ID : uuid:380a64cf-7abe-459d-b140-12b9a32076e2 Instance ID : uuid:6f37ddd0-24ba-4f1b-956d-d905d2fdbad9 Page Layout : SinglePage Page Mode : UseNone Page Count : 686 </pre> <small>EXIF Metadata provided by <a href="https://exif.tools/">EXIF.tools</a></small> <div id="ezoic-pub-ad-placeholder-110"> <script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> <!-- usermanual link ad --> <ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-0545639743190253" data-ad-slot="6172135303" data-ad-format="link"></ins> <script> (adsbygoogle = window.adsbygoogle || []).push({}); </script> </div> </div> <div id="catlinks" class="catlinks catlinks-allhidden" data-mw="interface"></div> <div class="visualClear"></div> </div> </div> <div id="mw-navigation"> <h2>Navigation menu</h2> <div id="mw-head"> <div id="p-personal" role="navigation" class="" aria-labelledby="p-personal-label"> <!-- <div id="p-search" role="search"> <form action="https://usermanual.wiki/search.php" id="searchform"> <div id="simpleSearch"> <input type="search" name="search" placeholder="Search UserManual.wiki" title="Search UserManual.wiki [ctrl-option-f]" accesskey="f" id="searchInput" tabindex="1" autocomplete="off"><input type="hidden" value="Special:Search" name="title"><input type="submit" name="go" value="Go" title="Find a User Manual" id="searchButton" class="searchButton"> </div> </form> </div>--> <ul> <li id="pt-mycontris"><a href="https://usermanual.wiki/upload" title="Upload User Manual" accesskey="y">Upload a User Manual</a></li> </ul> </div> <div id="left-navigation"> <div id="p-namespaces" role="navigation" class="vectorTabs" aria-labelledby="p-namespaces-label"> <h3 id="p-namespaces-label">Versions of this User Manual:</h3> <ul> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/JavaScriptandjQueryTheMissingManual3rdEdition5bA45d.518186687" title="User Manual Wiki" accesskey="c">Wiki Guide</a></span></li> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/JavaScriptandjQueryTheMissingManual3rdEdition5bA45d.518186687/html" title="HTML" accesskey="c">HTML</a></span></li> <li id="ca-nstab-main" class="selected" ><span><a href="https://usermanual.wiki/Document/JavaScriptandjQueryTheMissingManual3rdEdition5bA45d.518186687/help" title="Discussion / FAQ / Help" accesskey="c">Download & Help</a></span></li> </ul> </div> </div> <div id="right-navigation"> <div id="p-views" role="navigation" class="vectorTabs" aria-labelledby="p-views-label"> <h3 id="p-views-label">Views</h3> <ul> <li id="ca-view"><span><a href="#">User Manual</a></span></li> <li class="selected" id="ca-edit"><span><a href="https://usermanual.wiki/Document/JavaScriptandjQueryTheMissingManual3rdEdition5bA45d.518186687/help" title="Ask a question" accesskey="e">Discussion / Help</a></span></li> </ul> </div> </div> </div> <div id="mw-panel"> <div id="p-logo" role="banner"><a class="mw-wiki-logo" href="https://usermanual.wiki/Main_Page" title="Visit the main page"></a></div> <div class="portal" role="navigation" id="p-navigation" aria-labelledby="p-navigation-label"> <h3 id="p-navigation-label">Navigation</h3> </div> <div class="portal" role="navigation" id="p-tb" aria-labelledby="p-tb-label"> </div> </div> </div> <div id="footer" role="contentinfo"> <ul id="footer-info"> <li id="footer-info-lastmod">© 2025 UserManual.wiki</li> </ul> <ul id="footer-places"> <li id="footer-places-privacy"><a href="https://usermanual.wiki/ContactUs" title="UserManual.wiki:Contact Us">Contact Us</a></li> <li id="footer-places-about"><a href="https://usermanual.wiki/DMCA" title="UserManual.wiki:DMCA">DMCA</a></li> </ul> <ul id="footer-icons" class="noprint"> <li id="footer-poweredbyico"> </li> </ul> </div> </div></body></html> </textarea></td></tr></tbody></table></li></ul></li></ul></li></ul></li></ul></li></ul></li></ul></li></div></div></div></div></div></div></div></a></div></a></div></div></div></h1></div></h1></ul></h2></h1></pre></div></div></div></body></html> - tag to the second panel, and so on. In order to make these links work, you need to add the matching IDs to the panel divs. 4. Locate the
you just
edited. For each tag, add a # link like this: