NAME

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

SYNOPSIS

API definition

In api.cgi:

    use CGI::ExtDirect;
    
    use My::ExtDirect::Published::Module::Foo;
    use My::ExtDirect::Published::Module::Bar;
    
    my $direct = CGI::ExtDirect->new();
    
    print $direct->api();      # Prints full HTTP response

Routing requests

In router.cgi:

    use CGI::ExtDirect;
    
    use RPC::ExtDirect::API api_path     => '/extdirect_api',
                            router_path  => '/extdirect_router',
                            poll_path    => '/extdirect_events',
                            remoting_var => 'Ext.app.REMOTING_API',
                            polling_var  => 'Ext.app.POLLING_API',
                            namespace    => 'myApp',  # Defaults to empty
                            auto_connect => 0,
                            no_polling   => 0,
                            debug        => 0;
    
    use My::ExtDirect::Published::Module::Foo;
    use My::ExtDirect::Published::Module::Bar;
    
    my $debug   = 1;  # Optional debugging flag
    my %headers = (   # Optional CGI headers
        -charset => 'iso-8859-1',
        -nph     => 1,
        -cookie  => $cookie,
    );
    
    my $direct = CGI::ExtDirect->new({ debug => $debug });
    
    print $direct->route(%headers);    # Prints full HTTP response

Providing Event polling service

In poll.cgi:

    use CGI;
    use CGI::ExtDirect;
    
    use My::ExtDirect::Event::Provider1;
    use My::ExtDirect::Event::Provider2;
    
    my $debug = 1; 
    my $cgi   = CGI->new;
    
    # do something with $cgi but do not print headers
    ...
    
    my $direct = CGI::ExtDirect->new({ cgi => $cgi, debug => $debug });
    
    print $direct->poll();

DESCRIPTION

This module provides RPC::ExtDirect gateway implementation for CGI environment. It can be used wth Perl versions 5.6 and newer in about any environment; it was tested successfully with Apache, pure Perl server based on HTTP::Server::Simple and various other HTTP servers.

You can change some default configuration options by passing relevant parameters like shown above. For the meaning of parameters, see RPC::ExtDirect::API documentation.

Note that Ext.Direct specification requires server side implementation to return diagnostic messages only when debugging is explicitly turned on. This is why debug flag defaults to 'off' and CGI::ExtDirect returns generic error messages that do not contain any details as to where and what error has happened.

METHODS

new($arguments)

Creates a new CGI::ExtDirect object. $arguments is an optional hashref with the following options: cgi - Instantiated CGI or similar object. debug - Debug flag, defaults to off. See the note above.

api(%headers)

Creates JavaScript code with server side Action and Method declarations and prints it to default output handle along with HTTP headers. You can specify additional headers in CGI format: NPH, cookies, whatever; they will be passed to CGI->header() which is used to form HTTP header part.

Some of the headers, namely Content-Type, Content-Length and Status, are always overridden to provide client side with adequate response. Default Charset is UTF-8; however if you pass -charset header CGI::ExtDirect will honor it. It is implied that you should only do this when you clearly know what you are doing.

Other headers are passed along to CGI->header() unchanged.

route(%headers)

Accepts Ext.Direct requests, dispatches them, collects results and prints them back as serialized stream.

%headers are treated the same way as in api(), see above.

poll(%headers)

Queries Event provider Methods registered with RPC::ExtDirect as pollHandlers for events, collects them and returns back serialized stream.

%headers are treated the same way as in api(), see above.

DEPENDENCIES

CGI::ExtDirect is dependent on the following modules: RPC::ExtDirect, JSON, Attribute::Handlers.

SEE ALSO

For explanation of RPC::ExtDirect attributes, see RPC::ExtDirect. For more detail on API options, see RPC::ExtDirect::API.

For more information on Ext.Direct API see specification: http://www.sencha.com/products/extjs/extdirect/ and documentation: http://docs.sencha.com/ext-js/4-0/#!/api/Ext.direct.Manager.

See included Ext JS examples for ideas on what Ext.Direct is and how to use it in CGI applications.

ACKNOWLEDGEMENTS

The tiny but CGI-capable HTTP server used to provide working examples is (c) 2002-2004 by Hans Lub, <hlub@knoware.nl>. It is called p5httpd and can be found here: http://utopia.knoware.nl/~hlub/rlwrap/

BUGS AND LIMITATIONS

There are no known bugs in this module. Use CPAN RT to report bugs (better way) or just drop me an e-mail. Patches are welcome.

AUTHOR

Alexander Tokarev <tokarev@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2011-2012 Alexander Tokarev.

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

Included Ext JS examples are copyright (c) 2011, Sencha Inc. Example code is used and distributed under GPL 3.0 license as provided by Sencha Inc. See http://www.sencha.com/license. Ext JS is available for download at http://www.sencha.com/products/extjs/

cpanm CGI::ExtDirect

perl -MCPAN -e shell
install CGI::ExtDirect