NAME

SYNOPSIS

    use RPC::ExtDirect::Config;
    use RPC::ExtDirect::API;
    
    my $config = RPC::ExtDirect::Config->new(
        namespace    => 'MyApp',
        router_path  => '/router',
        poll_path    => '/events',
        remoting_var => 'MyApp.REMOTING_API',
        polling_var  => 'MyApp.POLLING_API',
    );
    
    my $api = RPC::ExtDirect::API->new_from_hashref(
        config   => $config,
        api_href => {
            before => 'MyApp::Util::global_before_hook',
            after  => 'MyApp::Util::global_after_hook',
            
            'MyApp::Server::Foo' => {
                before  => 'MyApp::Server::Foo::package_before_hook',
                
                action => 'MyApp.Server.Foo', # JavaScript style with dots
            
                methods => {
                    foo => {
                        len => 1,
                    },
                    bar => {
                        params => ['foo', 'bar'],
                    },
                    baz => {
                        params => ['frobbe', 'throbbe'],
                        metadata => {
                            params => ['mymse', 'qux'],
                        }
                    }
                }
            }
        }
    );

DESCRIPTION

The Ext.Direct API declaration is in fact a tree-like data structure (an Object in JavaScript parlance) containing description of Actions and Methods available to the client. This data structure is encoded in JavaScript code statement that is regenerated dynamically every time it is requested. No caching is used at this time.

ACTIONS AND METHODS

    Foo.Bar.Baz.do_foo(...);

COMPILE VS RUN TIME DEFINITION

Both of these ways have their advantages and disadvantages. Using the "ExtDirect" attribute, it's easier to keep definitions closer to the actual code so that when the code changes, its definition can be remembered to be changed as well. Also this approach is very easy to use and start with; just add the attribute to your code, and you're good to go. Also, the attribute syntax is expressive enough to be self-documenting, so often no other API documentation is needed.

On the other hand, for larger and more centralized projects it may be easier to keep all API definitions in one place rather than spread over dozens of packages. Besides easier maintenance, using dynamic approach allows having more than one active API object at a given time, possibly implementing different APIs tailored for usage patterns of a particular application.

Note that these two methods are not mutually exclusive, but it is not recommended to mix them unless you are ready to deal with ensuing timing issues. You've been warned.

DEFINING METHODS STATICALLY

    sub foo : ExtDirect(...) {}

Note that there can be no space between the "ExtDirect" attribute name and the opening parens; also in Perls older than 5.12, the attribute statement cannot span multiple lines, i.e. the whole "ExtDirect(...)" construct should fit in one line. This is due to limitations in Perl code parser.

Inside the parentheses, one of the following mutually exclusive option keywords is mandatory:

"n"

The number of ordered arguments this Method accepts. This form is considered obsolete, use "len" keyword instead. If "n" is used, this keyword should always come first in the list:

    sub foo : ExtDirect(1, ...) {} # right
    sub bar : ExtDirect(..., 1) {} # wrong
    sub baz : ExtDirect(0)      {} # right
    

"len"

The more preferred way to define an Ordered Method. This keyword should be followed by the number of the parameters accepted by the Method:

    sub foo : ExtDirect(len => 1)      {} # right
    sub bar : ExtDirect(..., len => 1) {} # also right
    sub baz : ExtDirect(len => 0)      {} # right again
    

"params"

A list of the named parameters this method accepts. Since a Method can be either ordered or named, this and above options are mutually exclusive. This keyword should be followed by an arrayref with the parameter names, possibly empty:

    sub foo : ExtDirect(params => ['foo', 'bar', ...], ...) {}
    sub bar : ExtDirect(params => [], ...)                  {}
    

"formHandler"

This option defines the Method as a Form Handler.

"pollHandler"

This option defines the Method as a Poll Handler.

Having more than one calling convention keyword in the Method definition is not supported and will lead to undefined behavior.

