The 80 percent rule: As an informal corollary to the famous 80/20 rule, Prototype pledges to solve the common problems that are shared by the vast majority of devel- opers. Proposed additions to the framework need to demonstrate widespread need. But the common 80 percent shouldn’t exclude the unique 20 percent, either— Prototype is designed to be easily extensible and customizable. Self-documenting code: In the README file of Prototype 1.0, Sam Stephenson states, “Prototype is embarrassingly lacking in documentation.” In lieu of providing plain English documentation, Sam did the next best thing: he made the code itself easy to read and understand. These days, Prototype enjoys exhaustive documentation, both official and unofficial. But readability, intuitive naming schemes, and cleanliness are still virtues of Prototype’s source code. Prototype’s Purpose and Scope Prototype is all about the abstract rather than the concrete. It isn’t a widget toolkit, or a graphing library, or a form validation utility—but all these things can be built atop Prototype. Most famously, script.aculo.us (which we’ll cover in Part 2) uses Prototype as a basis for a rich library of effects and UI controls. Many JavaScript toolkits, script.aculo.us included, allow you to do complex things without knowing much JavaScript. That’s not what Prototype is for. If you don’t want to get elbow-deep in JavaScript development, you won’t like Prototype very much. Prototype’s Web Site You can get Prototype, learn more about it, and read current project news at Prototype’s web site, at www.prototypejs.org/. You’ll also learn where to go if you get stuck, how to contribute to Prototype, and who uses Prototype in the real world. Prototype’s download page always features the latest stable version, plus instructions on how to build a bleeding-edge version if you’re feeling particularly daring. Contributing to Prototype Prototype is an open source project that bears the MIT License. In other words, do what- ever you like with the code and use it wherever you please, as long as you give credit. “Giving credit” is done automatically—at the top of the source code is a long comment describing the framework and its authors. Like other open source projects, Prototype relies heavily on the developer commu- nity. Bug reports and patches are enthusiastically welcomed. The code itself lies in the CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM 11 Ruby on Rails Subversion repository; you can browse the source code and the outstand- ing issues at http://dev.rubyonrails.org/. Proposed additions to Prototype are discussed on the Prototype Core mailing list. Instructions for joining this list can be found on Prototype’s web site. Getting Started with Prototype Prototype can be thought of as a JavaScript supplement. Most languages have a “stan- dard library” of code that simplifies common tasks. For instance, Ruby developers can use require 'rexml' to help with XML parsing, and Python developers can use import gzip to enable gzip compression in their scripts. Similarly, you can include Prototype on a web page by loading the prototype.js script near the beginning of the file. So let’s try it out. Creating a Page First, create an empty folder to hold your HTML and JavaScript files. Using your favorite text editor, create a boilerplate HTML file like so: <!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> </head> <body> <h1>Blank Page</h1> </body> </html> Not all that interesting, but it suits our needs. Save this file as index.html. Downloading Prototype Fire up a web browser and go to http://prototypejs.org/. Here you’ll see an overview of the Prototype library and a prominent Download link. Click the link, and then click the green box to get the latest version of Prototype (version 1.6.0.1 at press time). You should see a page that looks like Figure 1-1. CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM12 Figure 1-1. The download page on Prototype’s web site Clicking the link will likely take you to a page full of JavaScript code. This is Proto- type. You can save a copy of this file through the File menu; you can also select all the text and paste it into an empty text file. Either way, save the file as prototype.js in the same directory in which you placed index.html. Including Prototype To load Prototype into the page environment, you need to include a script tag. Add the following line to index.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" /> <script type="text/javascript" src="prototype.js"></script> <title>Blank Page</title> </head> CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM 13 <body> <h1>Blank Page</h1> </body> </html> Keep a few things in mind about script tags: • You can include JavaScript on a page directly with the script tag, but it’s usually a better idea to place your code in a file that gets loaded onto the page with the src attribute instead. It makes the code more portable. • Scripts are evaluated in the order in which they occur in the page. For this reason, any scripts you write that rely on Prototype must be included after prototype.js is loaded. For this reason, try to ensure that prototype.js is the very first script loaded on any page. • We’re placing this script tag in the head of the HTML, the same place we’d put style sheets and define other page metadata. Because the code is evaluated as soon as it’s parsed, it’s a bad idea for scripts you include to take immediate action, since they’d be acting on a document that’s only partially rendered. Instead, have your scripts define functions, and then set up those functions to run on page load or as the result of user action. Testing It Out Before you take a look at this page, make sure you’ve installed Mozilla Firefox and the Firebug extension. If you haven’t, you can visit two easy-to-remember URLs: http:// getfirefox.com and http://getfirebug.com. Both tools are free, easy to install, and avail- able on all major platforms. Save index.html, and then open it in Firefox. (You can simply drag the file into a browser window, if you like.) It won’t look like much, but since you’ve included Prototype on this page, you can use it as a playground. Click the icon at the bottom-right side of the screen; it should be a green circle with a check box. (If it’s a gray circle, you should click it and select “Enable Firebug for local files.”) Firebug will pop up a windowpane with several tabs. The one you’re interested in right now is Console; it acts as a JavaScript shell, letting you run code in the context of the current page (see Figure 1-2). CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM14 Figure 1-2. Firebug lets you run code interactively on the current page. Let’s try a couple of statements. Type in Prototype, then press Enter (see Figure 1-3). Figure 1-3. The Prototype object in Firebug The Prototype library defines a global object called Prototype, which holds metadata about the library itself. The most reliable way to determine whether the Prototype library has been loaded into a page is to check the type of the Prototype object; if it hasn’t been defined on the page, then the type will be undefined. A library that depends on Prototype might do something like this: // raise an error if Prototype isn't loaded if (typeof Prototype === "undefined") { throw new Error("This script relies on the Prototype JavaScript framework."); } CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM 15 You’ll notice that one of the properties is called Version. Type in Prototype.Version and press Enter (see Figure 1-4). Figure 1-4. The version number of Prototype in string form Naturally, Prototype.Version refers to the version of the library that’s been loaded onto the page. A lot of the code we’ll be writing in this book won’t work in versions of Prototype prior to 1.6. Many libraries, script.aculo.us among them, check this property and raise a helpful error message if the included Prototype version is too old. Summary We’ve just completed a high-level overview of JavaScript, the browser environment, and the Prototype project. Now we’re ready to jump headfirst into the code. On the other side of this chapter break, we’ll pick back up with a quick survey of the most important Proto- type functions and methods. CHAPTER 1 ■ WHAT YOU SHOULD KNOW ABOUT PROTOTYPE, JAVASCRIPT, AND THE DOM16 . atop Prototype. Most famously, script .aculo. us (which we’ll cover in Part 2) uses Prototype as a basis for a rich library of effects and UI controls. Many JavaScript toolkits, script .aculo. us included,. to read and understand. These days, Prototype enjoys exhaustive documentation, both official and unofficial. But readability, intuitive naming schemes, and cleanliness are still virtues of Prototype s. project news at Prototype s web site, at www.prototypejs.org/. You’ll also learn where to go if you get stuck, how to contribute to Prototype, and who uses Prototype in the real world. Prototype s