Sandbox. Загрузка и выгрузка модулей

Общие сведения

Модуль в bpm'online является изолированной программной единицей. Ему ничего не известно об остальных модулях системы, кроме списка имен модулей, от которых он сам зависит. Подробнее модули bpm'online описываются в статье "Принципы модульной разработки в bpm'online".

При работе с пользовательским интерфейсом bpm'online может возникнуть необходимость загрузки не объявленных как зависимости модулей во время выполнения приложения. Для загрузки и выгрузки таких модулей предназначены методы sandbox.loadModule() и sandbox.unloadModule().

Загрузка модулей

Для загрузки не объявленных в качестве зависимостей модулей предназначен метод sandbox.loadModule(moduleName, config). Параметры метода:

• moduleName — название модуля.
• config — конфигурационный объект, содержащий параметры модуля. Обязательный параметр для визуальных модулей.

Примеры вызова метода sandbox.loadModule():

// Загрузка модуля без дополнительных параметров.
this.sandbox.loadModule("ProcessListenerV2");
// Загрузка модуля с дополнительными параметрами.
this.sandbox.loadModule("CardModuleV2", {
    renderTo: "centerPanel",
    keepAlive: true,
    id: moduleId
});

Параметры модуля

Дополнительные параметры загрузки модуля агрегируются в конфигурационном объекте config. Наиболее часто используемые свойства этого объекта:

• id — идентификатор модуля. Если не указан, то сформируется автоматически. Тип данных — строка.
• renderTo — название контейнера, в котором будет отображено представление визуального модуля. Передается в качестве аргумента в метод render() загружаемого модуля. Обязателен для визуальных модулей. Тип данных — строка.
• keepAlive — признак добавление модуля в цепочку модулей. Используется для навигации между представлениями модулей в браузере. Тип данных — логический.
• isAsync — признак асинхронной инициализации модуля (см. "Принципы модульной разработки в bpm'online"). Тип данных — логический.

Параметры конструктора класса модуля. Свойство instanceConfig

Существует возможность при загрузке модуля передавать аргументы в конструктор класса инстанцируемого модуля. Для этого в конфигурационный объект config нужно добавить свойство instanceConfig, которому необходимо присвоить объект с нужными значениями.

Например, объявлен модуль:

// Модуль, возвращающий экземпляр класса.
define("CardModuleV2", [...], function(...) {
    // Класс, который используется для создания модуля страницы редактирования.
    Ext.define("Terrasoft.configuration.CardModule", {
        // Псевдоним класса.
        alternateClassName: "Terrasoft.CardModule",
        // Родительский класс.
        extend: "Terrasoft.BaseSchemaModule",
        // Признак, что параметры схемы установлены извне.
        isSchemaConfigInitialized: false,
        // Признак, что при загрузке модуля используется состояние истории.
        useHistoryState: true,
        // Название схемы отображаемой сущности.
        schemaName: "",
        // Признак использования режима совместного отображения с реестром раздела.
        // Если значение false, то на странице присутствует SectionModule.
        isSeparateMode: true,
        // Название схемы объекта.
        entitySchemaName: "",
        // Значение первичной колонки.
        primaryColumnValue: Terrasoft.GUID_EMPTY,
        // Режим работы страницы редактирования. Возможные значения
        // ConfigurationEnums.CardStateV2.ADD|EDIT|COPY
        operation: ""
    });
    // Возврат экземпляра класса.
    return Terrasoft.CardModule;
}

Тогда для передачи необходимых значений в конструктор модуля при его загрузке можно использовать следующий код:

// Объект, свойства которого содержат значения, 
// передаваемые как параметры конструктора
var configObj = {
    isSchemaConfigInitialized: true,
    useHistoryState: false,
    isSeparateMode: true,
    schemaName: "QueueItemEditPage",
    entitySchemaName: "QueueItem",
    operation: ConfigurationEnums.CardStateV2.EDIT,
    primaryColumnValue: "{3B58C589-28C1-4937-B681-2D40B312FBB6}"
};

// Загрузка модуля.
this.sandbox.loadModule("CardModuleV2", {
    renderTo: "DelayExecutionModuleContainer",
    id: this.getQueueItemEditModuleId(),
    keepAlive: true,
    // Указание значений, передаваемых в конструктор модуля.
    instanceConfig: configObj
    }
});

В результате модуль будет загружен с предустановленными значениями свойств и для их установки не потребуется отправлять никаких дополнительных сообщений.

