Ajax Helper

Hamilton G. Chua (ham@solutiongrove.com)
November 2006
v0.8d

Components :
Prototype v1.5.0_rc_1 (http://prototype.conio.net/)
Scriptaculous v1.6.4 (http://script.aculo.us/)
Overlibmws (http://www.macridesweb.com/oltest/)
Curvey Corners (http://www.curvycorners.net/)
Yahoo User Interface Library 0.11.4 (http://developer.yahoo.com/yui/)
Dojo Toolkit 0.4 (http://dojotoolkit.com)


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 libraries.

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 upon installation of the package.

Javascript Sources :

As of version 0.8d, required javascript sources will be loaded automatically depending on the wrapper function used. The following piece of code must be present in the blank-master.tcl template file to make this automated loading of javascript source files possible.

TCL File (blank-master.tcl) :

if { ![info exists header_stuff] } {
    set header_stuff {} 
}

# HAM : lets check ajaxhelper globals ***********************

global ajax_helper_js_sources
global ajax_helper_yui_js_sources
global ajax_helper_dojo_js_sources
set js_sources ""

if { [info exists ajax_helper_js_sources] || [info exists ajax_helper_yui_js_sources] || [info exists ajax_helper_dojo_js_sources] } {

	# if we're using ajax, let's use doc_type strict so we can get
	# consistent results accross standards compliant browsers
	set doc_type { < !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" > }

	if { [info exists ajax_helper_js_sources] } {
		append js_sources [ah::load_js_sources -source_list $ajax_helper_js_sources]
	}

	if { [info exists ajax_helper_yui_js_sources] } {
		append js_sources [ah::yui::load_js_sources -source_list $ajax_helper_yui_js_sources]
	}

	if { [info exists ajax_helper_dojo_js_sources] } {
		append js_sources [ah::dojo::load_js_sources -source_list $ajax_helper_dojo_js_sources]
	}
}

# ***********************************************************

# Attributes

multirow create attribute key value
set onload {}

ADP File (blank-master.adp):

@js_sources;noquote@
@header_stuff;noquote@

Automated loading will work only if you are using a wrapper script.

Alternatively if you wish to have more control of what javascript sources are loaded, you can still use the ah::js_sources procedure.

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

TCL File (e.g blank-master.tcl) :

    set ah_sources [ah::js_sources -default]

ADP File (eg. 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

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.

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

NOTE :

You can combine sources by specifying them in the source parameter separated by commas.

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

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


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.