sandbox object

Level: intermediate

A sandbox object is a core component required to organize the module interaction.

The sandbox object lets you execute the following actions:

• Organize the message exchange among the modules.
• Load and unload modules on request.

Methods

registerMessages(messageConfig)

Registers module messages.

Parameters

{Object} messageConfig

Configuration object of module messages. Configuration object is a key-value collection where every item is as follows.

Item of configuration object

/* Key of the collection item. The key is the message name. */
"MessageName": {
    /* Value of the collection item. */
    mode: [Message mode],
    direction: [Message direction]
}

Properties of the collection item values

{Terrasoft.MessageMode} mode

Message operation mode. Contains the value of the Terrasoft.MessageMode (Terrasoft.core.enums.MessageMode) enumeration. Available values (Terrasoft.MessageMode) BROADCAST Broadcast message mode where the number of message subscribers is unknown in advance. PTP Address message mode where only one subscriber can handle a message.

{Terrasoft.MessageDirectionType} direction

Message direction. Contains the value of the Terrasoft.MessageDirectionType (Terrasoft.core.enums.MessageDirectionType) enumeration. Available values (Terrasoft.MessageDirectionType) PUBLISH The message direction is publishing. The module only publishes the message to sandbox. SUBSCRIBE The message direction is subscription. The module only subscribes to a message that is published by another module. BIDIRECTIONAL The message is bidirectional. The module publishes and subscribes to the same message in different instances of the same class or the same schema inheritance hierarchy.

unRegisterMessages(messages)

Cancels message registration.

Parameters

{String|Array} messages

Name or array of message names.

publish(messageName, messageArgs, tags)

Publishes a message to sandbox.

Parameters

{String} messageName	A string that contains the message name. For example, "MessageToSubscribe."
messageArgs	An object passed as a parameter to the message handler method in the subscriber module. If incoming parameters are omitted from the handler method, set the messageArgs parameter to null.
tags	A tag array that lets you uniquely identify the module that sends the message. Usually, the [this.sandbox.id] value is used. sandbox identifies subscribers and publishers of a message based on the array of tags.

Use examples

Examples that use the publish() method

/* Publish the message without parameters and tags. */
this.sandbox.publish("MessageWithoutArgsAndTags");

/* Publish the message without using parameters for the handler method. */
this.sandbox.publish("MessageWithoutArgs", null, [this.sandbox.id]);

/* Publish the message using the parameter for the handler method. */
this.sandbox.publish("MessageWithArgs", {arg1: 5, arg2: "arg2"}, ["moduleName"]);

/* Publish the message using an arbitrary array of tags. */
this.sandbox.publish("MessageWithCustomIds", null, ["moduleName","otherTag"]);

subscribe(messageName, messageHandler, scope, tags)

Subscribes to a message.

Parameters

{String} messageName	A string that contains the message name. For example, "MessageToSubscribe."
messageHandler	A method handler is called when module receives a message. It can be either an anonymous function or module method. You can specify a parameter in the method definition. Pass the parameter value when publishing a message using the sandbox.publish() method.
scope	The execution scope of the messageHandler handler method.
tags	An array of tags that lets you uniquely identify the module that sends the message. sandbox identifies subscribers and publishers of a message based on the array of tags.

Use examples

Example that uses the subscribe() method

/* Subscribe to a message without parameters for the handler method.
Method handler is an anonymous function. Execution scope is the current module.
The getSandboxId() method returns a tag that matches the tag of the published message. */
this.sandbox.subscribe("MessageWithoutArgs", function(){console.log("Message without arguments")}, this, [this.getSandBoxId()]);

/* Subscribe to a message using the parameter for the handler method. */
this.sandbox.subscribe("MessageWithArgs", function(args){console.log(args)}, this, ["moduleName"]);

/* Subscribe to a message using an arbitrary tag.
Use a tag from the array of tags of the published message.
Implement the myMsgHandler() handler method separately. */
this.sandbox.subscribe("MessageWithCustomIds", this.myMsgHandler, this, ["otherTag"]);

loadModule(moduleName, config)

Loads the module.

Parameters

{String} moduleName

Module name.

{Object} config

Configuration object that contains the module parameters. Required for visual modules. Properties of the configuration object {String} id Module ID. If the ID is missing, the module generates it automatically. {String} renderTo The name of the container that displays the view of the visual module. Passed as the render() method parameter of the loaded module. Required for visual modules. {Boolean} keepAlive The flag that indicates whether to add the module to the module chain. Required for navigation between the module views in the browser. {Boolean} isAsync The flag that indicates whether to initialize the module asynchronously. {Object} instanceConfig Lets you pass parameters to the class constructor of an instantiated module when the module is loaded. To do this, specify a configuration object as the value of the instanceConfig property. An instantiated module is a module that returns a constructor function. You can pass the following property types to a module instance: string boolean number date (the value will be copied) object (literal objects only) Do not pass class instances, HTMLElement descendants, etc., as property values. When passing parameters to the constructor of the BaseObject descendant module, consider the following restriction: Creatio cannot pass a parameter that is not described in a module class or one of the parent classes. {Object} parameters Passes additional parameters to the module when loading a module. Pre-implement the same property in a module class or one of the parent classes. The parameters property is implemented in the BaseModule base class. When a module instance is created, the parameters property of the module is initialized using the values passed in the parameters property of the configuration object.

Use examples

Example that uses the loadModule() method

/* Load the module without using additional parameters. */
this.sandbox.loadModule("ProcessListenerV2");

/* Load the module using additional parameters. */
this.sandbox.loadModule("CardModuleV2", {
    renderTo: "centerPanel",
    keepAlive: true,
    id: moduleId
});

unloadModule(id, renderTo, keepAlive)

Unloads the module.

Parameters

{String} id	Module identifier.
{String} renderTo	The name of the container to remove the view of the visual module. Required for visual modules.
keepAlive	The flag that indicates whether to save the module model. The core can save a module model when unloading the module to use the properties, methods, and messages of the model.

Use examples

Example that uses the unloadModule() method

/* Retrieve the ID of an unloaded module. */
getModuleId: function() {
    return this.sandbox.id + "_ModuleName";
},

...
/* Unload a non-visual module. */
this.sandbox.unloadModule(this.getModuleId());

...
/* Unload a visual module previously loaded into the "ModuleContainer" container. */
this.sandbox.unloadModule(this.getModuleId(), "ModuleContainer");