Add custom overlays (advanced)

To add a custom view you have two options. Either you embed it into our UI which means we add an iframe into our page, or you overlay our UI with your own one. Both options have their reason to exist. The embedding into our UI involves less setup and in contrast the overlay gives you more control but needs more steps to be implemented. Currently, this only works nicely for desktop. We are working hard to improve the mobile experience soon.

Let's start with the overlay solution first

Add custom view as overlay

Assume the following scenario:

You have a Room Designer scene, and you want to show a custom view whenever a user selects a specific item, e.g.: USM Frame. Since we build an overlay this requires that you embed the Roomle UI somewhere on your webpage with our embedding lib.

In our example, we want the custom view to always overlay the drawer on the right-hand side. Additionally, the custom overlay should also animate in and out in the same way as the drawer does.

And last but not least, we want the user to be able to drag-in items from the overlay. As always you find the whole example in our CodeSandboxes. Be aware that this is not a copy & paste tutorial, we rather show the important parts of the code. If you want a copy & paste solution checkout our CodeSandbox. Nevertheless, we think it makes sense to go through this tutorial because there are some small gotchas you can easily overlook when simply copying and pasting. But now let's get started.

Basic setup

At first, we prepare the HTML of our webpage:

<div class="ext-overlay-container">
  <div class="custom-overlay hidden">
    <h2>
      USM Selected
      <div class="close"></div>
    </h2>
    <p>
      USM is a very beautiful shelf system therefore it has it's own selection
      page
    </p>
    <p>Drag in more of the nice stuff</p>
    <div class="catalog">
      <img
        src="https://uploads.roomle.com/configurations/usm:frame:FE21EAE6F8B8E90ED9C41AF2328DBEBC56D5A6D341D5F757049862A3A686EDE1/perspectiveImage.png?marker=1730984937"
        draggable="true"
        data-rml-id="usm:frame:FE21EAE6F8B8E90ED9C41AF2328DBEBC56D5A6D341D5F757049862A3A686EDE1"
      />
      <img
        src="https://uploads.roomle.com/configurations/usm:frame:B03B399E27EFF5EC0309373CDD82FABBBBB799092575BBBF9716058F13D5A109/perspectiveImage.png?marker=1730984972"
        draggable="true"
        data-rml-id="usm:frame:B03B399E27EFF5EC0309373CDD82FABBBBB799092575BBBF9716058F13D5A109"
      />
      <img
        src="https://uploads.roomle.com/configurations/usm:frame:3E66F2E9336C621F47C9EC51717E6977165097FA97346EF3025BC955339808BE/perspectiveImage.png?marker=1730984995"
        draggable="true"
        data-rml-id="usm:frame:3E66F2E9336C621F47C9EC51717E6977165097FA97346EF3025BC955339808BE"
      />
    </div>
    <p class="toggle">To toggle the drawer click me</p>
  </div>
  <div id="configurator"></div>
</div>

It is also important to take a look at the CSS to fully understand what's going on:

.custom-overlay {
  position: absolute;
  background-color: white;
  z-index: 999;
  border-left: 1px solid #e7e7e7;
  padding: 1rem;
  box-sizing: border-box;
}

.hidden {
  /**
   * in our example we show/hide based on opacity
   * this makes it easier for us to apply animations
   */
  opacity: 0;
  pointer-events: none;
}

#configurator {
  width: 100%;
  height: 100%;
  box-sizing: border-box;
  position: relative;
  top: 0;
  left: 0;
  /**
   * IMPORTANT: it is very important that the container
   * of the Roomle iframe has it's own CSS stacking context
   * otherwise we can not infer the drag-in position correctly.
   * In our example the easiest way to create a stacking
   * context is by applying a CSS transform to the container
   */
  transform: translate3d(0, 0, 0);
}

.ext-overlay-container {
  position: relative;
  width: 100%;
  height: 100%;
  overflow: hidden;
}

Now after we have the DOM setup we need to create an instance of the Rubens Room Designer. We do it like this:

const instance = await RubensEmbedding.createPlanner(
  'demoRoomDesigner',
  document.getElementById('configurator'),
  {
    autoStart: true,
    moc: true,
    startInDetail: false,
    customView: {
      itemSelection: {
        overlay: true,
        options: {},
      },
    },
  },
);
await instance.ui.loadObject('ps_lzu8f1101goct3a300r7evf0cw7n1zm');

We need special attention for the section at customView. This is a JavaScript object that consists of the name of the customView we want to set as key and the options of the customView. In our case we just set overlay to true to indicate the Rubens Room Designer that instead of the regular view during item selection we show a custom overlay.

So far so clear (especially when you already have a Roomle Rubens embedding setup). To make our overlay interactive we need to glue some code together. First we implement a logic to show and hide it. Therefore, we add the following code before loadObject:

instance.ui.callbacks.onShowCustomView = async (viewName, args) => {
  console.log('onShowCustomView', viewName, args);