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:
