The lib folder contains a copy of Prototype, just in case you don’t have it already. We’ll stick with the one we’ve already got; oftentimes the version bundled with script.aculo.us is a little behind the stand-alone version. But the latest script.aculo.us and the latest Prototype, each fetched from its respective web site, are guaranteed to work together. The src folder contains the files we’re interested in: • scriptaculous.js is the main file, the one that declares the script.aculo.us version number and ensures that Prototype is already loaded. • effects.js provides animations and advanced UI flourishes. • dragdrop.js provides drag-and-drop support—the ability to define certain ele- ments on a page as “draggables” that can be dropped onto other elements. • controls.js provides several advanced UI controls, among them an auto- completer (a text field that offers suggestions as you type) and an in-place editor (allowing a user to view and edit content on the same page). • slider.js provides a scrollbar-like “slider”—a button that a user can drag to any point along a track. • sound.js provides a simple API for playing sounds on a web page. • builder.js is a utility file for DOM element creation. Because none of the afore- mentioned scripts rely on it and it provides no end-user functionality, we won’t be covering this part. • unittest.js is a utility file that’s used for script.aculo.us unit tests. Speaking of unit tests, the test folder contains a bunch of unit and functional (automated and manual) tests. These tests assert that script.aculo.us does what it claims to do in a cross-browser manner. We won’t be bothering with this folder either. Loading script.aculo.us on a Page There are several ways to load script.aculo.us into a web page. All of them begin the same way that Prototype is loaded. First, as in Chapter 1, create a boilerplate index.html file, and include a script tag that references prototype.js: CHAPTER 9 ■ WHAT YOU SHOULD KNOW ABOUT DHTML AND SCRIPT.ACULO.US210 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>Blank Page</title> <script type="text/javascript" </head> <body> <h1>Blank Page</h1> </body> </html> To include script.aculo.us, you’ll need to copy the contents of the src folder into the folder where index.html resides. For this example, your JavaScript and HTML code all lives in the same place. It doesn’t have to, of course; just make sure that all the script.aculo.us files reside in the same directory. Treat them as one unit. Once you’ve copied the files over, include a reference to scriptaculous.js in your HTML: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>Blank Page</title> <script type="text/javascript" src="prototype.js"></script> <script type="text/javascript" src="scriptaculous.js"></script> </head> <body> <h1>Blank Page</h1> </body> </html> CHAPTER 9 ■ WHAT YOU SHOULD KNOW ABOUT DHTML AND SCRIPT.ACULO.US 211 You’re done. The file you included, scriptaculous.js, inserts references to the other files ( builder.js, effects.js, dragdrop.js, controls.js, slider.js, and sound.js) into your document dynamically. In other words, script.aculo.us loads every module by default. If there are certain modules you don’t need, you can leave them out by explicitly stating which modules you want to load: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>Blank Page</title> <script type="text/javascript" <script type="text/javascript" src="scriptaculous.js?load=effects,dragdrop"></script> </head> <body> <h1>Blank Page</h1> </body> </html> The query string at the end of the URL should contain a comma-separated list of the modules you want to load. Loading these script.aculo.us modules through one central script is helpful to you, the developer; among other things, it verifies that your versions of Prototype and script.aculo.us are compatible with one another. When your site goes live, however, it’s a good idea to reference the modules you need directly. A standard Ruby on Rails application uses a subset of script.aculo.us and references the modules by name: <script type="text/javascript" src="/javascripts/prototype.js"></script> <script type="text/javascript" src="/javascripts/effects.js"></script> <script type="text/javascript" src="/javascripts/dragdrop.js"></script> CHAPTER 9 ■ WHAT YOU SHOULD KNOW ABOUT DHTML AND SCRIPT.ACULO.US212 Summary Part 1 of this book dealt in the abstract, but Part 2 will be concrete and hands-on. You’ll build a site from scratch, using Prototype and script.aculo.us to ensure a rich, intuitive UI model. Because script.aculo.us is so rooted in Prototype, you’ll recognize some methods and classes along the way, and you’ll even notice how groundwork laid by Prototype enables a specific feature of script.aculo.us. In other words, Part 2 isn’t separate and distinct from Part 1; it’s an application of what you’ve already learned. Feel free to jump back to Part 1 whenever you need a refresher on how a certain aspect of Prototype works. CHAPTER 9 ■ WHAT YOU SHOULD KNOW ABOUT DHTML AND SCRIPT.ACULO.US 213 Introduction to script.aculo.us Effects What Are Effects? Bear with me for the next few pages. I’m going to introduce a lot of terms that, while general, are used in script.aculo.us in very specific ways. In script.aculo.us, an effect is the modification, over time, of any aspect of an element. For an animation of any sort, you need three things: • The target of the animation: an element • Starting and ending points: typically integers, like pixel values • A way to get from beginning to end incrementally: a function All the effects in script.aculo.us—and any custom effects you create on your own— consist of these three things. For example, I can make an element move across the page by positioning it absolutely and then changing its left CSS property little by little. To describe the effect, I’d need to identify the element I want moved, figure out starting and ending values, and then explain how to apply those values to the left property. More abstractly, some effects can be seen as time-lapse versions of other transforma- tions. Instead of simply hiding an element (by calling Element#hide on it), I can call a “fade” effect, which hides the element over time by gradually decreasing its opacity. Why Effects? I can hear the mob outside my door. Don’t waste our time and patience with superfluous animations! Surely you’re not suggesting we take our design cues from 30-second Flash intros so ubiquitous that even the dog catcher’s campaign site includes one? Extinguish your torches. Put down your pitchforks. Let me explain. Animations and effects are not the same thing. Effects are well established in the desktop world. When you minimize a window, Windows will show the window collapsing 215 CHAPTER 10 into its title bar and then shrinking into its slot in the task bar. Mac OS X will show the window getting sucked, genie-like, into its reserved space in the dock. These animated effects are meant to reinforce the result of an action. They’re not Disney-esque pixie dust following your mouse pointer or window frames pulsating to the tempo of techno music. For our purposes, we can divide animations into two groups: the purposeful and the superfluous. A window that shrinks when minimized belongs to the former group. It’s friendly because it serves as a guide that reinforces the action. It illustrates that the win- dow has assumed a different form. Effects are designed to attract the user’s attention, so be sure to use them only when the user’s attention is needed. Constantly calling attention to mundane things is a great way to annoy people. (“Look! There’s a wastebasket!”) Don’t be that guy. But the point remains—there are legitimate use cases for animated effects in your web app. Don’t avoid all effects; avoid gratuitous effects. When Effects Are Good Effects in web apps grab the user’s attention, so your application should embrace effects as a way to mark what’s important. Here are a handful of good reasons to use effects in your web app: To show motion: Many applications employ some sort of spatial metaphor—a user can move things around on the page. A “to-do list” application might organize items into two sections, “completed” and “not yet completed”; checking a box would move an item from the latter into the former. Without a reinforcing effect, this action could startle the user. It’s important to show that the item hasn’t disappeared outright. The obvious way to express this is through actual motion—the item moves in a straight line from its original spot to its destination—but other effects can be used, as well. To alert the user of new content: As web apps move toward a single-page model, in which all content is fetched through Ajax instead of through traditional page loads, it becomes more important to show the user when things change on the page. Imagine a news reader application that fetches headlines from major sites. When new head- lines get added to the page, they’ll more easily be noticed if they fade in. If, on the other hand, they suddenly appear on the page, the user may not notice unless he’s looking at the screen at that very instant. To show what’s changed on a page: A similar (but slightly different) use case is alerting the user when e xisting content changes . CHAPTER 10 ■ INTRODUCTION TO SCRIPT.ACULO.US EFFECTS216 . DHTML AND SCRIPT .ACULO. US2 12 Summary Part 1 of this book dealt in the abstract, but Part 2 will be concrete and hands-on. You’ll build a site from scratch, using Prototype and script .aculo. us to. Because none of the afore- mentioned scripts rely on it and it provides no end-user functionality, we won’t be covering this part. • unittest.js is a utility file that’s used for script .aculo. us. intuitive UI model. Because script .aculo. us is so rooted in Prototype, you’ll recognize some methods and classes along the way, and you’ll even notice how groundwork laid by Prototype enables a specific