Reusing Custom Modules
Understanding how to embed custom modules inside of one another
This article explains how to create embeddable custom modules and how to reuse them inside other custom modules.
Introduction
One of the most important and powerful aspects of custom module design in Proto is the ability to reuse custom modules inside other custom modules. This is achieved by embedding a new or extant custom module into another custom module and connecting it as if it were a basic module. This configuration allows messages to flow into and out of an embedded custom module as if the embedded custom module’s contained modules were contained in the parent module. Utilizing custom modules prevents you from needing to rebuild common module configurations or create an identical combination of modules multiple times.
Creating an Embedded Module
To create a new embeddable custom module, you can either adapt an existing custom module or create a new one from scratch. Every custom module has the potential to become embedded in another custom module. However, in order for the module to be functional while embedded, data must be able to travel into and out of it. Therefore it is necessary to utilize the custom module input and output connectors, accessible on the left and right of the Builder. Creating a connection between the input and output connectors and its contained modules determines the flow of data in and out of the custom module when it is embedded in another module. Making these connections is identical to making any other connection. When a connection is made with that embedded module connector and it receives a message, the message travels from the parent module into the embedded module along that connection. The message path continues regularly as if the modules were simply connected to the parent module until no triggered connections remain or until it reaches the embedded custom module’s output connector. In that case, the message will travel along that connection back out of the embedded custom module and into the parent module and continue as normal.
Editing a Custom Module’s Input and Output Connector Menus
When creating a custom module, it is possible to edit the name and number of input and output connectors contained in its input and output menu. By default, every custom module has two input connectors—“Input1” and “Input2”—and two output connectors—“Output1” and “Output2”. You can launch the Custom Module Menu Editor by right-clicking on the custom module input or output connector that you would like to edit and selecting Edit… In the Menu Editor, click on the to expand the top level menu. Right-click on the menu or any connector and select Add… to add a new connector menu. You can then provide its name and a description to be shown in the Guide and it will be added to the connectors list. Right-click on any connector already in the list and select Edit…, Rename, or Delete. Selecting Edit allows you to edit the connector’s name and Guide description, while Rename and Delete behave as expected. Deleting a connector with any attached connections will remove those connections.
Embedding Custom Modules
There are no restrictions as to which custom modules can be embedded inside others. To embed a custom module that has already been built and is stored in the repository, right-click anywhere on the background of the Builder and select Browse… from the Insert menu. The Open Custom Module window will appear, from which you can select any revision of any custom module stored in your repository. Select one and click and the custom module, represented by a single module with the custom module icon, will appear in the Builder. It is also possible to insert a new, empty custom module in your current custom module. To do so, right-click anywhere on the background of the Builder and select New Custom Module from the Insert menu. The new custom module will appear as an embedded module inside your current custom module.
Editing Embedded Modules
The Builder allows you to edit embedded custom modules after they have been inserted in your custom module. To open an embedded module, right-click on the module and select Open. This will display the embedded custom module’s Builder in a separate tab inside the current window. Click on the tabs along the top of the Builder to switch between Builder editors. In these tabs, you can edit an embedded custom module exactly as if it were open in its own window: you can make connections, edit the input and output connectors, or embed other custom modules. However, when a custom module is embedded, it is actually an exact copy of that module that is inserted into the parent custom module. Therefore, all changes made to an existing custom module when it is embedded will only be saved locally to the parent custom module that it is embedded in. To save the changes made to an embedded custom module in the repository as a new version of the custom module, right-click on the embedded module in its parent’s Builder and select Publish to Repository… This will bring up a standard Save window which saves new embedded custom modules as new modules in the repository and saving already existing custom modules as new revisions. For more information about versioning, please read managing modules.