NAME

Plack::Middleware::ExtDirect - RPC::ExtDirect gateway for Plack

SYNOPSIS

In your plackup, before Plack::Runner->run():

 use My::Server::Side::Class;
 use My::Server::Side::Class2;

In your app.psgi:

 my $app = sub { ... };
 
 builder {
    enable 'ExtDirect', 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,
                        before       => \&global_before_hook,
                        after        => \&global_after_hook,
                        ;
    $app;
 }

DESCRIPTION

This module provides RPC::ExtDirect gateway implementation for Plack environment. It is packaged as standard Plack middleware component suitable for use with Plack::Builder.

You can change some default configuration options by passing corresponding 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 RPC::ExtDirect returns generic error messages that do not contain any details as to where and what error has happened.

CAVEATS

Attribute handlers

For RPC::ExtDirect attribute handlers to work properly, modules that expose ExtDirect Methods should be loaded at compile time. On the other hand, Plack::Runner loads and compiles code in *.psgi at runtime, and that breaks attribute magic dust. To avoid this, make sure you load all modules that provide Ext.Direct functionality - including Event providers - before Plack::Runner starts. The easiest way to do this is to copy plackup script and modify it a little to use all relevant modules in it.

See included code examples to see how it works.

Environment object

For Plack Ext.Direct gateway, the environment object is based on Plack::Request. While it does provide the same methods described in "ENVIRONMENT OBJECTS" in RPC::ExtDirect, behavior of these methods can be slightly different from CGI environment. For example, $env->http() in CGI will return the list of both environment variables and HTTP headers in upper case, while the same $env->http() in Plack application will return only HTTP headers as they were defined in HTTP spec. To avoid problems, always find the actual header name first and then use it:

    my ($header) = grep { /^Content[-_]Type$/i } $env->http();
    my $value    = $env->http($header) if $header;
    
    ...

DEPENDENCIES

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

SEE ALSO

For more information on core functionality see RPC::ExtDirect.

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 ExtJS examples for ideas on what Ext.Direct is and how to use it.

BUGS AND LIMITATIONS

There are no known bugs in this module. To report bugs, use github RT (the best way) or just drop me an e-mail. Patches are welcome.

AUTHOR

Alexander Tokarev <tokarev@cpan.org>

ACKNOWLEDGEMENTS

I would like to thank IntelliSurvey, Inc for sponsoring my work on version 2.0 of RPC::ExtDirect suite of modules.

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 ExtJS 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

cpanm Plack::Middleware::ExtDirect

perl -MCPAN -e shell
install Plack::Middleware::ExtDirect