CGI::Ajax is an object-oriented module that provides a unique mechanism for using perl code asynchronously from javascript- enhanced HTML pages. CGI::Ajax unburdens the user from having to write extensive javascript, except for associating an exported method with a document-defined event (such as onClick, onKeyUp, etc). CGI::Ajax also mixes well with HTML containing more complex javascript.

CGI::Ajax supports methods that return single results or multiple results to the web page, and supports returning values to multiple DIV elements on the HTML page.

Using CGI::Ajax, the URL for the HTTP GET/POST request is automatically generated based on HTML layout and events, and the page is then dynamically updated with the output from the perl function. Additionally, CGI::Ajax supports mapping URL's to a CGI::Ajax function name, so you can separate your code processing over multiple scripts.

Other than using the Class::Accessor module to generate CGI::Ajax' accessor methods, CGI::Ajax is completely self-contained - it does not require you to install a larger package or a full Content Management System, etc.

We have added support for other CGI handler/decoder modules, like CGI::Simple or CGI::Minimal, but we can't test these since we run mod_perl2 only here. CGI::Ajax checks to see if a header() method is available to the CGI object, and then uses it. If method() isn't available, it creates it's own minimal header.

A primary goal of CGI::Ajax is to keep the module streamlined and maximally flexible. We are trying to keep the generated javascript code to a minimum, but still provide users with a variety of methods for deploying CGI::Ajax. And VERY little user javascript.

Alternatively, we could have used coderefs to associate an exported name...

my $evenodd_func = sub {
# exactly the same as in the above subroutine
};

Next we define a function to generate the web page - this can be done many different ways, and can also be defined as an anonymous sub. The only requirement is that the sub send back the html of the page. You can do this via a string containing the html, or from a coderef that returns the html, or from a function (as shown here)...

The exported Perl subrouting is triggered using the OnKeyUp event handler of the input HTML element. The subroutine takes one value from the form, the input element 'val1', and returns the the result to an HTML div element with an id of 'resultdiv'. Sending in the input id in an array format is required to support multiple inputs, and similarly, to output multiple the results, you can use an array for the output divs, but this isn't mandatory - as will be explained in the Advanced usage.

Now create a CGI object and a CGI::Ajax object, associating a reference to our subroutine with the name we want available to javascript.

Now we're ready to print the output page; we send in the cgi object and the HTML-generating function.

print $pjx->build_html($cgi,\&Show_HTML);

CGI::Ajax has support for passing in extra HTML header information to the CGI object. This can be accomplished by adding a third argument to the build_html() call. The argument needs to be a hashref containing Key=>value pairs that CGI objects understand:

Let's say we wanted to have a perl subroutine process multiple values from the HTML page, and similarly return multiple values back to distinct divs on the page. This is easy to do, and requires no changes to the perl code - you just create it as you would any perl subroutine that works with multiple input values and returns multiple values. The significant change happens in the event handler javascript in the HTML...

onClick="exported_func(['input1','input2'],['result1','result2']);"

Here we associate our javascript function ("exported_func") with two HTML element ids ('input1','input2'), and also send in two HTML element ids to place the results in ('result1','result2').

Occassionally, you might want to have a custom javascript function process the returned information from your Perl subroutine. This is possible, and the only requierment is that you change your event handler code...

onClick="exported_func(['input1'],[js_process_func]);"

In this scenario, js_process_func is a javascript function you write to take the returned value from your Perl subroutine and process the results. Note that a javascript function is not quoted -- if it were, then CGI::Ajax would look for a HTML element with that id. Beware that with this usage, you are responsible for distributing the results to the appropriate place on the HTML page. If the exported Perl subroutine returns, e.g. 2 values, then js_process_func would need to process the input by working through an array, or using the javascript Function arguments object.

There are times when you may want a different script to return content to your page. This could be because you have an existing script already written to perform a particular task, or you want to distribute a part of your application to another script. This can be accomplished in CGI::Ajax by using a URL in place of a locally-defined Perl subroutine. In this usage, you alter you creation of the CGI::Ajax object to link an exported javascript function name to a local URL instead of a coderef or a subroutine.

