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://configurator.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:

configurator-example.html

<!DOCTYPE html>
<html style="height: 100%">
<head>
    <title>Configurator iframe Example</title>
    <meta charset="UTF-8">
    <script type="text/javascript">
        let cmConfigurator;
        window.onload = () => {
            cmConfigurator = document.getElementById("cmConfigurator").contentWindow;
        }
    </script>
</head>
<body style="width: 100%; height: 100%; margin: 0;">
<iframe id="cmConfigurator"
        src="https://configurator.colormass.com?sceneId=990"
        style="width: 100%; height: 100%; border: none"
        allowfullscreen>
</iframe>
</body>
</html>

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:

{
    data: {
        method: string,
        parameters: {}
    },
    type: "colormass"
}

When using the postMessage() method, make sure to pass the targetOrigin parameter as shown below, otherwise the messages won't be dispatched.

const message = {
    data: {
        method: "showUi",
        parameters: {value: false}
    },
    type: "colormass"
}
cmConfigurator.postMessage(message, "https://configurator.colormass.com");

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:

const message = {
    data: {
        method: "options"
    },
    type: "colormass"
}

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:

window.onload = () => {
    cmConfigurator = document.getElementById("cmConfigurator").contentWindow;
    window.addEventListener("message", receiveMessage, false);
}

function receiveMessage(message) {
    if (message.data.type === "colormass" && message.data.data.method === "loadingCompleted") {
        let optionsMessage = {
            data: {
                method: "options"
            },
            type: "colormass"
        }
        cmConfigurator.postMessage(optionsMessage, "https://configurator.colormass.com");
    }
}

If you run the above code, you should see the following options printed to the console:

[
    {
        id: "ced9d80c-7103-43f2-a5ba-2d90e0c823b3",
        name: "Seat",
        variants: [
            {id: '3d7420d9-6117-428f-ba41-890ecd157f8e', name: 'Blazer Darthmouth'}
            {id: 'e6ddc079-8026-4e4f-95ca-6e2be019a0f6', name: 'Oceanic Atoll'}
            {id: '18479bf9-e393-4da9-9fc9-dfb37077550b', name: 'Lucia Tenom'}
            {id: '1d9f7d3d-3823-4224-a3f7-62028295080f', name: 'Velocity Polar'}
            {id: 'ec17fd8c-6131-46d8-8bdd-a2ac0f9d29a6', name: 'Main Line flax Farring'}
            {id: '27d9baf3-84fb-476b-8312-e348b46c1e40', name: 'Steam PDY'}
            {id: '087612ab-9a50-43e3-8626-b1c37322b499', name: 'Leather'}
        ]
    },
    {
        id: "60a5a88a-7701-4c10-819e-deb5f87f15c4",
        name: "Back",
        variants: [
            {id: 'c93e318c-88ee-4e8c-9b56-9c7075f53784', name: 'Main Line Flax Bayswater'}
            {id: '4c190056-bc69-49f5-a081-c82a86658124', name: 'Synergy Quilt Chemistry'}
            {id: '42763086-b3e6-48cb-ac63-2172f2245bf9', name: 'Synergy Quilt Group'}
            {id: '918f01a2-a890-42e7-94a8-fb0c821ab3b5', name: 'Carlow Callan'}
            {id: '931d70b6-a156-4fa8-bf3d-f8b817f28516', name: 'Main Line Flax Lambeth'}
        ]
    }
]

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.

let message = {
    data: {
        method: "option",
        parameters: {
            groupId: "ced9d80c-7103-43f2-a5ba-2d90e0c823b3",
            variantId: "e6ddc079-8026-4e4f-95ca-6e2be019a0f6"
        }
    },
    type: "colormass"
}
cmConfigurator.postMessage(message, "https://configurator.colormass.com");

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 .

PreviousGetting Started NextAPI Reference

Last updated 1 month ago