Script.aculo.us Controls: Do Your Web Users a Favor : Page 4

Implementing a Custom Autocompleter
As previously discussed, the problem with the Ajax-based autocompleter is that it expects an unordered list (<ul>) as a server response. The scenario in this section demonstrates how to implement an autocompleter that lets you handle any type of response. In this scenario, I intercept the server response—before passing it to the Script.aculo.us function that updates the list—and pass it to a callback function defined among the options passed to the autocompleter constructor.

The client code implements such a callback function in order to parse the response (XML, JSON or whatever) and build a <ul> block that will be passed to the Script.aculo.us updateChoices function, which will update the list. I called this autocompleter Ajax.Autocompleter.Custom. Here is its implementation:

Ajax.Autocompleter.Custom = Class.create(Ajax.Autocompleter, {
  initialize: function(element, update, url, options) {
    this.baseInitialize(element, update, options);
    this.options.asynchronous  = true;
    this.options.onComplete    = this.onComplete.bind(this);
    this.options.defaultParams = this.options.parameters || null;
    this.url                   = url;
    this.options.responseProcessor = this.options.responseProcessor || Prototype.K;
  },

  onComplete: function(request) {
       var htmlUL = this.options.responseProcessor(request.responseText, this.element);
     if(htmlUL)
     {
       this.updateChoices(htmlUL);
     }
  }
});

The only part I changed with respect to the default Ajax.Autocompleter implementation is the definition of a further parameter, responseProcessor, and the redefinition of onComplete. The responseProcessor parameter must be a callback function that expects two parameters:

• The server response
• The element to which the autocompleter is associated (You won't use this parameter very often in your callback functions.)

I redefined onComplete to intercept the call to updateChoices so that the callback function defined by the client code can process the server response and prepare the correct string expected by updateChoices. Listing 3 provides an example that uses this brand-new autocompleter (you can find the full code in the source code archive for this article).

As you can see, using the custom autocompleter is pretty simple. You create an instance of its class and pass a callback function among its parameters. In the previous example, this function is jsonResponseProcessor and it handles the JSON response format. You can easily implement a callback function that parses an XML response in much the same way. It's up to you to define the correct response processor, provided that the output of your callback function is always a string representing a <ul> block.

Using In-Place Editors
An in-place editor basically is a <div> containing text that a user can edit by clicking on it. The actors involved in such a control are:

• An instance of the Ajax.InPlaceEditor class
• A server-side component that receives the edited text and processes it (stores it in a database, sends it through e-mail, and so on)

Listing 4 provides an example that creates a very simple in-place editor.

The server component, namely editor-test.php, just takes the edited text and echoes it to the client again. Figure 3 and Figure 4 show the initial state of the editor and how it looks after the user clicks on the text, respectively.

Figure 3. In-place Editor Initial State: Here is the initial state of the editor.

Figure 4. In-place Editor State, After the User Clicks on Its Text: Here is how the editor looks after the user clicks on the text.

As the above code shows, creating an in-place editor is a piece of cake using Script.aculo.us. You just need to build an instance of Ajax.InPlaceEditor and pass it the following three parameters:

• The <div> ID
• The URL of the server component that processes the text
• The ubiquitous literal object containing the options for customizing the editor

Table 3 shows the most used options for the in-place editor.

Table 3. In-place Editor Customization Options

Option	Description
okText	This property is the text to use for the OK button.
cancelText	This property is the text to use for the Cancel link.
savingText	This property is the text displayed while the saving action is in progress. It defaults to "Saving...".
rows	This property is the number of rows to use for the text field. If greater than 1, it is rendered as a text area. It defaults to 1.
cols	This property is the number of columns to use.
size	This property is the same as cols, but it applies when rows is 1.
onComplete	This property is the callback function to call in case of a successful update.
onFailure	This property is the callback function to call in case of failure.

Previous Page

Next Page