3 - Initialization

This page describes how to initialize the product configurator.

You will need to know how to set attributes or send events to the configurator 🔗

Mandatory input data

warning

To use the Product Configurator, you have to set the content to load. They are multiple ways of loading content, as described below.

Simple product load

The most common use case: you want to load a product. You only need two attributes:

Attribute name	Attribute value
data-distribution-id	The id of your application distribution.
data-product	The database id of the product you want to load.

Assembly load

You can load an already configured product as a string (an "Assembly")

Common use case:

• You load a default product 🔗
• You retrieve the assembly 🔗, and save it for later use.
• Then you want to reload the saved product.

Since the assembly can be a little heavy, you will not send it as a DOM attribute.

First, set the required attributes so the configurator knows it has to wait for the assembly:

Attribute name	Attribute value
data-distribution-id	The id of your application distribution.
data-use-assembly	"true"

Then, when the page is loaded, you will need to send the assembly itself in an initialization event.

info

See the communication page to know how to send an event 🔗.

const dataToLoad = {
    appConfigData: {
        assembly: "[The assembly as a string]"
    },
}
configurator.dispatchEvent(new CustomEvent("configuratorInit", {detail: dataToLoad}));

Optional initial configuration

When you load some content, you can choose to override the values of some parameters.

info

This works when loading a product, 🔗 but also when loading an assembly. 🔗

Use cases

Use case 1: one product, multiple product sheets

• You have a product in our database that comes in blue fabric by default, and you can change its color between 10 fabrics.
• On your website you created 10 product sheets, one per fabric.
• You can load the same product on each product sheet, and use the initial configuration to choose the correct fabric.

Use case 2: configuration options before displaying the 3D viewer

• You have a product in our database that comes in multiple variants, and the user can switch between them.
• On your website, you let the user make important choices before opening the Product Configurator.
• When you load the Product Configurator, you can give it the product and the choices already made by the user.

Limitations

• You have to be careful with the eventual product rules you have. If you send a finish that is not compatible with the default state of the product, it will not load.
  • Example: if you have a parameter that limits the available values for another parameter, make sure to send both of them to make sure they are applied.
• For modular products, the parameters you will send will be applied to all modules.
  • This means that you cannot set a value for one module and another value for another module.
• You cannot add, replace or remove a module in a modular product.

Data to send

You will need to set the initial configuration data in the following DOM attribute, along with the content to load.

Attribute name	Attribute value
data-initial-configuration	A JSON array containing the list of parameters to set on the loaded content.

The objects you add in the array should follow this format:

Attribute name	Type	Content
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 Input	The value to set for this parameter. Its type depends on the parameterType. boolean: boolean color: string integer: integer material: Product Input number: number product: Product Input string: string

Product Input

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

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

Example

HTML attribute example

<product-configurator data-initial-configuration='[{"parameterId": "finish", "parameterType": "product", "parameterValue": { "dbId": "blue_fabric"}}]'>
</product-configurator>

Typescript example

const initialConfiguration = [
  {
    parameterId: "finish",
    parameterType: "product",
    parameterValue: { dbId: "blue_fabric" },
  },
  {
    parameterId: "width",
    parameterType: "integer",
    parameterValue: 80,
  }
];
const productConfigurator = document.createElement("product-configurator");
productConfigurator.setAttribute("data-initial-configuration", JSON.stringify(initialConfiguration));

Other data

info

The best way to configure the optional attributes is to set their value in your application distribution, but you can also choose to configure it in the DOM.

The values you set in the DOM will override the eventual values from the Application Distribution.

See the Product Configurator integration dedicated page 🔗.

When using HTML attributes of the Product Configurator, the general rule is that all values are strings including values inside JSON fields:

<product-configurator data-number-attribute="1.2"
                      data-boolean-attribute="false"
                      data-json-attribute='{"innerNumberAttribute": "42", "innerBooleanAttribute": "true"}'>
</product-configurator>

The Product Configurator also comes with an integrated documentation of available attributes. 🔗

You can use it to check the default value, type or name of all available attributes.