Дополнительные параметры модуля. Свойство parameters

Для передачи дополнительных параметров в модуль при его загрузке в конфигурационном объекте config предусмотрено свойство parameters. Такое же свойство должно быть определено и в классе модуля (или в одном из его родительских классов).

Таким образом, при создании экземпляра модуля свойство parameters модуля будет проинициализировано значениями, переданными в свойстве parameters объекта config.

Например, свойство parameters определено в модуле MiniPageModule:

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

        return Terrasoft.MiniPageModule;
    });

Тогда при загрузке модуля мини-карточки можно инстанцировать его с дополнительными параметрами. Например:

define("MiniPageContainerViewModel", ["ConfigurationEnumsV2"], function() {
    Ext.define("Terrasoft.configuration.MiniPageContainerViewModel", {
        extend: "Terrasoft.BaseModel",
        alternateClassName: "Terrasoft.MiniPageContainerViewModel",
        ...
        loadModule: function() {
            // Свойство parameters определено в родительском классе Terrasoft.BaseModel
            var parameters = this.get("parameters");
            ...
            this.sandbox.loadModule("MiniPageModule", {
                renderTo: Ext.get("MiniPageContainer"),
                id: moduleId,
                // Передача параметров в конфигурационный объект.
                parameters: parameters
            });
        }
        ...
    });
});

Выгрузка модуля

Для выгрузки модуля необходимо использовать метод sandbox.unloadModule(id, renderTo, keepAlive). Параметры метода:

• id — идентификатор модуля. Тип данных — строка.
• renderTo — название контейнера, из которого необходимо удалить представление визуального модуля. Обязателен для визуальных модулей. Тип данных — строка.
• keepAlive — признак сохранения модели модуля. При выгрузке модуля ядро может сохранить его модель для возможности использовать ее свойства, методы, сообщения. Тип данных — логический. Не рекомендуется к использованию.

Примеры вызова метода sandbox.unloadModule():

...
// Метод получения идентификатора выгружаемого модуля.
getModuleId: function() {
    return this.sandbox.id + "_ModuleName";
},
...
// Выгрузка невизуального модуля.
this.sandbox.unloadModule(this.getModuleId());
...
// Выгрузка визуального модуля, ранее загруженного в контейнер "ModuleContainer".
this.sandbox.unloadModule(this.getModuleId(), "ModuleContainer");

Цепочки модулей

Иногда возникает необходимость показать представление некой модели на месте представления другой модели. Например, для установки значения определенного поля на текущей странице нужно отобразить страницу выбора значения из справочника SelectData. В таких случаях нужно, чтобы модуль текущей страницы не выгружался, а на месте его контейнера отображалось представление модуля страницы выбора из справочника. Для этого можно использовать цепочки модулей.

Чтобы начать построение цепочки, достаточно добавить свойство keepAlive в конфигурационный объект загружаемого модуля. Например, в модуле текущей страницы CardModule необходимо вызвать модуль выбора из справочника selectDataModule. Для этого нужно выполнить следующий код:

sandbox.loadModule("selectDataModule", {
    // Id представления загружаемого модуля.
    id: "selectDataModule_id",
    // Представление будет добавлено в контейнер текущей страницы.
    renderTo: "cardModuleContainer",
    // Указывает, чтобы текущий модуль не выгружался.
    keepAlive: true
});

После выполнения кода построится цепочка модулей из модуля текущей страницы и модуля страницы выбора из справочника. Из модуля текущей страницы selectData, нажав на кнопку [Добавить новую запись], можно открыть новую страницу, добавив в цепочку еще один элемент. Таким образом в цепочку модулей можно добавлять сколько угодно экземпляров модулей. Активный модуль (тот, который отображен на странице) — всегда последний элемент цепочки. Если установить активным элемент из середины цепочки, то все элементы, находящиеся в цепочке после него, будут уничтожены. Для того чтобы активировать элемент цепочки, достаточно вызвать функцию loadModule, в параметр которой передать идентификатор модуля:

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

Ядро уничтожит все элементы цепочки после указанного и выполнит стандартную логику при загрузке модуля — вызовет методы init() и render(). При этом в метод render() будет передан контейнер, в который был помещен предыдущий активный модуль. Все модули цепочки могут работать как и раньше — принимать и отправлять сообщения, сохранять данные и т.п.

Если при вызове метода loadModule() в конфигурационный объект не добавлять свойство keepAlive или добавить его со значением keepAlive: false, то цепочка модулей будет уничтожена.