NAME

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

SYNOPSIS

  use CGI::Ajax; # required for all of the following

  1. Standard Method of using CGI::Ajax

  # create the CGI::Ajax object sending in a function name and a
  # reference to a sub, or an anonymous sub
  my $pjx = new CGI::Ajax( 'exported_func' => \&perl_func );
  my $pjx = new CGI::Ajax( 'exported_func' => $perl_anon_func );

	# send to an exported function the value in an html text box 
	# with id='input_elem'  and have the result go to 'output' use: 
  onClick="exported_func(['input_elem'],['output']);"

	#that is all the javascript you'll need. your html element for the
	#example above must have 'id' i.e.: 
	# <input type=text id='input_elem'>

  2. Advanced Methods: Multiple input/outputs and renaming parameters
  # send in parameters from html elements 'input1','input2' and have
	# the results go to 'result1','result2':
  onClick="exported_func(['input1','input2'],['result1','result2']);"

  # send in perl variables ($input1,$input2) using the 'args__' keyword:
  onClick="exported_func([\"args__$input1\",\"args__$input2\"],['out_div']);"

  # send in a constant (42):
  onClick="exported_func([\"args__42\"],['out_div']);"


  3. URL/outside script Method

  # create the CGI::Ajax object sending in a function name and a
  # url to a local script, where the receiving script uses parameters
  # from html elements on our page
  my $url = './outside_script.pl';
  my $pjx = new CGI::Ajax( 'external' => $url );

	# this will work as before:
  onClick="external(['input1','input2'],['out_div']);"

  # the outside_script.pl will get the values via: 
	 $cgi->params('args');  


  # rename parameters: 
  onClick="exported_func([\"myname__$input1\",\"myparam__$input2\"],['out_div']);"
	
	#retrieve them in an outside script with :
	#  $cgi->params('myname');  
	#  $cgi->params('myparam');  
	#  if sending to a function IN the perljax script, the perljax object
	#  uses $q->param('args') so not likely a good idea to rename.

  # rename a parameter to 'myparam' but get the value from an html element with div
	# id of 'input1':

  onClick="exported_func(['myparam__' + getVal('input1')],['out_div']);"

  # N.B. These examples show the use of outside scripts which are other
  # perl scripts, but you are not limited to perl - it could just as
  # easily be php or any other cgi script

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 any javascript, except for having to associate an exported method with a document-defined event (such as onClick, onKeyUp, etc). Only in the more advanced implementations of a 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.

USAGE

Create a CGI object to send to CGI::Ajax, export the subroutines prior to creating the CGI::Ajax object, like so:

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

  # define a normal perl subroutine that you want available 

    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");

  }

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

  sub Show_HTML {
    my $html = <<EOT;

  <HTML>
  <HEAD><title>CGI::Ajax Example</title>
  </HEAD>
  <BODY>
    Enter a number:&nbsp;
    <input type="text" name="val1" id="val1" size="6"
       onkeyup="evenodd( ['val1'], 'resultdiv' );
       return true;"><br>
    <hr>
    <div id="resultdiv" style="border: 1px solid black;
          width: 440px; height: 80px; overflow: auto">
    </div>
  </BODY>
  </HTML>
  EOT

    return $html;
  }

  my $cgi = new CGI();  # create a new CGI object

  # create a CGI::Ajax object, and associate our anon code
  # In >= version 0.20 of CGI::Ajax, you can make the associated
  # code a url to another CGI script (as seen in the above synopsis).

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

	# print the form sending in the cgi and the HTML function.  A cgi
  # object is only necessary in this scenario because we use the
  # CGI->header() function
  
  # this outputs the html for the page
  print $pjx->build_html($cgi,\&Show_HTML);

METHODS

build_html()

    Purpose: associate cgi obj ($cgi) with pjx object, insert
		         javascript into <HEAD></HEAD> element
  Arguments: either a coderef, or a string containing html
    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;

BUGS

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.

SEE ALSO

Class::Accessor, CGI