NAME

CGI::Ajax - a perl-specific system for writing AJAX- or DHTML-based web applications (formerly known as the module CGI::Perljax).

SYNOPSIS

use strict;
use CGI;
use CGI::Ajax;

my $cgi = new CGI;
my $pjx = new CGI::Ajax( 'exported_func' => \&perl_func );

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

sub perl_func {
  my $input = shift;
  # do something with $input
  my $output = $input . " was the input!";
  return( $output );
}

sub Show_HTML {
  my $html = <<EOHTML;
  <HTML>
  <BODY>
    Enter something: 
      <input type="text" name="val1" id="val1"
       onkeyup="exported_func( ['val1'], ['resultdiv'] ); return true;"><br>
    <div id="resultdiv"></div>
  </BODY>
  </HTML>
EOHTML
  return $html;
}

There are several fully-functional examples in the 'scripts/' directory of the distribution.

DESCRIPTION

CGI::Ajax is an object-oriented module that provides a unique mechanism for using perl code asynchronously from javascript-enhanced web pages. You would commonly use CGI::Ajax in AJAX/DHTML-based web applications. CGI::Ajax unburdens the user from having to write javascript, except for associating an exported method with a document-defined event (such as onClick, onKeyUp, etc). Only in the more advanced implementations of an exported perl method would a user need to write any javascript.

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

Using CGI::Ajax, the URL for the HTTP GET request is automatically generated based on HTML layout and events, and the page is then dynamically updated. We also have support for 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.

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.

EXAMPLES

The CGI::Ajax module allows a Perl subroutine to be called asynchronously. To do this, it must be exported:

my $pjx = new CGI::Ajax( 'JSFUNC' => \&PERLFUNC );

This maps a perl subroutine (PERLFUNC) to an automatically generated Javascript function (JSFUNC). Next you setup an HTML event to call the new Javascript function:

onClick="JSFUNC(['source1','source2'], ['dest1','dest2']); return true;"

where 'source1', 'dest1', 'source2', 'dest2' are the DIV ids of HTML elements in your page...

<input type=text id=source1>

CGI::Ajax sends the values from source1 and source2 to your Perl subroutine and returns the results to dest1 and dest2.

4 Usage Methods

1 Standard CGI::Ajax example

Start by defining a perl subroutine that you want available from javascript. In this case we'll define a subrouting that determines whether or not an input is odd, even, or not a number (NaN):

use strict;
use CGI::Ajax;
use CGI;


sub evenodd_func {
  my $input = shift;

  # see if input is defined
  if ( not defined $input ) {
    return("input not defined or NaN");
  }

  # see if value is a number (*thanks Randall!*)
  if ( $input !~ /\A\d+\z/ ) {
    return("input is NaN");
  }

  # got a number, so mod by 2
  $input % 2 == 0 ? return("EVEN") : return("ODD");
}

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

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

Next we define a function to generate the web page - this can be done million 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)...

sub Show_HTML {
  my $html = <<EOT;
<HTML>
<HEAD><title>CGI::Ajax Example</title>
</HEAD>
<BODY>
  Enter a number:&nbsp;
  <input type="text" name="somename" id="val1" size="6"
     onkeyup="evenodd( ['val1'], ['resultdiv'] ); return true;"><br>
  <hr>
  <div id="resultdiv">
  </div>
</BODY>
</HTML>
EOT
  return $html;
}

Note how we reference the exported subroutine in the OnKeyup event handler. The subroutine takes one value from the form, the 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 a an array for the output divs, but this isn't mandatory - as will be explained in the Advanced usage.

Now create a CGI object...

my $cgi = new CGI();

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

my $pjx = new CGI::Ajax( 'evenodd' => \&evenodd_func );

And if we used a coderef, it would look like this...

my $pjx = new CGI::Ajax( 'evenodd' => $evenodd_func );

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:

print $pjx->build_html($cgi,\&Show_HTML,
  {-charset=>'UTF-8, -expires=>'-1d'});

See CGI for more header() options.

That's it for the CGI::Ajax standard method. Let's look at something more advanced.

2 Advanced CGI::Ajax example

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 values and returns multiple values. The significant change happens in the event handler javascript in the HTML...

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

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').

3 Sending Perl Subroutine Output to a Javascript function

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]); return true;"

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. Be aware 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.

function js_process_func() {
  var input1 = arguments[0];
  var input2 = arguments[1];
  // do something and return results, or set HTML divs using
  // innerHTML
  document.getElementById('outputdiv').innerHTML = input1;
}

4 URL/Outside Script CGI::Ajax example

There are times when you may want a different script to return content to your page. This can be accomplished with 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.

my $url = 'scripts/outside_script.pl';
my $pjx = new CGI::Ajax( 'external' => $url );

This will work as before in terms of how it is called from you event handler:

onClick="external(['input1','input2'],['resultdiv']);"

The outside_script.pl will get the values via a CGI object and accessing the 'args' key. The values of the 'args' key will be an array of everything that was sent into the script.

my @input = $cgi->params('args');
$input[0]; # contains first argument
$input[1]; # contains second argument, etc...

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 - notice the escaped quotes and the required args__ prefix:

onClick="exported_func([\"args__$input1\",\"args__$input2\"],['resultdiv']);"

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.

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

onClick="exported_func([\"myname__$input1\",\"myparam__$input2\"],['resultdiv']);"

The URL generated would look like this script.pl?myname=input1&myparam=input2. You would then retrieve the input in the outside script with this...

my $p1 = $cgi->params('myname');
my $p1 = $cgi->params('myparam');

Finally, what if you need to get a value from our HTML page and you 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):

onClick="exported_func(['myparam__' + getVal('div_id')[0]],['resultdiv']);"

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

GET versus POST

Note that all the examples so far have used the following syntax:

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

There is an optional third argument to a CGI::Ajax exported function that allows change the submit method. The above event could also have been coded like this...

onClick="exported_func(['input1'],['result1'], 'GET'); return true;"

By default, CGI::Ajax sends a 'GET' request. If you need it, for example your URL is getting way too long, you can easily switch to a 'POST' request with this syntax...

onClick="exported_func(['input1'],['result1'], 'POST'); return true;"

METHODS

build_html()

  Purpose: associate cgi obj ($cgi) with pjx object, insert
           javascript into <HEAD></HEAD> element
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. (Thanks
           to Jesper Dalberg for this suggestion)
  Returns: html or updated html (including the header)
Called By: originating cgi script

show_javascript()

  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.

register()

  Purpose: adds a function name and a code ref to the global coderef
           hash, after the original object was created
Arguments: function name, code reference
  Returns: none
Called By: originating web script

JSDEBUG()

  Purpose: See the URL that is being generated
Arguments: JSDEBUG(0); # turn javascript debugging off
           JSDEBUG(1); # turn javascript debugging on
  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;

DEBUG()

  Purpose: Show debugging information in web server logs
Arguments: DEBUG(0); # turn debugging off (default)
           DEBUG(1); # turn debugging on
  Returns: prints debugging information to the web server logs using
           STDERR
Called By: $pjx->DEBUG(1) # where $pjx is a CGI::Ajax object;

BUGS

see project homepage - none that we know of yet.

SUPPORT

Check out the sourceforge discussion lists at:

http://www.sourceforge.net/projects/pjax

AUTHORS

Brian C. Thomas     Brent Pedersen
CPAN ID: BCT
bct.x42@gmail.com   bpederse@gmail.com

A NOTE ABOUT THE MODULE NAME

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.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)