Product Configuration

Within the Dopple platform, a product may be setup with a variety of configurable properties — such as the fabric on a sofa, or the body paint color of a car — and each property may have a variety of options that it may be set to.

For example, a configurable luggage product may have properties for color, luggage-view, and add-ons.

The options for the color could include a number of different materials and colors, such as black, light-gray, evergreen, and so on.
The luggage-view property may only have two boolean-like open and closed options.
The options for add-ons property may toggle a number of meshes on/off within the scene, such as with toiletry-bag, interior-cubes, both, or none.

Configurability Values

The values for each configurable property and option on a product can be found in the Dopple platform under the Configurability tab on the Product Overview page for that product.

Continuing the luggage example above, the table of values may look like this:

Property	Option
`color`	`black`
	`light-gray`
	`white`
	`cherry`
	`evergreen`
`luggage-view`	`open`
`luggage-view`	`closed`
`add-ons`	`none`
	`toiletry-bag`
	`interior-cubes`
	`both`

These values will be used when passing a default selection object during initialization or when calling updateSelection() to update the configuration.

The Product Matrix

You can view all of the metadata about the scene by calling dopple.matrix once the product has loaded.

const dopple = new DoppleXR({ /* ... */ });
await dopple.load();

console.log(dopple.matrix);

This product matrix contains information about all of the configurable properties and options available on a product, the environments and hotspots in the scene, and more.

// Get the list of all configurable properties
const configurableProperties = dopple.matrix.choices;

// Get all environments in the current scene
const environments = dopple.matrix.environments;

// Get all hotspots in the current scene
const hotspots = dopple.matrix.hotspots;

Default Configuration

When a new dopple instance is first created on your page, the scene (which includes any products, environments, cameras, and hotspots will load with the default values for the properties and options that were set when the product was published.

However, a selection object may be passed during initialization to override the scene’s default configuration, and instead set a new configuration for the 3D scene to initially load with.

Each key of the selection object corresponds to the name of the configurable property, and its value corresponds to the option that the property will be set to.

<script type="module">
  const dopple = new DoppleXR({
    container: document.getElementById("dopple-container"),
    owner: "my-org",
    workspace: "my-workspace",
    projectName: "my-luggage",
    productVersion: "1",
    // Load the gray luggage by default, with the "opened" view and only the toiletry bag
    selection: {
      "color": "light-gray",
      "luggage-view": "open",
      "add-ons": "toiletry-bag",
    },
  });
</script>

Dynamic Defaults with URL Parameters

A common scenario you may encounter is having a single “base” product page (for example: /products/luggage) that uses URL Search Parameters to specify which product variant is being shown to the user (such as /products/luggage?color=light-gray).

Before initializing your 3D product, you can check the URL for any URL Search Parameters and use them to set a new default configuration for the 3D product accordingly.

// Define an initial default selection
const defaultSelection = {
  "color": "light-gray",
  "luggage-view": "open",
  "add-ons": "toiletry-bag",
}

// Get any parameters from the current URL
// e.g. "/products/luggage?color=light-gray&add-ons=none"
const urlParams = new URLSearchParams(window.location.search);

// Update any parameters in the default selection if they're found in the URL
for (const [property, value] of urlParams) {
  if (defaultSelection.hasOwnProperty(property)) {
    defaultSelection[property] = value;
  }
}

// Initialize your 3D product
const dopple = new DoppleXR({
  /* ... */
  selection: defaultSelection,
});

This can help speed up load times drastically by ensuring the necessary assets for that default variant are loaded first.

Updating the Configuration

Use the updateSelection() method to update the 3D product’s current configuration, as well as other options in the scene such as hotspots, cameras, or environments.

const dopple = new DoppleXR({ /* ... */ });

await dopple.updateSelection({
  "color": "white",
});

The object passed to updateSelection() may include one or multiple property/option pairs, to update any number of properties and options at the same time.

const dopple = new DoppleXR({ /* ... */ });

await dopple.updateSelection({
  "color": "black",
  "luggage-view": "closed",
  "add-ons": "both",
});

Updating multiple properties at once can be especially useful when showing “preset” configuration options in your UI, or for resetting the product back to its default configuration.

When passing a selection object to updateSelection(), you only need to include the properties that will be updated. In other words, you don’t need to pass an object with all of the configurable properties if only a few should be updated.

await dopple.updateSelection({
  "primary_color": "red",
  "secondary_color": "green",
});

await dopple.updateSelection({
  "primary_color": "blue",
   "secondary_color": "green", // Not needed (already set to green above)
});

In the example above, the second call to updateSelection() does not need to include the secondary_color property, since it’s already set to green in the first call.

Getting the Current Configuration

To get the current configuration of the 3D product at any time, simply get the selection object on your dopple instance.

const dopple = new DoppleXR({ /* ... */ });

const currentSelection = dopple.selection;

Live Demo

Full Code Example

<html>
  <head>
    <script type="module">
      // Import Dopple
      import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";

      // Define a default selection
      const defaultSelection = {
        "color": "black",
        "luggage-view": "closed",
        "add-ons": "both",
      }

      // Initialize your 3D product
      const dopple = new DoppleXR({
        container: document.getElementById("dopple-container"),
        owner: "my-org",
        workspace: "my-workspace",
        projectName: "My Product",
        productVersion: "1",
        selection: defaultSelection,
      });

      await dopple.load();
      dopple.resize({ trackParentSize: true });
      dopple.run();

      // Handle new body color selections
      const colorSelect = document.getElementById("color-selection");
      colorSelect.addEventListener("change", async () => {
        await dopple.updateSelection({
          "color": colorSelect.value
        });
      });

      // Handle new luggage view selections
      const viewSelect = document.getElementById("view-selection");
      viewSelect.addEventListener("change", async () => {
        await dopple.updateSelection({
          "luggage-view": viewSelect.value
        });
      });

      // Handle resetting the product back to its default configuration
      const resetButton = document.getElementById("reset-button");
      resetButton.addEventListener("click", async () => {
        await dopple.updateSelection(defaultSelection);
        console.log("The current selection has been reset to:", dopple.selection);
      })
    </script>
  </head>
  <body>
    <!-- Create a container for the 3D product -->
    <div id="dopple-container"></div>

    <!-- Add selection options for the "color" and "luggage-view" properties -->
    <label for="color-selection">Luggage Body Color:</label>
    <select id="color-selection">
      <option value="black">Black</option>
      <option value="light-gray">Light Gray</option>
      <option value="white">White</option>
      <option value="cherry">Cherry Red</option>
      <option value="evergreen">Evergreen</option>
    </select>

    <label for="view-selection">Luggage View:</label>
    <select id="view-selection">
      <option value="open">Open</option>
      <option value="closed">Closed</option>
    </select>

    <!-- Add a "Reset" button -->
    <button id="reset-button">Reset Configuration</button>
  </body>
</html>