SubComponents are basically nested components in other components. They provide you with a possibility of reusing code in other components. They can also enter the part list as separate entries. To sum it up, they can be utilized in following scenarios:
use other component's geometry
use other component's parameters
use them as part list entries
use them as a workaround for some computations
To define a SubComponent, use subComponents list, which is one of root attributes of the Component class:
If you load both of those components, you can see that it seems like the subcomponent is loaded. Practically everything in the master is coming from the subcomponent - the geometry, parameters and even the part list.
What can be unexpected is that the articleNr of '123.456' is nowhere to be seen. This is because if you have a subcomponent definition, the part list entry of the main component is hidden. To fix this, we can add a back-referencing subcomponent, but more on that later.
Attributes of SubComponent
internalId: You see that the SubComponent is defined with an internalId, which is any reasonable identifier string, which you will use in the geoemtry as argument for the SubComponent(subComponentInternalId) function. This basically takes the subcomponent's geometry and draws it as if it was the master's own geometry, including selection highlighting and measurement box. It is a mandatory attribute.
componentId: This is the componentId of the component that is used as a subcomponent. Mandatory attribute.
numberInPartList: Integer or Decimal, which is shown in the "Count" field in the part list. It can be a constant, expression or a RoomleScript. If you want, you can use assignment to an internal variable number in this script. Example:
{"numberInPartList":"if (type == 'set') { number = 4; } else { number = 1; } "}
sort: This is the sort criteria for the part list entry. Part list entries will be sorted by ascending order of this value. Part list entries without the sort value defined are sorted at the end of the part list. To control sort of the current component, apply the sort attribute to the back-reference.
isMain: If part list grouping is set in the configurator init data, this component is displayed in the part list as the category header. See Part List Grouping for more details.
assignments: Will assign a value to the subComponent's parameters. They are assigned in every onUpdate loop, making the loop continue in the subComponent. You can assign to any parameter, as long as the assigned value is among the set of the target parameter's possible values.
active: If true, all supersedings are valid and the update loop runs in the subcomponent. If false, superseded parameters are not available (including their identifiers' declarations) and the update loops do not run. Inactive subComponents do not enter the part list.
supersedings: Currently working only for parameters. Superseded parameters will be exposed in the master component's UI and its value is available in the master. Superseding can happen through more levels of the whole subcomponent hieararchy.
Superseded parameter's onValueChange will be evaluated in its own component's context only.
If you supersede a parameter, it should be initialized with a parameter of the same key and type, with no provided valid values.
supersedings.overrides: Object with fields key and group. Allows you to override the group or key of the superseded parameter.
Back-reference
If you use subcompnent definitions, the root component (of the subcomponent hierarchy, not of the configuration/docking hierarchy) looses its entry from the part list. Resulting part list can even be empty. To show the root component, use a following back-reference pattern:
Every subComponent that has the same componentId as the parent component id (like in the example above) is considered to be a back-reference and its sole purpose is to be able to define the count of the component in the part list. All assignments to this component are ignored and it is not indended to be instantiated in the geometry (otherwise this would end in an endless hierarchy).
You can use the Roomle: Add SubComponent Backreference command of the VS Code extension to inject the back-reference for you if there is none yet.
Hint: Always write the back-reference as the first subComponent.
SubComponents Use Cases Examples
In following subchapters, you can see how to utilize SubComponents in commented examples.
1. External Geometry
If you have a geometry that you extensively reuse accross more components, or more times in a single component, you can take this geometry, put it in another component and instantiate the geometry using the subcomponent. This is especially usable if you do complex geometry functions in order to keep your components more clean.
1.1 Example: Using SubComponent's Geometry
In this example, we instantiate pleated window blinds using geometry from existing components. The blinds should be attached in between two rails. The geometry has been created beforehand in another project and its usage is internally documented. What you need to know when using a subcomponent are the parameters, because you can only assign to (and supersede from) the parameters.
As you can see, we have two parameters driving the size of the product. There are three defined SubComponents - the folds and two rails. The parameters assigned to the folds are mostly self-explanatory. However, there are some that you need to know what they're for:
position: how the plissee is open (in percent)
place: +1 if the rail is on top, -1 if on bottom
RailHeight: superseded, its the dimension of the rail, it has to be moved up in order that the folds fit on it
In the geometry, we simply instantiate the subcomponents' geometries using the SubComponent() function. We also supersede one parameter here, basically copying its instance to the above hierarchy level.
2. Partlist Entry
2.1 Example: Adding Mounting Parts to the Parametrized Shelf
In the previous example, we looked into how to instantiate a subcomponent's geometry. Here, we look into how to instantiate it as a part list entry. We will extend the previous example of the parameterized grid shelf. Not exactly a feature for the customer, more like a feature for the manufacturer: Specify the screws and pins needed in the package. Therefore, we make two new components:
Now we open demoCatalogId:example_shelf, we compute how many screws and pins are needed. The screws hold the outer walls togetger, always needing 8 of them, and there are always two pins in every intersection of the wood plates. We add following SubComponent definitions:
When we load the component and open the part list, we can see following result:
Everything is fine, but the shelf is gone from the part list! As mentioned above in the Back-reference chapter, we add the component itself as a subcomponent. We also add a label:
Not always a best case example, but sometimes it can be handy, that you override the part list of one component by another component. This can be especially useful, if the customer's partlist contains a lot of data that are unrelevant for you and are only output of the configurator, like pricegroups, weight, etc. You can compute a correct articleNr in your main component and then send this articleNr to another component, that has code generated for example from an Excel/Google sheet, that can be exported from the client's information system. You can then have one component that contains a table of all partlist entries, which you can update easily, should the client want to add/remove/change some data. Your only responsibility is to compute the articleNr correctly.
If you select an invalid articleNumber to assign, no of the if-statements will be evaluated and productCode stays with 'ERROR', showing also a big red cube in the geometry supposing you instantiate geometry of the subComponent using the SubComponent function. We recommend doing this in debugGeometry supposing you're using the Advanced Loader Snippet. You should notice error in the QM phase when clicking through the elements.
3. External Computation
This pattern was used in the past as a workaround for the missing Functions feature. Following is kept in the documentation, but not recommended anymore.
Let's say we have a function we want to reuse across multiple components. We make and extra component for it, in means of a workaround for a missing function definition feature:
