Setting Parameters

Parameters let you adjust the settings of a configurator instance in two ways:

1. Initial Parameters via HTML: You can set an initial configuration by adding a set of parameters directly to the configurator's HTML tag. This approach is useful for loading a predefined configuration when the configurator first loads.

2. Dynamic Parameters at Runtime: You can also modify parameters at runtime by calling setParameter on the configurator. This method is helpful when building a custom menu or control interface for the configurator.

Note that colormass typically provides the necessary parameter settings, so you do not need to understand the details of the parameter format beyond those two points. The following example adds an initial parameter to the HTML tag by using the parameters attribute:

<cm-configurator-main
	template-uuid="9f867cb8-966f-4736-9106-3cacba50b3b4"
	parameters="param(3d23006d-1eb2-47f1-a616-e357695316b8)=material(2d8709e8-d5b9-4028-86b1-d06e8575011b)"
></cm-configurator-main>

The same parameter can also be set at runtime:

<script>
	customElements.whenDefined("cm-configurator-main").then(() => {
		cmConfigurator = document.querySelector("cm-configurator-main")
		cmConfigurator.setParameter("3d23006d-1eb2-47f1-a616-e357695316b8", "material", "2d8709e8-d5b9-4028-86b1-d06e8575011b")
	})
</script>

Parameter Format

A configurator parameter is composed of three parts: id, type and value. Values for those parts are usually provided by colormass, but if you have access to the platform, you can also get and edit the available parameters yourself. This is covered in a separate section below.

• id: This is a unique identifier for the parameter. This ID is usually platform-generated but can be customized for readability.

• type: Specifies how the configurator interprets and processes the value. Different types, like "material" or "config" determine the behavior and application of the parameter within the configurator.

• value: The specific value to be used with the parameter. Depending on the type, this value can also be customized for better readability.

The parameter string used to load a given configuration is usually provided by colormass. If you need to change it, the format is as follows:

param(id)=type(value)

When multiple parameters should be set, they are separated by &:

param(id1)=type(value1)&param(id2)=type(value2)

Parameter Types and Associated Values

All parameters originate from input elements that were used to build the configurator on the colormass platform. The type of a parameter defines what the configurator will assign to those elements internally. The following types are available:

config

This type controls configurations that are also available in the configurator’s menu. It allows to programmatically load a specific configuration variant displayed there. A config parameter is derived from a config group within the configurator’s template, and the values it accepts are the IDs of that group’s config variants (see figures below). Available variants for a config parameter can also be retrieved via cmConfigurator.getParameterList().

Config group inside the template editor. The ID of the group is part of the parameter ID.

Config variant, whose ID can be used in cmConfigurator.setParameter.

material

This type assigns a material to the configurator, even if it is not available in the configurator’s menu. The required value is a material ID, which you can retrieve via our GraphQL API. Instructions for accessing the API are available here, and you can build and test queries directly on the API test page.

material-article-id

This type is used to assign a material by specifying your own in-house ID. The ID must be set up on the details page of the material on the colormass platform:

Getting Available Parameters

In order to get the currently available parameters, you can use getParameterList:

<script>
    customElements.whenDefined("cm-configurator-main").then(() => {
        cmConfigurator = document.querySelector("cm-configurator-main")

        //Parameters are only available after a configurator was loaded. loadingCompleted is emitted after the initial loading completes
        cmConfigurator.addEventListener("loadingCompleted", (event) => console.log("Current parameters", cmConfigurator.getParameterList()))
        //configurationLoaded is emitted after a new configuration selected by the user was loaded
        cmConfigurator.addEventListener("configurationLoaded", (event) => console.log("Current parameters", cmConfigurator.getParameterList()))
    })
</script>

API Limitations

When creating a custom menu or controls for a configurator, be aware that the configurator’s API currently does not provide information on parameter dependencies. In complex configurators, certain configurations are hidden or shown based on the currently selected variant. Consequently, calls to cmConfigurator.getParameterList() may not always list every available parameter. After a parameter with dependencies is changed, subsequent calls to getParameterList() may return a different set of parameters.