4.4 - Configuration Menu

When you want to build your own user interface for the Product Configurator, one of the most useful set of data is the configuration menu. It also comes with a set of event that you can send to take actions on the product.

Event name	Input / Output	Payload	Reason
menuChanged	Output event	Menu changed.	Receive every change in the configuration menu.
addComponent	Input event	Add component.	Attach a new component to an anchor.
applyConfiguration	Input event	Apply configuration.	Apply a configuration change on one product.
removeComponent	Input event	Remove component.	Remove a component currently attached to an anchor.
replaceComponent	Input event	Replace component.	Replace a component currently attached to an anchor.
setAnchorSelection	Input event	Set anchor selection.	Set the current anchor selection.

Menu changed

This event is fired everytime a change occurs in the configuration menu. It contains the following attributes:

Attribute name	Type	Content
mainParameters	An array of Menu Parameters	The list of parameters to display that while change the whole composition. On a modular product, this will change on all compatible modules. On a non modular product this contains all the data you need.
modules	An array of Modules	Only for modular products. This is the list of modules currently loaded in the composition, including the data necessary to configure them.
moduleAdding	An optional Product Adding Parameter	Only for modular products. Null when no anchor is selected. When the users selects an anchor, this will contains the data necessary to add a module attached to the selected anchor.
selectedProductUUID	An optional string	The UUID of the selected product at the time the configuration menu is updated, or null if there was no selected product at that time.

warning

The selectedProductUID information is provided for convenience whenever the configuration menu changes. It is not updated when the selection changes, but the menu content remains the same.
If you wish to be informed of occurring selections, use the dedicated Product selection events.

Menu Parameter

A menu parameter contains the data necessary to configure one parameter.

info

Every menu parameter contains the same base set of attributes. Then, depending on the type of the parameter, it will contain some specific data.

This is the list of attributes available on every parameter:

Attribute name	Type	Content
action	string	Can be one of: add: This is used to add a module (only for modular products). parameter: This is used to modify the value of a parameter. replace: This is used to replace a module (only for modular products).
deletable	boolean	If true, you can send a null value for this parameter to delete it.
id	string	The identifier of the parameter, used to communicate with the Product Configurator.
name	string	The name to display in the menu.
productUuid	string?	The UUID of the associated product. This will be set when the scope is local only (this is the product on which the parameter applies). This is null for global scoped parameters.
scope	string	Only useful for modular products (otherwise, both value have the same effect). Can be one of: global: This parameter will apply to the whole composition. local: This parameter will apply to the current module only.
type	string	Can be one of: boolean: Boolean Parameter color: Color Parameter integer: Number Parameter material: Product Parameter number: Number Parameter product: Product Parameter string: String Parameter

Boolean Parameter

A boolean parameter is a Menu Parameter with additional / modified attributes. The possible values are always true and false.

Attribute name	Type	Content
currentValue	boolean	The current value of this parameter.

Color Parameter

A color parameter is a Menu Parameter with additional / modified attributes.

Attribute name	Type	Content
currentValue	string?	The optional current value of this parameter. If set, it's an hexadecimal color value.
possibleValues	Array of objects	An array of all the possible values. Each value is an object containing: displayName: The value to display (string). value: The hexadecimal value of this color (string).

Number Parameter

A number parameter is a Menu Parameter with additional / modified attributes.

Number parameter can have two different ways of listing the values that can be used:

• A closed list of possibilities to display.
• A "range", that you would usually display as a slider in the menu. To know which one to use, you can check the presence of either the possibleValues or range attributes.

Possible values

Attribute name	Type	Content
currentValue	number?	The optional current value of this parameter.
possibleValues	Array of objects	An array of all the possible values. Each value is an object containing: displayName: The value to display (string). value: The hexadecimal value of this color (string).

Range

Attribute name	Type	Content
currentValue	number	The current value of this parameter.
range	object	An object with instruction about a range of authorized values. See the description of this object below.

The range object contains the following attributes:

Attribute name	Type	Content
max	number?	The optional maximum allowed value.
min	number?	The optional minimum allowed value.
step	number?	The optional step between two values. With a min of "0" and a step of "2", allowed values would be 0, 2, 4...

Product Parameter

A product parameter is a Menu Parameter with additional / modified attributes.

Attribute name	Type	Content
currentValue	An optional Product Parameter Value.	The current product for this parameter. May be null.
filters	An optional array of Product Filters	A description of the filters available on this parameter.
isMaterialList	boolean	Indicates if the list of product is a list of materials. It allow to display materials with a different UI.
possibleValues	Array of Product Parameter Values.	The list of possible values for this parameter.

tip

When displaying the list of possible values in the UI, you will want to know for each possible value if it's the currently selected value.

You can do this by comparing it to the currentValue using the dbId attribute, like this: possibleValue.dbId == currentValue?.dbId.

Product Filter

A product filter defines a filter that can be used to filter the possible values of a product parameter. It contains the filter itself, and the list of possible options for this filter. Usually the options would be displayed as checkboxes use the filter name. It's an object with the following attributes:

Attribute name	Type	Content
id	string	The identifier of this filter.
name	string	The name to display for this filter.
type	string	The type of this filter. One of: boolean: No options, the possible values are always "true" and "false". color: Options are strings for a color. integer: Options are integers. material: Options are strings (name of products). number: Options are numbers. product: Options are strings (name of products). string: Options are strings.
options	Array of objects	This arrays contains the available options for this filter. The array contains objects with the following attributes: name: The display name for this filter. value: The value for this filter. The type depends on the type of filter described in this same table.

Product Parameter Value

A product parameter value describes a product that can be used as a value for a parameter. It may be a material, a leg, a module... It's an object with the following attributes:

Attribute name	Type	Content
dbId	string	The database ID of this product.
photo	string?	An optional URL to the photo of this product.
description	string?	The optional description of the product.
name	string?	The optional name of the product.
filters	Optional Product Filter Values	The data that can be used to associated this parameter value to the filters available on the parameter.

Product Filter Values

The product filter values are an object with no predefined attributes. It's defined like this: Record<string, Array<boolean | number | string>>

• As the key (string) you find the ids of the filters from Product Filter -> id.
• As values, you find arrays with the matching filter values. The values are the same as in Product Filter -> options[] -> value.

As an example:

You have a material filter that can take as possible values fabric and leather. The current product is a fabric. In the product filter values object, you will find this:

{
    material: ["fabric"]
}

It means that if you select the "fabric" value in the "material" filter, this product will match the search.

Product Adding Parameter

A product adding parameter is a Product Parameter with additional / modified attributes. It's used when adding a product to an anchor.

Attribute name	Type	Content
anchorUuid	string	The uuid of the anchor where to attach this product.
productUuid	string	The same attribute described in Product Parameter, but it's always set to a value (never null).

String Parameter

A string parameter is a Menu Parameter with additional / modified attributes.

Attribute name	Type	Content
currentValue	string?	The optional current value of this parameter.
possibleValues	Array of objects	An array of all the possible values. Each value is an object containing: displayName: The value to display (string). value: The raw value to set (string).

Module

Modules are only available on modular products. It is a representation of one of the module currently loaded in the Product Configurator. It contains the following attributes:

Attribute name	Type	Content
name	string	The name to display for this module.
parameters	An array of Menu Parameters	The list of parameters to display that while change on this module only.
photo	string?	If available, an url to the photo of this module.
replacement	An optional Product Parameter	If available, a product parameter that can be used to replace this module. The productUuid is always set on it.
uuid	string	The unique identifier of this module in the current composition.

Example

// Receive the menu changes.
configurator.addEventListener("menuChanged", (event) => {
    console.log(event.detail);
});

Actions

tip

The following actions will trigger modifications in the 3D viewer. All the data to send as a payload should come from the menuChanged event.

Apply a configuration

This event is applicable to all products. It allows the modification of a product, by changing the value of any available parameter.

Payload description

The request payload for the applyConfiguration event must follow this format:

Attribute name	Type	Content
productUuidToModify	string?	The optional UUID of the product to modify if you use a local scope, null if you use a global scope (applies the configuration to all products).
parameterScope	string	Can be one of the following: global: to apply on all products. local: to apply to the provided product uuid only.
parameterId	string	The identifier of the parameter to modify.
parameterType	string	The type of the parameter. One of: boolean color integer material number product string
parameterValue	null string number boolean Product	The value to set for this parameter. Its type depends on the parameterType. boolean: boolean color: string integer: integer material: ProductParameterValue number: number product: ProductParameterValue string: string

When sending a "Product" in the parameterValue, the value is an object that need to define the following attributes:

Attribute name	Type	Content
dbId	string	The database identifier of the product to set as a value.

Example

const configurationData = {
    productUuidToModify: "productUUID",
    parameterScope: "local",
    parameterId: "boolean_parameter_id",
    parameterType: "boolean",
    parameterValue: true,
};
// Apply a configuration.
configurator.dispatchEvent(new CustomEvent("applyConfiguration", {detail: configurationData}));

Add a component

This event is only applicable to modular products. It will add a module to the current composition, on a given anchor.

Payload description

The request payload for the addComponent event must follow this format:

Attribute name	Type	Content
productDbIdToAdd	string	The database identifier of the product to add.
parentProductUuid	string	The UUID of the product to attach to.
parentAnchorUuid	string	The UUID of the anchor to attach to.

Example

const configurationData = {
    productDbIdToAdd: "my-model-2-seaters",
    parentProductUuid: "parent-uuid",
    parentAnchorUuid: "anchor-uuid",
};
// Add a component.
configurator.dispatchEvent(new CustomEvent("addComponent", {detail: configurationData}));

Remove a component

This event is only applicable to modular products. It will remove a module from the current composition.

Payload description

The request payload for the removeComponent event must follow this format:

Attribute name	Type	Content
productUuidToRemove	string	The UUID of the component to remove.

Example

const configurationData = {
    productUuidToRemove: "module-uuid"
};
// Remove a component.
configurator.dispatchEvent(new CustomEvent("removeComponent", {detail: configurationData}));

Replace a component

This event is only applicable to modular products. It will replace a module in the current composition by another one.

Payload description

The request payload for the replaceComponent event must follow this format:

Attribute name	Type	Content
productUuidToReplace	string	The UUID of the component to be replaced.
productDbIdToAdd	string	The database identifier of the product to load.

Example

const configurationData = {
    productUuidToReplace: "uuid-of-the-product-the-remove",
    productDbIdToAdd: "dbid-of-the-new-product",
};
// Replace a component by another one.
configurator.dispatchEvent(new CustomEvent("replaceComponent", {detail: configurationData}));

Set anchor selection

This event is only applicable to modular products. When displaying a modular product, some anchors can be displayed and the user can interact with them. An anchor is used to attach a module to another module.

You can force the state of the anchor selection. Usually it is used to unselect an anchor when going back in the menu.

Payload description

When using the setAnchorSelection event, you have two choices:

• You want to "unselect": send a null payload.
• You want to "select" an anchor: send an object with the following attributes:

Attribute name	Type	Content
productUUID	string	The UUID of the product on which the anchor exists.
anchorUUID	string	The UUID of the anchor.

Example

const anchorData = {
    productUUID: "product-uuid",
    anchorUUID: "anchor-uuid",
};
// Set the anchor selection
configurator.dispatchEvent(new CustomEvent("setAnchorSelection", {detail: anchorData}));