sandbox object
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.
/* 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 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 PUBLISH The message direction is publishing. The module only publishes the message to 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, |
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 |
tags | A tag array that lets you uniquely identify the module that sends the message. Usually, the |
Use examples
/* 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, |
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 |
scope | The execution scope of the |
tags | An array of tags that lets you uniquely identify the module that sends the message. |
Use examples
/* 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. {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 {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 Do not pass class instances, HTMLElement descendants, etc., as property values. When passing parameters to the constructor of the {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 |
Use examples
/* 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
/* 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");