Prototype: Easing AJAX's Pain (1) - Web Planet

This article describes Prototype, an open source JavaScript library to create an object for an AJAX application. I explain how to use Prototype by describing an environmentally oriented web application that displays an annual atmospheric carbon dioxide (CO2) level. First, I will discuss Prototype's benefits and describe how to set up Prototype in your application. Second, I will delve into the nitty-gritty of how this application puts the library to good practical use.

Why Prototype?

Why didn't I just create a plain old JavaScript object (POJO) for my application, instead of introducing an open source library? For one, Prototype includes a nifty collection of JavaScript shortcuts that reduce typing and help avoid the reinvention of the wheel. The commonly touted shortcut is $("mydiv"), which is a Prototype function that returns a Document Object Model (DOM) Element associated with the HTML tag with id "mydiv". That sort of concision alone is probably worth the cost of setting up Prototype. It's the equivalent of:

document.getElementById("mydiv");

Another useful Prototype shortcut is $F("mySelect"), for returning the value of an HTML form element on a web page, such as a selection list. Once you get used to Prototype's austere, Perlish syntax, you will use these shortcuts all the time. Prototype also contains numerous custom objects, methods, and extensions to built-in JavaScript objects, such as the Enumeration and Hash objects (which I discuss below).

Finally, Prototype also wraps the functionality of XMLHttpRequest with its own Ajax.Request and related objects, so that you don't have to bother with writing code for instantiating this object for various browsers.

Setting Up

So how do you set up Prototype? First, download it from prototype.conio.net. Prototype is open source and available under an MIT-style license. The download includes a file named prototype.js. This is a JavaScript file that defines the various functions and objects your application will use. Add the prototype.js file to your application by using a script tag in the HTML code.

<head>...
<script src="js/prototype.js" type="text/javascript">
</script>
<script src="js/co2.js" type="text/javascript">
</script>
<script src="js/eevpapp.js" type="text/javascript">
</script>...
</head>

The same directory that holds this application's HTML file contains a directory named js. This js directory contains prototype.js, an object definition in the file co2.js, which this article describes, as well as the rest of the application's client-side code in another file: eevapp.js.

Since the application imports the Prototype file, the JavaScript code in the other imported .js files can use Prototype's objects and extensions as if they were declared and defined locally. JavaScript does not require statements such as import or require to use objects from other JavaScript files that the browser commonly imports.

Climate Change

How is Prototype going to help with our application's requirements? What are the requirements?

The User Interface is a web browser, such as Safari 1.3, Firefox 1.5, Opera 8.5, or Internet Explorer 6. The application is designed to display a small data set of annual atmospheric carbon dioxide (CO2) levels. This is a number, like 377, that represents the parts-per-million CO2 level in the air for a specific year. I decided to store these years and numbers in a JavaScript object that the browser downloads with the application. It is not necessary to use a database to store this data, which is small in size and needs neither security nor authentication. The data is designed for consumption by the interested public. The application does, however, give this JavaScript object the ability to add new data on the fly when necessary.

CO2 Applet

Figure 1-1 shows the browser screen for the application. In the upper left corner is an applet that displays the CO2 level in the atmosphere when the user chooses a year.

Figure 1-1. The select tag shows CO2 level--click for full-size image.

This data is derived from the Mauna Loa Observatory, run by the U.S. government in Hawaii. The measurements are taken at high altitude in pristine conditions. Scientists throughout the world use the data in their climate-change research.

There are only 46 different annual levels, associated with the years 1959-2004 (the 2005 level is not available at this time). Therefore, it makes sense to store this information in a JavaScript object. Even if we choose to display the monthly levels associated with those years with this tool (over 500 separate numbers), it still might make sense to store the data on the client. No database or extra server hits are required.

Where Prototype Comes In

The eevapp.js file contains the code that executes when the user selects a year in the selection list widget.

//instantiate an object 
//defined in the co2.js file 
var co2lev = new CO2Levels();
//the onload event handler executes
//when the browser is finished loading the page.
window.onload=function(){
 
$("co2_select").onchange=function(){
    $("co2ppm").innerHTML= 
    co2lev.getYear($F("co2_select")); 
    }

};

The value "co2_select" is the id value of the selection list that the user clicks to choose a year.

<select id="co2_select" .../>

The code:

 $("co2_select")

returns a DOM Element reference, the equivalent of document.getElementById("co2_select");.

The code sets the onchange event-handler attribute of the selection list element to a JavaScript function, as in: $("co2_select").onchange=function(){...}.

In simpler terms, when the user chooses a year in the select tag, the browser executes the defined function. What does this function do? The function gets a reference to an HTML div element with the id "co2ppm", once again, using Prototype's shortcut. The innerHTML property of this div element, representing what the user sees in the browser, is set to the return value of a method call:

co2lev.getYear($F("co2_select"));

The object named co2lev is instantiated at the top level of the eevapp.js file.

var co2lev = new CO2Levels();

This object has a method called getYear(). This method takes a string representing a year as a parameter, such as "1999". The method returns the CO2 level associated with that year.

Pithy Syntax

That dollar sign pops up in the syntax again: $F("co2_select"). The $F() Prototype function returns the value of an HTML form element, in this case the selection list, when I pass its id into the method as a parameter. The application uses this function to change the displayed CO2 level each time a user chooses a different year.

One tip to remember with $F(): it won't return a value from a selection list unless the list's child option elements have value attributes, as in: <option value="1959">1959</option>. In other words, at least the Prototype version I was using (1.4.0) would not return a value with $F() if I left out the value="..." part.