Ajax Connections

Overview

The first tutorial in this series introduces you to the Ajax Helper package and how to implement simple cinematic effects. The second tutorial in this series will show you how to make ajax requests to update sections of an html page without refreshing an entire page.

If you're wondering how a portlet can be inserted into the the mashups demo page without refreshing the entire page, this tutorial is for you.

Prerequisites

Prerequisites for this tutorial are the same as the first. Please make sure you have Ajax Helper installed on your OpenACS instance. The installation should also mount ajax helper in /ajax. Also ensure that you have sourced the needed javascript libraries. Please consult the first tutorial on how to source javascript libraries.

Ajax Update

The tcl wrapper proc that generates the javascript to perform an xmlhttp connection and update a portion of an html page is ah::ajaxupdate. Here is a sample of how it is used.

 
set script [ah::update -container "test" \
-url "/tutorial2-handler" \
-pars "'myid=123'" \
-options "onSuccess:function(t){ alert('update done : 't.responseText); }"]

• query the url tutorial2-handler
• pass a querysting "myid" to the url using http post
• retrieve whatever text is returned from tutorial2-handler
• write the text in the html element with id "test"
• when the connection is successful, it will popup an alert box

In addition to the javascript that makes the xmlhttp connection, there is another component to make ajax work. The second component is the URL that will receive, handle and return a response to the request. This URL must be ready to return some text that will be used to update an html element. It can be a page that accepts one or more querystring parameters. It can also be a tcl page that queries the database and returns results from the database.

The javascript above can be placed in the onclick attribute of an image or link. Clicking the link or image will trigger the xmlhttp connection that subsequently updates an html element.

Practical Example

In this practical example we show a page with a link, a text field and a div element. A user types his/her name on the text field and clicks the link to update the contents. The resulting javascript will retrieve the value of the text field and submit this to the handler url using xmlhttp. The results are then used to update the contents of the gray box. html element.

1. Create a tcl file (tutorial2.tcl) with the following

	 
	set sources [ah::js_sources -default]
	set updatescript [ah::ajaxupdate -container "test" \
	-url "tutorial2-handle" \
	-pars "'myname='+document.getElementById('name').value" \
	-options "onSuccess:function(t){ alert('update done : '+t.responseText); }"]
	

2. Create an adp file (tutorial2.adp) with the following

	<  html >
	< head >
	< title > Tutorial Two < /title >
	@sources;noquote@
	< /head >
	< body >
	Type your name please : < input type="text" id="name" / >
	< br >
	< a href="javascript:void(0)" onclick="@updatescript;noquote@" > Update Content < /a > 
	< br >< br >
	< div id="test" style="width:250;height:100;background:#e2e2e2" >
	The quick brown fox .....
	< /div >  
	< /body >
	< /html  >  
	

3. Create the handler, that receives the xmlhttp request and returns some text

tutorial2-handle.adp

		... jumped over @name;noquote@.
	


tutorial2-handle.tcl

		set name [ns_queryget "myname"]
	

View this example here.

More Ajax

ah::ajaxupdate is a tcl wrapper for the scriptaculous Ajax.Updater function. Consult the scriptaculous documentation for more information about additional parameters and options you can pass to ajaxupdate. Also consult the /api-doc of your local installation to view the parameters that the tcl procedure accepts. If you would like to make an xmlhttp request but you do not wish to update any html element, you can use ah::ajaxrequest. It uses the same syntax except that you no longer need to pass a -container parameter.