Noder-js integration in Aria Templates

The next non-backward-compatible release of Aria Templates (1.6.1) will contain an important internal re-factoring: the replacement of its current loader by a CommonJS-compatible one: noder-js.

This article describes what this change will bring. For most applications, migrating to that new release should be straightforward. However, as this is a big internal change, a beta version of Aria Templates is already available so that you, dear Aria Templates users, can test it and report bugs or any other remark you may have. Then, bug fixes and other improvements can hopefully be integrated in the 1.6.1 release.

Update (02/07/2014): Aria Templates 1.6.1 is now published and should be used instead of the beta version. The examples and the last section of this article were updated accordingly.

CommonJS in the browser

noder-js allows to run CommonJS modules in the browser.
As the main file of Aria Templates 1.6.x fully includes noder-js itself, all the features of noder-js are automatically available.

For example, suppose you have a JavaScript file called x/y/MyMainClass.js, which uses the CommonJS syntax and has the following content:

exports.main = function () {
   alert("Hello world!");
};

You can load and use the previous file from your HTML page with the following piece of code:

<!-- Aria Templates is supposed to be included in the page as usual, like this: -->
<script type="text/javascript" src="aria/ariatemplates-1.6.1.js"></script>

<!-- It is now possible to have a script with type "application/x-noder" and use require inside it:  -->
<script type="application/x-noder">
   require("x/y/MyMainClass").main(); // This will load MyMainClass.js and execute the exported main method
</script>
<!-- The beta version of Aria Templates 1.6.x expected type "noder" instead of "application/x-noder" -->
<!-- Please now use type="application/x-noder" (for Aria Templates >= 1.6.1, noder-js >= 1.5.0). -->

As described in the CommonJS modules/1.0 specifications, a module can export anything on the exports object (or it can even replace this object with another one by setting module.exports), and this object can then be retrieved from another module by calling require. The path used in the call to require can be either absolute (from the configured root directory) or relative (to the module calling require).

For more information about the features provided by noder-js, you can have a look to the noder-js website. It is good to know that noder-js also includes a small promise library, which is used internally by the loader itself and can also be used by applications if needed.

Compatibility with current classes

The integration of noder-js with Aria Templates is done in such a way that current (non-CommonJS) Aria Templates classes (using for example $dependencies), can be loaded without any change. So, do not worry, there will be no need to change all your files to upgrade to version 1.6.x.

It is possible both to require non-CommonJS Aria Templates classes from CommonJS modules and to depend on CommonJS modules from non-CommonJS Aria Templates classes.

However, mixing both syntaxes in the same module, which means using both require and $dependencies in the same file, is not supported.

Aria Templates detects the format (either CommonJS or non-CommonJS) with the following rule: a file is considered using the CommonJS syntax if it either contains calls to require or if it does not contain any Aria definition (recognized by a call to Aria.classDefinition or Aria.interfaceDefinition or Aria.beanDefinitions or Aria.tplScriptDefinition).

This means that, as soon as you want to call require from a file, you have to switch to the CommonJS syntax for that whole file. Each file can be converted independently of any other file.

Here is an example of a non-CommonJS Aria Templates class:

Aria.classDefinition({
    $classpath : "x.y.MyClass",
    $dependencies : ["a.b.MyDependency1", "x.y.MyDependency2"],
    $extends : "x.MyBaseClass",
    $prototype : {
        myMethod : function (myParam) {
            return {
                myDep1 : new a.b.MyDependency1(myParam),
                myDep2 : new x.y.MyDependency2(myParam)
            }
        }
    }
});

Here is the same class converted to the CommonJS syntax:

var Aria = require("ariatemplates/Aria");
var aBMyDependency1 = require("a/b/MyDependency1");
var xYMyDependency2 = require("./MyDependency2");
var xMyBaseClass = require("../MyBaseClass");
module.exports = Aria.classDefinition({
    $classpath : "x.y.MyClass",
    $extends : xMyBaseClass,
    $prototype : {
        myMethod : function (myParam) {
            return {
                myDep1 : new aBMyDependency1(myParam),
                myDep2 : new xYMyDependency2(myParam)
            }
        }
    }
});

