Configurator iframe Example

# 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 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](https://developer.mozilla.org/en-US/docs/Web/Security/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](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). ## **Basic Setup** To begin with, create an HTML file and copy paste the following code: {% code title="configurator-example.html" lineNumbers="true" %} ```html Configurator iframe Example ``` {% endcode %} 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: 1. It embeds the configurator using an iframe element. 2. Accessing the [contentWindow](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement/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: {% code lineNumbers="true" %} ```json { data: { method: string, parameters: {} }, type: "colormass" } ``` {% endcode %} When using the `postMessage()` method, make sure to pass the `targetOrigin` parameter as shown below, otherwise the messages won't be dispatched. {% code lineNumbers="true" %} ```javascript const message = { data: { method: "showUi", parameters: {value: false} }, type: "colormass" } cmConfigurator.postMessage(message, "https://configurator.colormass.com"); ``` {% endcode %} 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: {% code lineNumbers="true" %} ```javascript const message = { data: { method: "options" }, type: "colormass" } ``` {% endcode %} 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: {% code lineNumbers="true" %} ```javascript 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"); } } ``` {% endcode %} If you run the above code, you should see the following options printed to the console: {% code lineNumbers="true" %} ```javascript [ { 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'} ] } ] ``` {% endcode %} 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. {% hint style="info" %} 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. {% endhint %} ## **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*. {% code lineNumbers="true" %} ```javascript 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"); ``` {% endcode %} 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:

{% hint style="warning" %} 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. {% endhint %} 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 . --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.colormass.com/dev/configurator/iframe-integration/advanced-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.