Ajax Helper

Hamilton G. Chua (ham@solutiongrove.com)
January 2006
v0.1d

Components :
Prototype v1.4.0 (http://prototype.conio.net/)
Scriptaculous v1.5.1 (http://script.aculo.us/)
Rico v1.1.0 (http://www.openrico.org)
Overlibmws (http://www.macridesweb.com/oltest/)
Extracted Rounder Functions from Rico
(http://encytemedia.com/blog/articles/2005/12/01/rico-rounded-corners-without-all-of-rico)

Introduction :

The Ajax Helper package provides TCL API to generate the javascript from the above components to enable their various features for use in OpenACS applications. The motivation for this package is to easily enable Web 2.0 like features in OpenACS applications using the most popular javascript library prototype.js and it's derivatives like Scriptaculous and Rico.

Prerequisites :

The ajax helper package must be installed and mounted in /ajax to be able ot use these features. The installer should automatically mount the ajax helper in /ajax.

Javascript Sources :

The javascript files from prototype and scriptaculous must be declared in the < head > section of an html page. In the case of OpenACS applications that use the templating system, the sources must be declared in the blank-master.adp file.

To have the ajax helper generate the javascript declaration ....

TCL File (blank-master.tcl) :

set ah_sources [ah::js_sources -default]

ADP File (blank-master.adp):

@ah_sources;noquote@

Compiled Template:

<script type="text/javascript" src="/ajax/prototype/prototype.js"></script> 
<script type="text/javascript" src="/ajax/scriptaculous/builder.js"></script> 
<script type="text/javascript" src="/ajax/scriptaculous/controls.js"></script> 
<script type="text/javascript" src="/ajax/scriptaculous/dragdrop.js"></script> 
<script type="text/javascript" src="/ajax/scriptaculous/effects.js"></script> 
<script type="text/javascript" src="/ajax/scriptaculous/slider.js"></script>
<script type="text/javascript" src="/ajax/scriptaculous/scriptaculous.js"></script>

The above TCL API generates the default sources that must be declared for you to be able to use the javascript libraries Ajax Helper has support for overlibmws (DHTML callouts) and RICO (other cinematic effects) in addition to scriptaculous. Scriptaculous is the default javascript library.

To generate the javascript sources for Rico :

    set ah_sources [ah::js_sources -source "rico"]

To generate the javscript sources for Overlibmws :

    set ah_sources [ah::js_sources -source "overlibmws"]

The functions that are responsible for rounded corners has been extracted into rounded.js to work with scriptaculous.
To use these functions wihtout using all of rico.js

    set ah_sources [ah::js_sources -source "rounder"]

NOTE :

You can combine sources by doing this

    set ah_sources [ah::js_sources -default]
    append ah_sources [ah::js_sources -source "overlibmws"]

The above code will generate the overlibmws javascript source declaration with the default declarations.

Overlibmws and the default sources (Scriptaculous) are compatible with each other. It is not advisable to use both Scriptaculous and Rico at the same time.

Ajax Procedures :

Prototype has a pair of javascript functions that alllow programmers to use XMLHTTP. The ajax.updater and ajax.request functions. See http://wiki.script.aculo.us/scriptaculous/show/Ajax.Updater and http://wiki.script.aculo.us/scriptaculous/show/Ajax.Request for more information about these javascript functions.

The TCL API is used like this

    set request [ah::ajaxrequest -url "/url/to/call" \
                                                     -pars "parameter1=parameter_value&parameter1=parameter_value" ]

The above api will generate an ajax.request javascript function that is best placed in an event like "onClick".

    <a href="#" onClick="@request;noquote@">

Consult the api-doc for more information about other parameters you can pass on to the ah::ajaxrequest proc.

The ah::ajaxrequest will make an xmlhttp call but does not do anything about the response. To update content based on the response from an xmlhttp request, use ah::ajaxupdate. This procedure will not only make an xmlhttp call but update the contents of a div or layer with the response text of the xmlhttp request.

Here's an example :

       set js_update_connections [ah::ajaxupdate -container "connections" \
                -url "/url/to/call" \
                -enclose \
                -pars "'effects=$effects&limit_n=$limit_n'" \
                -effect "Fade" \
                -effectopts "duration: 0.5"]

On the adp side, you can just put

      @js_update_connections;noquote@

The "-enclose" parameter tells the procedure to enclose the resulting script in script tags <script></script>. This is another option in addition to putting the scripts in html event attributes like onClick, onMouseover or onChange.

The "-pars" parameter is where you pass the querystring that you want to send along with the xmlhttp request. Notice that it takes the form of a querystring that you normally see in the address bar of your browser. Use this to pass values to the URL you are making an xmlhttp request to.

The "-effect" parameter is an optional parameter that allows you to specify the effect you want to execute after the container's content has been updated.

Cinematic Effects :

Use ah::effects to generate javascript that allows you to implement transitional and cinematic effects to html elements. You will need to consult the scriptaculous documentation http://wiki.script.aculo.us/scriptaculous/tags/effects to know what kinds of effects and what kinds of options you can pass to the effect script.

The procedure is called in this manner :

    set effect [ah::effect -element "container"
                                       -effect "Fade"
                                       -options "duration: 1.5"]
NOTE :
The Effect name and the options are case sensitive.

DHTML Callouts :

There is currently basic support for overlibmws. Right now we are able to create bubble type call outs.

In your tcl file ...

   set onmouseover [ah::bubblecallout -text " Contents of My Popup" ]

The adp file should have something like this ....

   <a href="#" @onmouseover;noquote@ >Link with Popup</a>

Drag and Drop Sortables :

Sortables are documented in the scriptaculous wiki http://wiki.script.aculo.us/scriptaculous/show/Sortables.
For sortables to work you will need to define a container which will hold the elements you want to be sortable.

Here is what the script looks like

    append scripts [ah::sortable -element "container"
                                                     -options "tag:'div',only:'portlet',overlap:'horizontal',constraint:false,ghosting:false"]

You adp page should contain a div with id attribute container. This "container" should have subcontainers which the above script will make sortable.