To be technically correct, the Uize.module method strictly takes just one parameter that is an object. This object should contain a number of properties, as shown in the syntax declaration. So all the "parameters" described below are actually properties of this one object bundle that the method accepts. For simplicity's sake, we will refer to these properties as parameters.

[host].[guest]

required:'Uize.Node,Uize.Color,Uize.Data,Uize.Fade'

required:['Uize.Node','Uize.Color','Uize.Data','Uize.Fade']

required:[
  'Uize.Node',
  'Uize.Color',
  'Uize.Data',
  'Uize.Fade'
]

A subclass module is a module of code intended to create a subclass. When declaring a subclass module, the superclass can be specified using the optional superclass parameter. If no superclass is specified, then the "host" is assumed to be the superclass. The builder function should expect to receive one parameter, being an object reference to the superclass. The builder function should return an object reference to the subclass it creates, so this can be assigned to the "host".

EXAMPLE 1

Uize.module ({
  name:'Uize.Widget.MyWidgetClass',
  builder:function (_superclass) {
    /*** Object Constructor ***/
      var
        _class = _superclass.subclass (
          /*
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          */
        ),
        _classPrototype = _class.prototype
      ;
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
    return _class;
  }
});

In the example above, the widget class Uize.Widget.MyWidgetClass is a subclass of Uize.Widget. It has a simple implementation and so doesn't have any requirements beyond the implicit requirement of the Uize.Widget superclass.

EXAMPLE 2

Uize.module ({
  name:'MyNamespace.MyWidgetClass',
  superclass:'Uize.Widget',
  builder:function (_superclass) {
    /*** Object Constructor ***/
      var
        _class = _superclass.subclass (
          /*
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          */
        ),
        _classPrototype = _class.prototype
      ;
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
    return _class;
  }
});

In the example above, the class MyNamespace.MyWidgetClass is not a subclass of the module MyNamespace. Rather, MyNamespace is merely the "host" for the MyWidgetClass property, and MyNamespace.MyWidgetClass is a means of referencing the class in code. Therefore, the fact that MyNamespace.MyWidgetClass is a subclass of Uize.Widget needs to be declared explicitly using the optional superclass parameter.

EXAMPLE 3

Uize.module ({
  name:'MyNamespace.MyWidgetClass',
  superclass:'Uize.Widget',
  required:[
    'Uize.Node',
    'Uize.Fade'
  ],
  builder:function (_superclass) {
    /*** Object Constructor ***/
      var
        _class = _superclass.subclass (
          /*
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          */
        ),
        _classPrototype = _class.prototype
      ;
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
    return _class;
  }
});

In the above example, the implementation of the MyNamespace.MyWidgetClass module has become more complex and it now requires the additional modules Uize.Node and Uize.Fade. Notice, however, that the modules MyNamespace and Uize.Widget (the host and superclass, respectively) are not in the required list, since their requirement is implicit.

A package in the UIZE Framework is often just a collection of helper static methods or data properties, and is not derived from a superclass.

So, when declaring packages, there is no meaning to the concept of superclass. This means that the optional superclass parameter would not be applicable. Additionally, the value that is passed as a parameter to the specified builder function would not be valuable, and so your builder function can simply have no parameters.

EXAMPLE

Uize.module ({
  name:'Uize.Node',
  builder:function () {
    var _package = function () {};
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
    return _package;
  }
});

IMPORTANT

In the example above, notice how the package object being built by the builder function is initialized as an anonymous function. For the benefit of the inheritance mechanism of the UIZE Framework, the package should be built upon a function and not an object. Making the package an object would result in deep cloning in certain cases of subclassing, and this is not desirable for performance reasons.

Extension modules are modules of code that extend on the implementation of a class or package.

EXAMPLE

Uize.module ({
  name:'Uize.Widget.Bar.Slider.xSkin',
  builder:function (_class) {
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
  }
});

In the above example, the module Uize.Widget.Bar.Slider.xSkin is extending the module Uize.Widget.Bar.Slider. The implementation of the module's builder function will use the _class parameter that is passed to it, which is a reference to the Uize.Widget.Bar.Slider class, and will assign new properties on it (or otherwise modify it).

Since no valus is returned by the builder function, the value function () {} (a dummy function) will be assigned to the xSkin property of the Uize.Widget.Bar.Slider module, resulting in the valid object path of Uize.Widget.Bar.Slider.xSkin. This will ensure that if the module is required and has already been built, then the Uize.module method will detect this, because the property xSkin will exist on the Uize.Widget.Bar.Slider object and dereferencing the object path Uize.Widget.Bar.Slider.xSkin will resolve to something defined, and the Uize.module method won't attempt to load the module.

NOTES

Anonymous modules are modules where no name is specified. They are useful when declaring isolated modules of code that have dependencies on other modules that may not already be defined by the time that the anonymous module declaration is encountered. Once the Uize.module method has resolved the anonymous module's dependencies, the module's builder function will be executed.

When not providing a name parameter value in the Uize.module method call, the result of the module's builder function will not be assigned to a host. Without a name for the module, there can be no host, so the value returned by the builder function is effectively ignored (ie. there is no point in returning a value).

