Module basics

Advanced

AMD concept

Creatio front-end is a set of function blocks implemented in separate modules. In accordance with the Asynchronous Module Definition (AMD) concept, Creatio loads modules and their dependencies asynchronously at runtime. Therefore, the AMD concept lets you load only data with which you need to work currently. Learn more about the AMD concept in Wikipedia.

Different JavaScript frameworks support the AMD concept. Creatio uses the RequireJS loader to work with modules. Learn more on the official RequireJS website.

Modular development in Creatio

A module is a code fragment encapsulated in a separate block that is loaded and executed independently.

The Module programming pattern declares the module creation in JavaScript. Learn more in a separate article: JavaScript Module Pattern: In-Depth. The classic pattern implementation uses anonymous functions that return a specific value, for example, object, function, etc., associated with a module. In this case, the module value is exported to a global object.

Example that exports the module value to a global object

/* Immediately invoked function expression (IIFE). The anonymous function that initializes the myGlobalModule property of the global object using a function that returns the module value. Thus, the module is loaded and can later be accessed via the myGlobalModule global property. */
(function () { 
    /* Access a module on which the current module depends.
    Load the module into the SomeModuleDependency global variable before accessing it.
    The "this" context is a global object. */ 
    var moduleDependency = this.SomeModuleDependency; 
    /* In the global object property, declare a function that returns the module value. */ 
    this.myGlobalModule = function () { return someModuleValue; }; 
}());

When the interpreter finds a functional expression like this in the code, the interpreter immediately resolves it. As a result, a function that returns the module value will be placed to the myGlobalModule global object's property.

The concept specifics are as follows:

Declaration and use of dependency modules are complex.
Load all module dependencies before Creatio starts executing the anonymous function.
Dependency modules must be loaded via the <script> HTML element in the page header. Use global variable names to access the dependency module. In this case, the developer needs to implement the load order of module dependencies.
As a result of the previous item, Creatio loads the modules before the browser starts rendering the page, so the modules cannot access page controls to implement custom logic.

The special features of using the concept in Creatio are as follows:

You cannot load modules dynamically.
You might need to apply additional logic when loading modules.
Managing a large number of modules with multiple dependencies that can overlap adds complexity.

RequireJS loader

The RequireJS loader provides a mechanism that declares and loads modules based on the AMD concept and lets you take into account the specifics listed above.

The operating principles of the RequireJS loader are as follows:

The module is declared in the define() function that registers a factory function to instantiate the module. At the same time, the define() function does not load the module immediately when this function is called. Learn more about the define() function on the GitHub website.
Module dependencies are passed as an array of string values, not via the global object properties.
The loader loads the module dependencies that are passed as arguments of the define() function. Modules are loaded asynchronously. The loader sets the load order arbitrarily.
After the specified module dependencies are loaded, the loader calls a factory function that returns the module value. The loaded module dependencies are passed to the function as arguments.

Resources

Description of Asynchronous Module Definition (AMD) concept (Wikipedia)

Official RequireJS website

Description of JavaScript Module Pattern

Description of define() function (GitHub)

Example that declares a module

Beginner

Example that uses the define() function to declare the SumModule module

/* The SumModule module implements the functionality that adds two numbers.
The module has no dependencies. Therefore, the function passes an empty array as the second argument, and the anonymous factory function does not receive parameters. */
define("SumModule", [], function () {
    /* The body of the anonymous function contains the internal implementation of the module's functionality. */
    var calculate = function (a, b) { return a + b; }; 
    /* The function returns a value that is an object. In this case, the object is the module. */ 
    return { 
        /* Description of the object. In this case, the module is an object that has the summ property. The summ property value is a function that has two arguments and returns the sum of those arguments. */
        summ: calculate 
    };
});

define() function

Beginner

The purpose of the define() function is to declare an asynchronous module in the source code. The loader works with this module.

Declare the module

define(
    ModuleName,
    [dependencies],
    function (dependencies) {
    }
);

Parameters

ModuleName

The string that contains the module name. Optional.

If you do not specify the parameter, the loader assigns a module name automatically based on the module location in the Creatio script tree. The name is required to access the module from other Creatio parts, including asynchronous loading as a dependency of another module.

dependencies

An array of module names on which the current module depends. Optional.

The RequireJS loader loads the module dependencies that are passed as arguments to the define() function. The loader calls the factory function after loading the dependencies listed in the dependencies array.

function(dependencies)

An anonymous factory function that instantiates the module. Required.

Pass the objects that the loader associates with module dependencies as function parameters. List dependencies in the dependencies array. The array arguments are required to access the properties and methods of the dependency modules in the current module. The order of dependencies in the dependencies array corresponds to the order in which the parameters are listed in the factory function.

The factory function returns the value that the loader handles similarly to the exported value of the current module.

The types of values that the factory function returns are as follows:

Object. In this case, the object is the module. The browser caches the module after the initial download. If the module declaration changes after the client downloads the module, for example, as part of implementing the configuration logic, clear cache and re-download the module.
Module function factory. The constructor receives the scope object as an argument. As a result, downloading a module creates a module instance (instantiated module) in the client. Re-downloading the module to the client via the require() function creates another module instance. Creatio treats these instances of the same module as individual modules. View the example that declares an instantiated module in the CardModule schema of the NUI package.