Besides the mandatory calling convention keyword, there are optional Method attributes in hash-like "key => value" form. See more in "new" in RPC::ExtDirect::API::Method.

DEFINING METHODS DYNAMICALLY

    my $api = RPC::ExtDirect->get_api();
    $api->init_from_hashref({
        'MyApp::Server::Foo' => {
            methods => {
                ordered_method => {
                    len => 1,
                },
                named_method => {
                    params => [qw/ foo bar /],
                    strict => !1,
                },
                form_handler => {
                    formHandler => 1,
                },
                poll_handler => {
                    pollHandler => 1,
                },
            },
        },
    });

Keywords and options are mostly the same as with the static definition; refer to "new" in RPC::ExtDirect::API::Method for details.

GLOBAL API TREE INSTANCE

Versions 1.x and 2.x of RPC::ExtDirect used package global variables to hold this information; version 3.0 is using a global RPC::ExtDirect::API object instead. This object is held in a private variable and can be retrieved by the get_api method:

    my $global_api = RPC::ExtDirect->get_api;

This API object holds an instance of RPC::ExtDirect::Config with a set of options used to configure the API object behavior. This Config instance can be retrieved to set options directly:

    my $cfg = RPC::ExtDirect->get_api->config;
    $cfg->option1('foo');
    $cfg->option2('bar');

Since the API object is a normal object, and the config method is a normal accessor, it is possible to replace that Config instance with a new one. However this may result in a loss of statically defined Config options, and is not recommended. Instead, use import package sub to configure the global API when using static API definitions.

The global API instance is used by default to generate the API declaration requested by the client side, and for dispatching remoting calls from the client side. If you prefer more control over the API tree, create the API object explicitly as shown in the SYNOPSIS, and pass it to the gateway object. Refer to the actual gateway documentation for details.

Because attribute parsing happens at package compilation time, it is hard to predict the order in which the methods will be processed. To provide some help with debugging, RPC::ExtDirect will throw an error if you are trying to redefine a Method; usually that means a mistake has been made somewhere.

API CONFIGURATION

An example of the new dynamic configuration is available in the "SYNOPSIS" above. This is the preferred way of configuring the API in large complex applications; it allows keeping the whole API definition in one place instead of distributed among the packages. It is also possible to define more than one API this way, for publishing to different clients.

The static configuration has been available since version 1.0 and will be supported going forward. This way it is possible to configure the API variables at compile time:

 use RPC::ExtDirect::API         namespace    => 'myApp',
                                 router_path  => '/router',
                                 poll_path    => '/events',
                                 remoting_var => 'Ext.app.REMOTING_API',
                                 polling_var  => 'Ext.app.POLLING_API',
                                 auto_connect => 0,
                                 no_polling   => 0,
                                 before       => \&global_before_hook,
                                 after        => \&global_after_hook,
                                 ;

Under the hood, the above code will set specified options on the Config instance held in the global API object.

API CONFIGURATION OPTIONS

"namespace"

Declares the namespace your Actions will reside in. To call the Methods on client side, you will have to qualify them with namespace: "namespace.Action.Method", e.g.: "myApp.Foo.Bar"

"router_path"

URI for Ext.Direct Router calls. For the CGI environment, this should be the name of the CGI script that provides the API declaration; for more sophisticated environments it is an anchor for the specified PATH_INFO.

"poll_path"

URI for Ext.Direct Event Provider calls. Client side will poll this URI periodically, hence the name.

"remoting_var"

By default, Ext.Direct API declaration for remoting (forward) Methods is stored in Ext.app.REMOTING_API variable. If for any reason you would like to change that, do this by setting remoting_var.

Note that in production environment you would probably want to use a compiled version of the JavaScript application that consist of one big JavaScript file. In this case, it is recommended to include API declaration as the first script in your index.html and change the remoting API variable name to something like "EXT_DIRECT_API". Default variable name depends on Ext.app namespace being available by the time Ext.Direct API declaration is downloaded, which is often not the case.

"polling_var"

