Skip to main content

Product Configuration

Mapping your product’s properties and values​

Your 3D product will be set up with an array of properties that may be configured, and values that those properties may be set to, mapped out in the configurability matrix provided to you by Dopple.

These properties and values may control things like the materials, colors, meshes, environments, and more.

For example, say a sofa product has been set up with three configurable properties:

  1. Sofa type
  2. Sofa material
  3. Sofa color

The sofa type could have values that swap the 3D mesh, such as toggling between a two-seater or three-seater sofa. In this case, these values are predefined in the platform.

The sofa material could have values that swap the base texture that is applied to the mesh, such as leather or fabric materials. In this case, these values are predefined in the platform.

The sofa color could have values that set the albedo color of the texture to some RGB value, such as [202, 23, 39] for a crimson color. In this case, the values can be set by the UI to any valid RGB value (between [0, 0, 0] and [255, 255, 255]).

As you prepare to add buttons and inputs to your UI to control your 3D product, you will need these properties and their corresponding values to pass to the Visual instance.

Updating the product using setValue()​

With your product’s properties and values ready, the setValue method may be called on the Product instance. setValue() requires two parameters:

  1. A property on the product to be updated (must be a string).
  2. A value to update the property to (must be either a string or a valid RGB color value array).

For example:

JS
// setValue() using a string value
product.setValue('my_property_1', 'my_value')

// or... setValue() using an RGB array value
product.setValue('my_property_2', [255, 255, 255])

Using the sofa example from earlier, a setValue call may look like this:

JS
// setValue() updating the sofa's mesh
product.setValue('sofa_style', 'two_seater')

// or... setValue() updating the sofa's material
product.setValue('sofa_material', 'material_fabric')

// or... setValue() updating the sofa's color
product.setValue('sofa_fabric_color', [110, 60, 30])
tip

setValue may be called anytime after the Product has been loaded, such as when a user clicks a <button> on the page to update the product’s configuration to a new state.

Overriding default configurations using setValue​

While a product’s default configuration values should be set within the product’s manifest, setValue may also be called as soon as the Product has finished loading to immediately show the product with any desired values.

JS
const loadProduct = async () => {
    // ...
    
    new Atlatl.LoadingScreen(visual, function onShow() {
        // ...
    }, function onHide() {
        // Call setValue on the Product as soon as the loading screen hides 
        myProduct.setValue('some_property', 'some_value')
        myProduct.setValue('another_property', 'another_value')
        myProduct.setValue('rgb_property', [255, 255, 255])
    });

    // ...
}

Full code example​

index.html
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>My Page</title>
        <!-- Link to the Visual API's scripts -->
        <script src="https://builds.dopple.io/atlatl-visual-api/releases/current/index.js" defer></script>
        <!-- Link to custom scripts -->
        <script src="scripts.js" defer></script>
    </head>
    <body>
        <!-- Canvas to render the 3D scene to -->
        <canvas id="my-canvas"></canvas>
        <div>
            <!-- Button to change the product's configuration -->
            <button id="my-button">My button</button>
        </div>
    </body>
</html>