Advanced Integration
The colormass configurator comes with a default user interface, so it is quick and easy to get started as described in Getting Started . However, if it is required to customize the UI or control the configurator's behavior programmatically, there is an API to do so.
The configurator is served from the https://ci.colormass.com domain. When it is embedded into a webpage via an iframe, script access to the frame's content is subject to the same-origin policy. Because of this, it is not possible to simply call the configurator's functions. Safe cross-origin communication is only enabled over the window.postMessage()
method. Further information can be found here.
Basic Setup
To begin with, create an HTML file and copy paste the following code:
There is no need to serve the file through a server, it can be opened directly in the browser and the example configurator should load as expected. The above code snippet does two important things:
It embeds the configurator using an iframe element.
Accessing the contentWindow property, it gets hold of the Window object of the iframe, which will be used to communicate with the configurator through messages.
Calling Methods
The configurator expects messages in the following format:
When using the postMessage()
method, make sure to pass the targetOrigin
parameter as shown below, otherwise the messages won't be dispatched.
The above method call hides the default user interface including the panels both on the left and on the right side. As a next step, let's print the configuration options in order to see the available variants. This is done via the options
method. The message should look as follows:
If you post this message the same way as we did for the showUi
method, you will notice that the printed array is empty. The reason for this is that the loading of the configurator is not finished yet at the point in time when the message arrives. You will have to make sure to wait for the loadingComplete
event first.
Listening to Events
Up till now we only used the messaging to communicate towards the configurator (iframe window). Event are implemented using the same mechanism, the configurator sends messages back to the parent window. In order to receive those, we have to initialize an event listener as follows:
If you run the above code, you should see the following options printed to the console:
For this specific configurator there are two configuration groups, the _Seat _and the _Back. _Both of them have multiple variants. In this case those are different fabric options.
Please mind that the configuration options could look very different for your specific configurator based on how it was set up on the back end. However, it always has the same structure: configuration groups containing variants.
Setting Configurations
As a next step, let's add a button to our example which changes the current configuration to a different fabric on the seat of the chair. The method to be used here is called option
. It expects a groupId
and a variantId
. Given that we would like to change the fabric on the seat, we are going to use the group ID ced9d80c-7103-43f2-a5ba-2d90e0c823b3
. For the variant we pick the one called Oceanic Atoll.
Make sure the above message gets posted only after the configurator finished loading, otherwise you are going to get an error. One way to achieve this is to execute the above code only after the loadingCompleted
event fired. Alternatively, you can assign the action to a button and only press it after the default version of the chair loads. If you did everything correctly, you should see the following variation of the chair:
Changing the configuration triggers the loadingCompleted
event once it finished loading. Make sure not to include the above changing logic within the event listener function, because it will lead to an infinite loop.
Having gone through this advanced integration guide, now you should have a good understanding of how the communication between the main window and the iframe is implemented. If you would like to see all the features the API offers, make sure to check out the API Reference .
Last updated