view release on metacpan or  search on metacpan

lib/CGI/ExtDirect.pod  view on Meta::CPAN

=pod

=begin readme text

CGI::ExtDirect
==============

=end readme

=for readme stop

=head1 NAME

CGI::ExtDirect - Ext.Direct remoting gateway for CGI applications

=head1 SYNOPSIS

=head2 API definition

In C</cgi-bin/api.cgi>:

    use CGI::ExtDirect;
    use RPC::ExtDirect::Config;
    
    use My::ExtDirect::Published::Module::Foo;
    use My::ExtDirect::Published::Module::Bar;
    
    my $config = RPC::ExtDirect::Config->new(
        api_path     => '/cgi-bin/api.cgi',
        router_path  => '/cgi-bin/router.cgi',
        poll_path    => '/cgi-bin/events.cgi',
    );
    
    my $direct = CGI::ExtDirect->new(config => $config);
    
    print $direct->api();      # Prints full HTTP response

=head2 Routing requests

In C</cgi-bin/router.cgi>:

    use CGI::Cookie;
    use CGI::ExtDirect;
    
    use My::ExtDirect::Published::Module::Foo;
    use My::ExtDirect::Published::Module::Bar;
    
    my %headers = (   # Optional CGI headers
        -charset => 'iso-8859-1',
        -nph     => 1,
        -cookie  => CGI::Cookie->new(
            -name  => 'foo',
            -value => 'bar',
        ),
    );
    
    my $direct = CGI::ExtDirect->new();
    
    print $direct->route(%headers);

=head2 Event polling service

In C</cgi-bin/poll.cgi>:

    use CGI::Simple;
    use CGI::ExtDirect;
    
    use My::ExtDirect::Event::Provider1;
    use My::ExtDirect::Event::Provider2;
    
    # CGI::Simple is supported as well
    my $cgi = CGI::Simple->new;
    
    # do something with $cgi but do not print headers
    ...
    
    my $direct = CGI::ExtDirect->new(cgi => $cgi);
    
    print $direct->poll();

=head1 DESCRIPTION

=for readme continue

This module provides an L<RPC::ExtDirect> gateway implementation for
CGI compatible Web server environments. This includes both traditional
CGI scripts that start up anew for each HTTP request, as well as more
modern CGI environments in which a script is started once and then
persists through the lifetime of a server process.

CGI::ExtDirect can be used wth Perl versions 5.6 and newer with many
Web servers; it was tested successfully with Apache/mod_perl, pure
Perl server based on L<HTTP::Server::Simple> (L<RPC::ExtDirect::Server>),
and various other HTTP server environments.

If you are not familiar with Ext.Direct, more information can be found in
L<RPC::ExtDirect::Intro>.

=for readme stop

=head1 CGI SCRIPTS

If your environment requires using old fashioned standalone CGI scripts,
CGI::ExtDirect is fine with that. In fact, it is tested in exactly this
kind of environment to ensure it will work properly.

You need to create at least two CGI scripts: API generator, and request
router. The third Event provider script is optional, and is only needed
if you plan to use event polling capabilities of Ext.Direct. The examples
provided in L</SYNOPSIS> can be used as starting points for further
customization. See also the L<examples|/EXAMPLES> packaged with