Rubens Knowledge Base

How to control the configurator with external parameters outside of the configurator iFrame?


The Roomle Embedding API gives you the possibility to get and set parameters inside the Roomle Configurator from outside. This means your web shop is able to change parameters of the configuration based on some logic you can define.

Who should use this functionality?

This functionality is useful for every web shop which has special logics when and how to set a given parameter. For example you could preset parameters based on the geo-location of the user. This can be helpful for things like electricity connectors. For US users you set the parameter to something different than for EU users. 
Another use case would be to change the UX slightly. Maybe there is some very important parameter which should be visible all the time no matter what the user is doing inside the configuration. Then you can set up the controls for these parameters outside of the configurator directly within your web shop. Ideally, you set these parameters to "hidden" inside the Roomle Configurator.

How can this be implemented with API?

It is important that the parameters you want to change from outside are "well-known". This means that you know the name of the parameters. The name of the parameters can be anything and are defined during scripting. For example, the width parameter can be named something like "shelfWidth". If the parameter name is calculated dynamically that's not possible.


The following code snippet should give you an idea of how to implement the above-described behavior:

Code snippet external parameter control

(async function() {
const minWidth = '10rem';
const params = await RoomleConfigurator.getParametersOfRootComponent();
const viewParam = params.find(({key})=>key==='view');
if(!viewParam) {
console.warn('Configuration has no view param');
const parent = document.getElementById('roomle-configurator').parentNode;
if(!parent) {
console.warn('No Roomle Configurator found');
const wrapper = document.createElement('div');
viewParam.validValues.forEach(({value,label})=> {
const button = document.createElement('div');
const span = document.createElement('span');
span.innerText = label;

    span.classList.add('btn','btn-primary'); = minWidth; = '1rem';
    button.addEventListener('click', ()=> RoomleConfigurator.setParameterOfRootComponent(viewParam,value));
}); = 'grid'; = '1fr ' + minWidth; = '10px';

  await RoomleConfigurator.setParameterOfRootComponent(params[0], 'all');