Sandbox. Loading and unloading modules

Introduction

A bpm’online module is an isolated software unit. It has no information about other bpm’online modules apart from the module name list from which is depends. See “Modular development principles in bpm'online” for more information about bpm’online modules.

In certain situations, you might need to load modules that were not declared as dependencies when working with bpm’onlie interface. To load and unload such modules, sandbox.loadModule() and sandbox.unloadModule() methods are designed.

Loading modules

Use the sandbox.loadModule(moduleName, config) method to load undeclared modules. Method parameters:

• moduleName – module name.
• config – configuration object that contains module parameters. This is a required parameter for visual modules.

Method sandbox.loadModule() call parameters:

// Loading a module without additional parameters.
this.sandbox.loadModule("ProcessListenerV2");
// Loading a module with additional parameters.
this.sandbox.loadModule("CardModuleV2", {
    renderTo: "centerPanel",
    keepAlive: true,
    id: moduleId
});

Module parameters

Additional module loading parameters are aggregated in the config configuration object. Most common properties of this object are as follows:

• id – module Id. If the Id is not specified, it will be generated automatically. Data type – string.
• renderTo – name of the container where visual module view will be displayed. Passed as an argument to the render() method of the loaded module. Required for visual modules. Data type – string.
• keepAlive – indicates whether the module is added to a module thread. Used for navigation between the module views. Data type – Boolean.
• isAsync – indicates asynchronous initialization of the module (see “Modular development principles in bpm'online”). Data type – Boolean.

Module class constructor parameters. The instanceConfig property.

There is an option to pass arguments to the class constructor of the instantiated module. To do this, add the instanceConfig property to the config configuration object and assign an object with the needed values to it.

For example, the following module is declared:

// A module that returns a class instance.
define("CardModuleV2", [...], function(...) {
    // A class used for creating an edit page module.
    Ext.define("Terrasoft.configuration.CardModule", {
        // Class alias.
        alternateClassName: "Terrasoft.CardModule",
        // Parent class.
        extend: "Terrasoft.BaseSchemaModule",
        // Indicates that schema parameters have been set from without.
        isSchemaConfigInitialized: false,
        // Indicates that history state is used on module loading.
        useHistoryState: true,
        // Schema name of the displayed entity.
        schemaName: "",
        // Indicates that the common display mode (with the section list) is used.
        // If the value is false, SectionModule is present on the page.
        isSeparateMode: true,
        // Object schema name.
        entitySchemaName: "",
        // Primary column value.
        primaryColumnValue: Terrasoft.GUID_EMPTY,
        // Edit page mode. Possible values
        // ConfigurationEnums.CardStateV2.ADD|EDIT|COPY
        operation: ""
    });
    // Return class instance.
    return Terrasoft.CardModule;
}

Use the following code to pass the needed values to the module constructor on its loading:

// Object, whose properties contain values 
// passed as constructor parameters
var configObj = {
    isSchemaConfigInitialized: true,
    useHistoryState: false,
    isSeparateMode: true,
    schemaName: "QueueItemEditPage",
    entitySchemaName: "QueueItem",
    operation: ConfigurationEnums.CardStateV2.EDIT,
    primaryColumnValue: "{3B58C589-28C1-4937-B681-2D40B312FBB6}"
};

// Loading module.
this.sandbox.loadModule("CardModuleV2", {
    renderTo: "DelayExecutionModuleContainer",
    id: this.getQueueItemEditModuleId(),
    keepAlive: true,
    // Specifying values passed to module constructor.
    instanceConfig: configObj
    }
});

As a result, the module will be loaded with pre-set property values and no additional messages will be needed to set them.

Additional module parameters. The “parameters” property.

The parameters property is designed to pass additional parameters to a module on its loading in the config configuration object. Same property must be defined in the module class (or one of its parent classes) as well.

Thus, when instantiating the module, its parameters property will be initialized with values passed in the parameters property of the config object.

For example, the “parameters” property is defined in the MiniPageModule module:

define("MiniPageModule", ["BusinessRulesApplierV2", "BaseSchemaModuleV2", "MiniPageViewGenerator"],
    function(BusinessRulesApplier) {
        Ext.define("Terrasoft.configuration.MiniPageModule", {
            extend: "Terrasoft.BaseSchemaModule",
            alternateClassName: "Terrasoft.MiniPageModule",
            ...
            parameters: null,
            ...
        });

        return Terrasoft.MiniPageModule;
    });

In this case, the pop-up summary module can be instantiated with additional parameters. Example:

define("MiniPageContainerViewModel", ["ConfigurationEnumsV2"], function() {
    Ext.define("Terrasoft.configuration.MiniPageContainerViewModel", {
        extend: "Terrasoft.BaseModel",
        alternateClassName: "Terrasoft.MiniPageContainerViewModel",
        ...
        loadModule: function() {
            // The "parameters" property is defined in the parent class Terrasoft.BaseModel
            var parameters = this.get("parameters");
            ...
            this.sandbox.loadModule("MiniPageModule", {
                renderTo: Ext.get("MiniPageContainer"),
                id: moduleId,
                // Passing parameters to configuration object.
                parameters: parameters
            });
        }
        ...
    });
});

Unloading modules

Use the sandbox.unloadModule(id, renderTo, keepAlive) method to unload module. Method parameters:

• id – module Id. Data type – string.
• renderTo – name of the container where visual module view will be deleted. Required for visual modules. Data type – string.
• keepAlive – indicates if the module model is saved. On unloading the module, the core can save its model for using its properties, methods an messages. Data type – Boolean. Not recommended.

Method sandbox.unloadModule() call parameters:

...
// Method that obtains Id of unloaded module.
getModuleId: function() {
    return this.sandbox.id + "_ModuleName";
},
...
// Unloading a non-visual module.
this.sandbox.unloadModule(this.getModuleId());
...
// Unloading a visual module, previously loaded to the "ModuleContainer" container.
this.sandbox.unloadModule(this.getModuleId(), "ModuleContainer");

Module thread

Sometimes a model view must be shown in place of other model. For example, to set a field value on the current page, a SelectData lookup selection page must be displayed. In such cases, the current page module must not be unloaded, but the module view of the lookup selection page must be displayed in place of its container. For this, use module threads:

To begin a new module thread, add the keepAlive property to the configuration object of the loaded module. For example, you need to display lookup selection module (selectDataModule) in the current page module (CardModule). To do this, execute the following code:

sandbox.loadModule("selectDataModule", {
    // Id of the loaded module view.
    id: "selectDataModule_id",
    // The view will be added to the current page container.
    renderTo: "cardModuleContainer",
    // Denies unloading of the current module.
    keepAlive: true
});

After the code is executed, a module thread consisting of the current page module and lookup selection module will be created. Clicking the [Add new record] button in the current page module (selectData) will open a new page and add another element to the thread. Thus, unlimited number of modules can be added to the module thread. Active module (the one displayed on the page) will always be the last element in the thread. If an element in a thread is set as active, all elements after it will be destroyed. To activate a chain element, call the loadModule function and pass module Id to its parameter:

sandbox.loadModule("someModule", {
    id: "someModuleId"
});

The core will destroy all elements in the thread after the specified one and execute standard module loading logic, calling the init() and render() methods. The container where the previous active module was placed will be passed to the render() method. All modules in the thread can work as before, receiving and sending messages, saving data, etc.

If the keepAlive property is not added to the configuration object when the loadModule() method is called, or if this property is added as keepAlive: false, the module thread will be destroyed.