Uize.module ({
  required:[
    'Uize.Node',
    'Uize.Widget.ImagePort',
    'Uize.Widget.Bar.Slider.xSkin',
    'Uize.Widget.Resizer.Marquee'
  ],
  builder:function () {
    /*
    ...PAGE WIRING CODE HERE...
    ...PAGE WIRING CODE HERE...
    ...PAGE WIRING CODE HERE...
    */
  }
});

The Uize.module method can also be used to simply declare a namespace. This is useful when declaring modules under that namespace, where it is implicit that the namespace must exit.

EXAMPLE

Uize.module ({
  name:'MyNamespace.MyWidgetClass',
  superclass:'Uize.Widget',
  builder:function (_superclass) {
    /*** Object Constructor ***/
      var
        _class = _superclass.subclass (
          /*
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          ...SOME CODE HERE...
          */
        ),
        _classPrototype = _class.prototype
      ;
    /*
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    ...SOME CODE HERE...
    */
    return _class;
  }
});

In the above example, it is implicit that MyNamespace must exist, so that the property MyWidgetClass can be assigned on it. Therefore, the module declaration will try to resolve this dependency, if MyNamespace is not already defined. The Uize.module method will try to load the module MyNamespace. If MyNamespace is intended to truly be just a namespace and have zero implementation "guts", then you can declare the namespace in a namespace module, as simply...

Uize.module ({name:'MyNamespace'});

Since no builder function is specified in this module declaration, the Uize.module method will simply assign function () {} (a dummy function) to the namespace. If the module name has no "host" portion (as in this example), then the "guest" (MyNamespace in this example) is assigned as a property on the window object. Namespaces can have a "host", however, as in the following example...

Uize.module ({name:'MyNamespace.MySubNamespace'});

In the event that you have multiple pages or code modules that you know all require the same common set of modules, you can declare a "library" module that itself only declares a required list and does nothing else, and then all the aforementioned pages or code modules can simply require that library module.

EXAMPLE

Uize.module ({
  name:'MyNamespace.MySiteSectionLibrary',
  required:[
    'Uize.Widget.MagView',
    'Uize.Widget.Bar.Slider.xSkin',
    'Uize.Widget.Options.Tabbed'
  ]
});

In this example, all modules that require MyNamespace.MySiteSectionLibrary will effectively require Uize.Widget.MagView, Uize.Widget.Bar.Slider.xSkin, and Uize.Widget.Options.Tabbed - even though the MyNamespace.MySiteSectionLibrary module doesn't declare its own builder function. The module does nothing but require other modules. When the builder parameter is not specified, the Uize.module method will assign function () {} (a dummy function) to the module name path (ie. MyNamespace.MySiteSectionLibrary is set to function () {} in this example), once all required modules are built.

The Uize.moduleLoader static property lets you specify a custom module loader. This is useful if you plan to use a Web service accessed through AJAX to load JavaScript modules.

A default module loader is specified for the Uize.moduleLoader static property. This module loader makes use of a technique of dynamically adding script nodes to the document.

The default module loader relies on the value of the Uize.moduleUrlTemplate static property to know where to locate the JavaScript files that define required modules. The value of this property should be a string containing the token [#modulePath], which will be replaced with a path that is derived from the name of the module to be loaded.

EXAMPLE

Uize.moduleUrlTemplate = 'http://www.somedomain.com/js/[#modulePath]';

In the above example, if the module Uize.Widget.MagView needed to be loaded, the module path of "Uize.Widget.MagView.js" would be derived from the module name and would be substituted for the [#modulePath] token, to produce the URL "http://www.somedomain.com/js/Uize.Widget.MagView.js".

When the Uize module is initially loaded, the value of Uize.moduleUrlTemplate static property will be set to a path from which the Uize.js library is loaded. This is accomplished by scanning through the document's DOM to find a script node that references the "Uize.js" JavaScript library. This approach usually works well and it is, therefore, usually not necessary to set a value for this property in order for the default module loader to work.

There might be cases, however, when the code for the Uize base class is included into a single JavaScript library file that is not named "Uize.js". In such cases, it will be necessary to set a value for the Uize.moduleUrlTemplate static property that is consistent with your server environment and where the UIZE Framework's JavaScript files are located.

In order to define your own module loader, you can override the default value of the Uize.moduleLoader static property. The value of this property should be a function. The function should expect to receive two parameters, being the name of the module to load, and a function that should be called once the module's code has been loaded. The callback function expects to receive one parameter, being the module's code as a string value.

EXAMPLE

Uize.moduleLoader = function (_moduleToLoad,_callback) {
  _this._commObject.request ({
    url:
      _this.get ('env').service + 'getjs?' +
      _serializeParams ({filename:_moduleToLoad + '.js'}),
    returnType:'json',
    requestMethod:'GET',
    callback:_callback
  });
};

When relying upon the dynamic loading of modules, one does not need to worry about whether modules are already defined or loaded by some other code by the time your module declaration is encountered. The Uize.module method does the sensible thing of not attempting to load modules that have already been loaded. Therefore, one should always feel confident to use module declarations and declare required modules appropriately. For performance reasons, you can always choose to pre-load modules with explicit script tags in a page, so that they are already loaded by the time a module declaration that might require them is encountered.