Ext.Direct does not provide a standard namespace for Event Providers to be published in. For similarity with "remoting_var", "Ext.app.POLLING_API" name is used to declare an Event Provider so that it could be used on the client side without having to hardcode any URIs explicitly.

"Ext.app.POLLING_API" configuration will only be published to the client side if there is at least one pollHandler Method defined in the Ext.Direct API.

Note that the same variable naming caveat applies here as with "remoting_var".

"no_polling"

Explicitly prohibit the API declaration from containing a "polling_var" definition. This will suppress publishing Event Providers even if there are any pollHandler methods in the actual API.

This option can be useful for testing.

"auto_connect"

This option is deprecated and should not be used anymore.

"before"

Global "before" hook. See "HOOKS" in RPC::ExtDirect.

"instead"

Global "instead" hook. See "HOOKS" in RPC::ExtDirect.

"after"

Global "after" hook. See "HOOKS" in RPC::ExtDirect.

API OBJECT INTERFACE

"HOOK_TYPES"

Class/instance method. Returns the list of supported hook types. See "HOOKS" in RPC::ExtDirect for more information.

Accepts no arguments.

"new"

Constructor. Returns a new RPC::ExtDirect::API object with an empty API tree. Accepts named arguments in a hash.

Parameters:

"new_from_hashref"

Constructor. Returns a new RPC::ExtDirect::API object with an API tree initialized from the api_href argument. Accepts named arguments in a hash.

Parameters:

"init_from_hashref"

Instance method. Initializes the API tree in the object from the passed hashref with API definitions. This method will be called internally by "new_from_hashref".

Accepts only one ordered argument:

"get_remoting_api"

Instance method. Returns stringified API declaration for the current API tree contained in the object. Accepts named arguments in a hash.

Parameters:

"actions"

Instance method. Returns the list of names for all Actions defined in the API tree.

"add_action"

Instance method. Adds or replaces an Action in the current API tree. Accepts named arguments in a hash.

Parameters:

"get_action_by_name"

Instance method. Returns the Action object for the corresponding action name, or "undef". Accepts one ordered argument (action name).

"get_action_by_package"

Instance method. Returns the Action object for the corresponding package, or "undef". Accepts one ordered argument (package name).

"add_method"

Instance method. Add a new Ext.Direct Method object to the current API tree, creating an Action for it if necessary. Accepts named arguments in a hash.

Parameters:

"get_method_by_name"

Instance method. Return the Method object for the corresponding Action and Method name, or "undef". Accepts two ordered arguments:

"add_hook"

Instance method. Adds a new Hook object to the current API tree. Accepts named arguments in a hash.

For global hooks, only "type" and "code" parameters are needed. For Action level hooks, either "package" or "action" parameter is needed as well. For Method level hooks, the "method" parameter is required in addition to the above.

If api_hook_class Config option is not set, the default RPC::ExtDirect::API::Hook class will be used to instantiate the Hook object.

Parameters:

"get_hook"

Instance method. Returns the Hook object for given criteria, or "undef". Accepts named arguments in a hash.

When looking up Method level hook, "action" or "package" parameter is mandatory, as well as the "method" name and hook "type". For Action level hooks, "action" or "package" is required to look up the Action, and "type" for the hook. For global hooks, only "type" is required.

Parameters:

"get_poll_handlers"

Instance method. Returns the list of Method objects for all Poll handlers for every Action in the current API tree.

This method does not accept any arguments.

ACCESSOR METHODS

"config"

Return the current RPC::ExtDirect::Config instance held in this API object, or set a new one.

"before"

Return the global "before" Hook object if set, or assign a new one. See "HOOKS" in RPC::ExtDirect for more information.

"instead"

Return the global "instead" Hook object if set, or assign a new one. See "HOOKS" in RPC::ExtDirect for more information.

"after"

Return the global "after" Hook object if set, or assign a new one. See "HOOKS" in RPC::ExtDirect for more information.

SEE ALSO