Exposing module services in a Page Engine-based application

[flongo]

1. Requirements

Suppose you have two module controller instances, that we will call A and B, inside your page engine applications. They can be either common modules (declared in the site configuration) or page specific modules (declared in a page definition).

Sometimes A needs to call a method defined in B. This is currently impossible. Even in a standard application using Aria Templates (without the page engine), when two modules are added as sub-modules of the same parent, they cannot directly call methods on each other.

When module controllers are used in a page engine context, they can only share portions of their data model through the binding mechanism that is provided by the framework (http://www.ariatemplates.com/usermanual/...bindings), which allows to share module data in the application data.
This possibility sometimes inspires developers to inject the instance of module controller in the application data, so that the methods provided by it become public. This is somehow a hack.

It would be convenient to also have a syntax to expose certain methods of a sub-module to all the others.

2. Use Cases

Suppose you have a common module that performs a login. It is declared in the site configuration

{
    ...
    commonModules: {
        login : {
            classpath : "my.Login"
        }
}

and it implements a method (declared in its public interface)

loginMethod : function (credentials, cb) {
    ...
}

Another page-specific module declared in the "SEARCH" page

{
    pageComposition : {
        ...
        modules : {
            "search" : {
                classpath : "my.Search"
            }
        }
    },
    pageId : "SEARCH"
}

wants to be able to access the "loginMethod" function of the login module.

3. Technical solution

The suggested solution consists in a syntax to expose module controller methods as "services". Considering the same example as above, suppose you want to expose the "login" method of the login module. The syntax would be

{
    ...
    commonModules: {
        login : {
            classpath : "my.Login",
            services : {
                "globalLogin" : "loginMethod"
            }
        }
}

Suppose now that the "serach module on the "SEARCH" page needs to access the "loginMethod" function of the login controller. this is the suggested syntax:

Aria.classDefinition({
    $classpath : "my.Search",
    ...
    $prototype : {
        init : function (initArgs, cb) {
            // store the page engine instance automatically injected in the initArgs
            this._pageEngine = initArgs.pageEngine;
            ...
            this.$callback(cb);
        },

        search : function () {
            var services = this._pageEngine.getServices();
            var credentials = {...};
            var callback = {...};
            services.globalLogin(credentials, callback);
        }
    }
});

So the idea is to

• Implement a "getServices" method in class "aria.pageEngine.PageEngine". It returns an object containing all exposed services.
• Services will be accessible by the key that was used in the module declaration ("globalLogin" in the above example).
• Both common and page-specific modules can expose services.
• If a module exposes a service that does not correspond to a method in its public interface, an error should be logged by the framework.
• If a module exposes a method that already exists, a warning should be logged by the framework.
  

4. History

18/02/2014 Specs creation - Francesco Longo