xone_amd.md

Xone Asynchronous Module Definition (AMD)

Note: Work in progress.

API Overview

Global Methods:

• define: function(namespace<, dependencies>, factory<, bind>)
• require: function(namespace<, callback, bind>)
• install: function(namespace<, target>)
• export: function(namespace<, target>)
• build (in progress)
• convert (in progress)
• undefine: function(namespace)
• run: function(namespace<, async, ordered>)

Note: The amd methods are only available in local development environments. When performing xone build compilation/build, all amd modules are resolved and converted, the amd library itself is removed completely, therefore access on require or define by example isn't possible anymore (e.g. in production releases). Read further notes at the bottom of this site.

Define

Defines a function/value MyLib.foo:

define("MyLib.foo", function(){

    return function(str){

        alert(str);
    };
});

Defines a function/value MyLib.foo which includes MyLib.foo:

define("MyLib.bar", "MyLib.foo", function(foo){

    return function(str){

        foo("Hello World"); // --> "Hello World"
    };
});

Defines a function/value MyLib.foobar which includes multiple dependencies:

define("MyLib.foobar", ["MyLib.foo", "MyLib.bar"], function(foo, bar){

    return function(){

        foo("Hello World"); // --> "Hello World"
        bar(); // --> "Hello World"
    };
});

Defines a function/value MyLib.test which has custom this injected:

define("MyLib.test", "MyLib.foobar", function(foobar){

    return function(){

        this.setTimeout(foobar); // --> "Hello World" x 2
    };
    
}, /* pass this: */ window);

define("MyLib.run", function(){

    return function(){

        this(); // --> "Hello World" x 2
    };
    
}, /* require this: */ "MyLib.test");

Defines an object MyLib.object:

define("MyLib.object", ["MyLib.foo", "MyLib.bar"], function(_foo, _bar){

    return {

        foo: _foo,
        bar: _bar
    };
});

Defines an simple array MyLib.array:

define("MyLib.array", function(){

    return [];
});

Define constants:

define("MyLib.constString", "MY_CONST_STRING");

define("MyLib.constNumber", 3.14);

define("MyLib.constArray", [0, 1, 2, 5]);

define("MyLib.constEnum", {

    'r': 255,
    'g': 255,
    'b': 255
});

Require

Require a defined function/value:

require("MyLib", function(MyLib){
            
    MyLib.foo();
    MyLib.bar();
});

Require multiple defined functions/values:

require(["MyLib", "MyNewLib"], function(MyLib, MyNewLib){
            
    MyLib.foo();
    MyNewLib.bar();
});

Require a reference/namespace by:

var MyNewLib = require("MyLib");
MyNewLib.foo();

require("MyLib").foo();

Usage of plain require() is one way to force loading "hidden" dependencies during build process, e.g.:

require([
            
    "MyLib.foo",
    "MyLib.bar"
]);

Note: When passing an array wihtout a callback function, require() returns undefined.

Run

Executes defined functions in order (without any parameters):

run([
            
    "MyLib.foo",
    "MyLib.bar"
]);

Executes defined functions asynchronously in non-strict order (without any parameters):

run([
            
    "MyLib.foo",
    "MyLib.bar"
    
], /* async: */ true);

Executes defined functions asynchronously in strict order (without any parameters):

run([
            
    "MyLib.foo",
    "MyLib.bar"
    
], /* async: */ true, /* ordered: */ true);

Install

Install a definition globally:

// installs MyLib to window.MyLib when no 2nd parameter was passed
install("MyLib");

// now you can access:
MyLib.foo();

Install to a custom object:

// installs MyLib to MyNewLib
install("MyLib", MyNewLib);

// now you can access:
MyNewLib.MyLib.foo();

Export

Export a definition to an existing object/namespace:

// exports all methods of MyLib to MyNewLib
export("MyLib", MyNewLib);

// foo is now a member of MyNewLib:
MyNewLib.foo();

Important Notice

All AMD calls should be placed in global scope or at least have to be executed/evaluated in place (supports async). That may differ from other AMD libraries. The reason for this restriction is simply: the final build does not need any AMD directives anymore so it does not include AMD code.

Therefore inner calls are only possible, if their holders (functions) are executed/evaluated anywhere in place e.g.:

if(ENV === 'production') defineFlag() : defineFlagDev();

function defineFlag(){

    define("MyLib.flag", true);
}

function defineFlagDev(){

    var flag = require("MyConfig.flag");
    define("MyLib.switch", flag);
}

Usually this will fail in production builds:

define("MyLib.foo", function(){

    return function(str){

        define("MyLib.bar", function(){
        
            return function(str){
        
                alert(str);
            };
        });
    };
});

When you call require("MyLib.foo"); somewhere in place, the example from above should work, because the inner definition will executes during dependency evaluation runtime.

By the way this also works fine, but those usage is not very common:

define("MyLib.foo", function(){

    define("MyLib.bar", function(){
        
        return function(str){
    
            alert(str);
        };
    });

    return require("MyLib.bar");
});