To achieve this conversion automatically, the at-noder-converter tool is provided.

The syntax of templates (of any kind: .tpl, .tpl.css, .tml, .cml and .tpl.txt) is not affected in the scope of version 1.6.1. It is not (yet) possible to use require inside them. It may be implemented in a future release, but, currently, the only way to declare a dependency in a template is to use the $dependencies syntax. However, the associated script can use require if it uses the CommonJS syntax.

In the same way, resources definitions are not affected either in the scope of 1.6.1: it is not supported to use module, exports or require with Aria.resourcesDefinition.

Non-backward compatible changes

Even if most of the migration to Aria Templates 1.6.x should be straightforward, there are some small non-backward compatible changes. Mainly, the class manager (aria.core.ClassMgr) and all class loaders are replaced with noder-js, so most of their methods are no longer usable.

The integration of noder-js does not affect the download manager (aria.core.DownloadMgr) which is still used along with aria.core.IO and IO transports, to request files from the server.

Here is the precise list of non-backward compatible changes:

  • aria.core.ClassMgr can no longer be used for class loading. Its classComplete event is no longer raised. Its methods no longer work, except getBaseLogicalPath and unloadClass.
  • aria.core.ClassLoader, aria.core.CmlClassLoader, aria.core.CSSClassLoader, aria.core.JSClassLoader, aria.core.ResClassLoader, aria.core.TmlClassLoader and aria.core.TxtClassLoader are no longer usable.
  • It is no longer possible to create an instance of aria.core.TplClassLoader. Its static methods still work, though (they are still used internally by the framework).
  • aria.core.Cache.content.classes no longer exists.
  • In case of errors in the class definition, Aria.classDefinition raises exceptions instead of only logging errors.
  • Aria.eval no longer returns the last evaluated expression. The evaluated code is wrapped in a function such that it is possible to call return with the desired return value. For example:
    var one = Aria.eval("1")

    // the previous line has to be replaced, in Aria Templates 1.6.x, by:

    var one = Aria.eval("return 1").
  • The build process of applications which create a custom packaging of the Aria Templates framework has to be updated to support version 1.6.x of Aria Templates (those changes will be detailed later).

How to test the 1.6.1 version right now?

Aria Templates 1.6.1 is now available.

  • The simplest way to try the 1.6.1 version is through our CDN server, by using the following script tag in your HTML page. For more information about how to use the CDN, you can have a look to this page.
    <script type="text/javascript" src="http://cdn.ariatemplates.com/at1.6.1.js"></script>

    Update (02/07/2014): Version 1.6.1 solves the following issue which was present in 1.6.0-beta versions:

    Note that if you use a question mark to pass parameters to the CDN (for example dev or skin), they are currently also interpreted by noder-js as the main file to be executed (instead of the default aria/bootstrap file). This is a known issue which will be solved later. As a work-around, you can use the following syntax so that noder-js ignores the query string and still uses aria/bootstrap as the main file to be executed:

    <script type="text/javascript" src="http://cdn.ariatemplates.com/at1.6.0-beta.3.js?dev&skin">
    {
       main: "aria/bootstrap"
    }
    </script>
  • If you want to get the 1.6.1 version as a zip file, you can go to our download page.
  • If you are using node.js and npm, you can also get the 1.6.1 version from the npm repository, by executing, from the command line:
    npm install ariatemplates@1.6.1

    Then you can configure your web server to serve files from node_modules/ariatemplates/build/target/production (for the packaged version) or from node_modules/ariatemplates/build/target/bootstrap (for the unpackaged version).

  • The source code is available in the v1.6.1 tag of our GitHub repository. To clone the repository and build the 1.6.1 version, you can run, from the command line:
    git clone -b v1.6.1 https://github.com/ariatemplates/ariatemplates.git
    cd ariatemplates
    npm install

    This builds the packaged version in build/target/production and the unpackaged one in build/target/bootstrap

If you have any question or remark, do not hesitate to leave a reply below or to contact us through our forum. Your feedback is welcome. Thank you in advance. Happy testing!

3 responses on “Noder-js integration in Aria Templates

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>