This is good, but what if you need to send in arguments to the other script which are directly from the calling Perl script, i.e. you want a calling Perl script's variable to be sent, not the value from an HTML element on the page? This is possible using the following syntax:

Similary, if the external script required a constant as input (e.g. script.pl?args=42, you would use this syntax:

onClick="exported_func(['args__42'],['resultdiv']);"

In both of the above examples, the result from the external script would get placed into the resultdiv element on our (the calling script's) page.

If you are sending more than one argument from an external perl script back to a javascript function, you will need to split the string (AJAX applications communicate in strings only) on something. Internally, we use '__pjx__', and this string is checked for. If found, CGI::Ajax will automatically split it. However, if you don't want to use '__pjx__', you can do it yourself:

In order to rename parameters, in case the outside script needs specifically-named parameters and not CGI::Ajax' 'args' default parameter name, change your event handler associated with an HTML event like this

Finally, what if we need to get a value from our HTML page and we want to send that value to an outside script but the outside script requires a named parameter different from 'args'? You can accomplish this with CGI::Ajax using the getVal() javascript method (which returns an array, thus the getVal()[0] notation):

This will get the value of our HTML element with and id of div_id, and submit it to the url attached to myparam__. So if our exported handler referred to a URI called script/scr.pl, and the element on our HTML page called div_id contained the number '42', then the URL would look like this script/scr.pl?myparam=42. The result from this outside URL would get placed back into our HTML page in the element resultdiv. See the example script that comes with the distribution called pjx_url.pl and its associated outside script convert_degrees.pl for a working example.

N.B. These examples show the use of outside scripts which are other perl scripts - but you are not limited to Perl! The outside script could just as easily have been PHP or any other CGI script, as long as the return from the other script is just the result, and not addition HTML code (like FORM elements, etc).

We have implemented a method to prevent page cacheing from undermining the AJAX methods in a page. If you send in an input argument to a CGI::Ajax-exported function called 'NO_CACHE', the a special parameter will get attached to the end or your url with a random number in it. This will prevent a browser from caching your request.

onClick="exported_func(['input1','NO_CACHE'],['result1']);"

The extra param is called pjxrand, and won't interfere with the order of processing for the rest of your parameters.

Purpose: Associates a cgi obj ($cgi) with pjx object, inserts
javascript into <HEAD></HEAD> element and constructs
the page, or part of the page. AJAX applications
are designed to update only the section of the
page that needs it - the whole page doesn't have
to be redrawn. L<CGI::Ajax> applications use the
build_html() method to take care of this: if the CGI
parameter C<fname> exists, then the return from the
L<CGI::Ajax>-exported function is sent to the page.
Otherwise, the entire page is sent, since without
an C<fname> param, this has to be the first time
the page is being built.
Arguments: The CGI object, and either a coderef, or a string
containing html. Optionally, you can send in a third
parameter containing information that will get passed
directly to the CGI object header() call.
Returns: html or updated html (including the header)
Called By: originating cgi script

Purpose: builds the text of all the javascript that needs to be
inserted into the calling scripts html <head> section
Arguments:
Returns: javascript text
Called By: originating web script
Note: This method is also overridden so when you just print
a CGI::Ajax object it will output all the javascript needed
for the web page.

Purpose: Show the AJAX URL that is being generated, and stop
compression of the generated javascript, both of which can aid
during debugging. If set to 1, then the core js will get
compressed, but the user-defined functions will not be
compressed. If set to 2 (or anything greater than 1 or 0),
then none of the javascript will get compressed.
Arguments: JSDEBUG(0); # turn javascript debugging off
JSDEBUG(1); # turn javascript debugging on, some javascript compression
JSDEBUG(2); # turn javascript debugging on, no javascript compresstion
Returns: prints a link to the url that is being generated automatically by
the Ajax object. this is VERY useful for seeing what
CGI::Ajax is doing. Following the link, will show a page
with the output that the page is generating.
Called By: $pjx->JSDEBUG(1) # where $pjx is a CGI::Ajax object;

This module was initiated using the name "Perljax", but then registered with CPAN under the WWW group "CGI::", and so became "CGI::Perljax". Upon further deliberation, we decided to change it's name to CGI::Ajax.