The Prototype JavaScript Framework / Page 2

The Prototype JavaScript Framework [con't]

Prototype's Ajax Object

Prototype houses all Ajax functionality in the global Ajax object. The Ajax xmlHttpRequest object is represented by the transport variable, with browser differences safely abstracted from the user. Requests are made by creating instances of the Ajax.Request object:

The first parameter is the URL of the request. The second is a JSON object literal which can contain a number of options. The method option provided above refers to the HTTP method to be used; the default method is POST.

You can pass parameters to the page using the parameters option. One of the primary applications for the parameters property is sending the contents of a form. Prototype has a handy function for this, called [form field].serialize(). The authors of the Prototype Framework replaced the need to check the loading status of the response by replacing each with its own event. The main ones are onSuccess and onFail. Others include: onUninitialized, onLoading, onLoaded, onInteractive, onComplete and onException. Here's a more complete version of the function above that performs a search based on the value of the search_field:

Prototype will handle the AJAX response differently depending on the header type. For instance, if the response holds a X-JSON header, its content will be parsed, saved as an object and sent to the callbacks as the second argument:

JSON Utilities

Prototype added JSON encoding and parsing support in version 1.5.1. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It's used by APIs all over the Web and is a fast alternative to XML in Ajax requests. You can read more about JSON in my Introduction to JSON article.

JSON Encoding

The vast majority of the time, the static Object.toJSON( Object obj ) method can be called to convert your JavaScript objects to their JSON counterparts:

You can also invoke the toJSON() method on Number, String, Array, Hash, and Date data types:

Overriding the `toJSON()` Method

There may be times when you'd like to use your own encoding function instead of toJSON(). The Prototype framework provides a way to override the toJSON() method. All you have to do is create a function of the same name in your class:

Associating Your Custom `toJSON()` Method with HTML Elements

You can link custom toJSON() methods to specific HTML elements by using the Element.addMethods() function. Here's an example of JavaScipt code that converts the value of a text field to a JSON-formatted name/value pair:

Parsing JSON Strings

The Prototype Framework provides a String method called evalJSON( [boolean sanitize] ) to take care of converting JSON strings to JavaScript objects. Always supply the optional sanitize parameter with a value of true when your JSON data is coming from an untrusted source, which would include any external or user-created content. It checks the string for possible malicious attempts, prevents the evaluation, and throws a SyntaxError if one is detected.

Parsing a JSON String from an AJAX Response

JSON's light weight and compatibility with JavaScript makes it an ideal choice for AJAX data transfers. As the example below demonstrates, extracting the data from an AJAX response is straightforward. To convert the JSON string to a proper JavaScript object, call the evalJSON() method on the transport.responseText property. To make the sanitize parameter easy to recognize, the example below employs a constant, which were introduced in JavaScript 1.5:

[previous] [next]