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 a configurator-example.html file and copy paste the following code:
<!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:

https://slite.com/api/files/0psl_c7Xx/oceanic-atoll.jpg?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoiVjl2WU1DejNsIiwiaWF0IjoxNzE0ODAzODk3LCJpc3MiOiJodHRwczovL3NsaXRlLmNvbSIsImp0aSI6IkZGSlNOZkpDdV9DODdsIiwiZXhwIjoxNzE3Mzk1ODk3fQ.GPxE1uBDb8aCrHthg2FNT1VGl6LdKSlI9zUCWagH9HM

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⁠ .