Previous Page
Next Page

Hack 63. Integrate script.aculo.us Visual Effects with an Ajax Application

Include an impressive array of special effects with your Ajax application.

script.aculo.us includes a variety of special effects and custom controls developers can use to enliven their Ajax applications or just to give them the advanced capabilities users have come to expect from desktop applications. It also has some built-in Ajax features that use Prototype, the library that must accompany script.aculo.us in order to use its widget controls and special effects.

Setting Up

The first step in using script.aculo.us is to download the library from http://script.aculo.us/downloads. This site makes the library available as an archive (currently scriptaculous-js-1.5.1.tar.gz), which contains various JavaScript files that you have to add to whichever web application directory you have designated for JavaScripts. The files are: builder.js, controls.js, dragdrop.js, effects.js, scriptaculous.js, and slider.js. (A file called unittest.js, useful if you want to run unit tests on your code, is also included.) The main JavaScript directory for this hack, which is built on the Tomcat web container, is /parkerriver/ajaxhacks/js, so that's where I put all of these files. script.aculo.us depends on prototype.js, so make sure this library is included in the directory as well (see "Use Prototype's Ajax Tools with Your Application" [Hack #50]).

Next, you must make sure that the script.aculo.us library is properly loaded. A simple hack like this one will also work when the web page is loaded into the browser from the filesystem.

While your designated directory for JavaScript files has to contain the various script.aculo.us-dependent files, your web page only has to include prototype.js and scriptaculous.js (which loads all of its dependencies itself). This hack's web page also imports efflib_2.js, which is the JavaScript file that contains our application code. Here's what the head section of the web page should look like:

<html lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <script src="js/prototype.js" type="text/javascript"></script>
    <script src="js/scriptaculous.js" type="text/javascript"></script>
    <script src="js/efflib_2.js" type="text/javascript"></script>
    <style type="text/css">
        @import "/stylesheets/hacks.css";
    </style>
    <title>Toggle a control</title>
</head>

With the setup complete, let's take a look at how easy it is to include a useful control or effect with your Ajax application.

Toggling and Switching

Some applications need to be able to show or hide a control or page region, depending on what the user wants to do with the application. For example, this hack contains a textarea that shows instant messages, similar to an emailer that auto-fetches emails. The application enables users to show or hide the textarea (in other words, to get it out of the way when they are not examining their messages).

The hack uses the toggle effect of Prototype and the SwitchOff effect of script.aculo.us.

Figure 8-1 shows the section of the web page that contains a viewport for instant messages.

Figure 8-1. Embed script.aculo.us controls in a view


When the user clicks the Toggle button, the textarea or view port disappears, and the two buttons move up the page to take its place. Clicking the "Switch off" button elicits a more interesting animationthat of a TV screen of the older cathode-ray tube vintage switching offas the textarea disappears. Again, the two buttons move up to inhabit the region where the view port used to be. Clicking the Toggle button again restores the viewport.

So, how does this work? Here's all the code that's necessary:

window.onload=function(  ){
   if($("msg_screen") && $("toggle") && $("switchoff")){
      $("toggle").onclick=function(  ){
        Element.toggle($("msg_screen"));
      };
       $("switchoff").onclick=function(  ){
        Effect.SwitchOff("msg_screen"));
       };
   }
};

The onclick event handlers of each button are set to call Element.toggle( ) and Effect.SwitchOff( ). toggle( ) takes the toggled element as a parameter; the code uses the Prototype shortcut $("msg_screen"). Effect.SwitchOff takes the switched-off element's id as a parameter.

The code also checks that each of these elements, including the textarea, exists on the web page before it assigns behaviors.


Hacking the Hack

You can make the code feed the message screen with new server messages using Prototype's Ajax.Updater object, perhaps in conjunction with the PeriodicalExecuter (see "Create Observers for Web Page Fields" [Hack #52]).


Previous Page
Next Page