synchro results from the CPAN

CGI-Ajax
package CGI::Ajax;
use strict;
use Data::Dumper;
use base qw(Class::Accessor);
use overload '""' => 'show_javascript';    # for building web pages, so
                                           # you can just say: print $pjx

BEGIN {
    use vars qw ($VERSION @ISA @METHODS);
    @METHODS = qw(url_list coderef_list CACHE DEBUG JSDEBUG html
      js_encode_function cgi_header_extra skip_header fname);

    CGI::Ajax->mk_accessors(@METHODS);

    $VERSION = .707;
}

########################################### main pod documentation begin ##

=head1 NAME

CGI::Ajax - a perl-specific system for writing Asynchronous web
applications

=head1 SYNOPSIS

  use strict;
  use CGI;      # or any other CGI:: form handler/decoder
  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'] );">
      <br>
      <div id="resultdiv"></div>
    </BODY>
    </HTML>
  EOHTML
    return $html;
  }

When you use CGI::Ajax within Applications that send their own header information,
you can skip the header:

  my $pjx = new CGI::Ajax(
    'exported_func' => \&perl_func,
    'skip_header'   => 1,
  );
  $pjx->skip_header(1);
  
  print $pjx->build_html( $cgi, \&Show_HTML);

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

=head1 DESCRIPTION

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 I<support> for other CGI handler/decoder modules,
like L<CGI::Simple> or L<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.

=head1 EXAMPLES

The CGI::Ajax module allows a Perl subroutine to be called
asynchronously, when triggered from a javascript event on the
HTML page.  To do this, the subroutine must be I<registered>,
usually done during:

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

This maps a perl subroutine (PERLFUNC) to an automatically
generated Javascript function (JSFUNC).  Next you setup a trigger this
function when an event occurs (e.g. "onClick"):

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

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

  <input type=text id=source1>
  <input type=text id=source2>
  <div id=dest1></div>
  <div id=dest2></div>

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

=head2 4 Usage Methods

=over 4

=item 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 subroutine
  };
( run in 0.761 second using v1.01-cache-2.11-cpan-97f6503c9c8 )