Ajax Helper

Hamilton G. Chua (ham@solutiongrove.com)
September 2007
v0.87d

Components :
Prototype v1.5.1 (http://prototypejs.org/)
Scriptaculous v1.7.3 Beta (http://script.aculo.us/)
Overlibmws (http://www.macridesweb.com/oltest/)
Curvey Corners (http://www.curvycorners.net/)
Yahoo User Interface Library 2.3.0 (http://developer.yahoo.com/yui/)
Dojo Toolkit 0.4 (http://dojotoolkit.com)
ExtJs 1.1.1 (http://extjs.com)

What's New :

0.87d

Uses Lee Denison's template::head code to load javascript sources and cascading style sheets
Removed Dojo javascript sources, users who would like to use dojo should download it separately from http://dojotoolkit.org
Added ExtJs javascript sources
Added helpers for YUI menu, autocomplete and treeview.
Added ExtJs helpers for Ext.onReady, Ext.Ajax and Ext.MessageBox
Additional tests in ajaxhelper/www/tests

Introduction :

The Ajax Helper package provides helper Tcl API procs to generate the javascript from the above listed 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 libraries.

Prerequisites :

The ajax helper package must be installed and mounted in /ajax . The installer should automatically mount the ajax helper in /ajax/ upon installation of the package.

Lee Denison's template::head code must be available. This code will soon be committed to CVS head after consulting the community and some more testing.

In the mean time, you can find the files you need to implement template head from packages/ajaxhlper/www/docs. You should copy the files into the following locations

acs-integration-procs.tcl	openacs_root/packages/acs-templatng/tcl/
head-procs.tcl	openacs_root/packages/acs-templatng/tcl/
blank-master.adp	openacs_root/www/
blank-master.tcl	openacs_root/www/
site-master.adp	openacs_root/www/
site-master.tcl	openacs_root/www/
default-master.tcl	openacs_root/www/
default-master.adp	openacs_root/www/

Javascript Sources :

As of 0.87d, all required sources and stylesheets are loaded automatically using Lee Denison's template::head code.

Ajax Procedures :

Prototype has a pair of javascript functions that alllow programmers to use XMLHTTP. The ajax.updater and ajax.request functions. See http://api.prototypejs.org/ajax/Ajax/Updater/ and http://api.prototypejs.org/ajax/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@">Send Request</a>

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


<a href="#" onClick="@js_update_connections;noquote@">Update</a>

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://madrobby.github.io/scriptaculous/core-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 in the tcl file:


set effect [ah::effect -element "container" -effect "Fade" -options "duration: 1.5"]

On the adp file you must put the javascript on a click event


<a href="#" onClick="@effect;noquote@">Show Effect</a>

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://madrobby.github.io/scriptaculous/sortable/.
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.