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