Skip to main content

Loading Screen

By default, Dopple Visual will display a “loading” splash screen over the canvas while the Visual instance, product, and assets load. Dopple provides a variety of built-in loading screen options to pick from, but a custom loading screen may be placed over the canvas while products are being loaded.

Choosing a default loading screen​

Out of the box, Dopple provides three different loading screen options to pick from:

  1. defaultScreen — this is the default option if another loading screen is not specified.
  2. animatedCube

Previews:

defaultScreen
Loading 3D...
animatedCube
Loading 3D...

To set one of these options as your loading screen, pass it as the value for loadingScreenType when first initializing Dopple Visual and loading the product on your page:

JS
await visual.initClient(clientId, {
    loadingScreenType: 'defaultScreen' // or 'animatedCube'
})

Full code example​

scripts.js
let visual
let myProduct
let namespace = 'my-namespace'
let name = 'my-product-name'

// Initialize Dopple Visual and load the product once the document is ready
window.addEventListener('load', async () => {
    const renderCanvas = document.getElementById('my-canvas')
    visual = new Atlatl.Visual(renderCanvas)
    
    // Set the "animated cube" as the loading screen while the product loads
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', {
        loadingScreenType: 'animatedCube'
    })

    // Create and load the ProductTemplate
    const template = new Atlatl.ProductTemplate(visual, namespace, name)
    await template.load()

    // Create the Product instance
    myProduct = new Atlatl.Product(template)
    
    // Hide the loading screen to show the product once the product is ready
    await myProduct.ready()
    visual.loadingScreen.hide()
})

Displaying a custom loading screen​

A custom loading screen may be displayed by positioning an element (such as a <div> or <img>) above the canvas on your page, then hiding this element as soon as the product has finished loading.

To do this, it is first recommended to disable the default Dopple-generated loading screen using the showLoadingScreen option when first initializing Dopple Visual:

JS
await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', {
    showLoadingScreen: false // 'true' by default
})

Then, wrap the <canvas> and the custom loading screen element in a container element, then absolutely position the loading screen element above the canvas using CSS and giving the loading screen element an opaque background color.

HTML
<div class="canvas-container">
    <canvas id="my-canvas"></canvas>
    <div class="custom-loading-screen">
        <span>Loading...</span>
    </div>
</div>
CSS
.canvas-container {
    position: relative;
}

.custom-loading-screen {
    background-color: #E0E0E0;
    inset: 0;
    position: absolute;
    z-index: 2;
}

Alternatively, a custom loading screen may be shown at the time of initializing Visual using the onShow() function available on the Atlatl.LoadingScreen method. This method should be the second parameter passed to the LoadingScreen (the first being the Visual instance itself).

JS
new Atlatl.LoadingScreen(visual, function onShow() {
    // Show the custom loading screen
    document.querySelector('.custom-loading-screen').classList.remove('done-loading')
})
NOTE

Dopple Visual will not run onShow() if showLoadingScreen: false is used when calling initClient. Be sure to set showLoadingScreen to true, or remove it altogether.

JS
await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', {
    showLoadingScreen: true
})

Hiding a custom loading screen​

To hide the custom loading screen once the product has finished loading, await product.ready() to resolve before adding or removing your loading screen’s visibility classes accordingly.

CSS
.custom-loading-screen.done-loading {
    visibility: hidden;
}
JS
await product.ready()
document.querySelector('.custom-loading-screen').classList.add('done-loading')

Alternatively to awaiting product.ready(), Atlatl.LoadingScreen also accepts an onHide() function as its third parameter.

Similar to the onShow() function above, onHide() will be run as soon as the product is fully loaded and ready.

JS
new Atlatl.LoadingScreen(visual, function onShow() {
    // Show the custom loading screen
    document.querySelector('.custom-loading-screen').classList.remove('done-loading')
}, function onHide() {
    // Hide the custom loading screen
    document.querySelector('.custom-loading-screen').classList.add('done-loading')
})

Full code example​

scripts.js
let visual
let myProduct
let namespace = 'my-namespace'
let name = 'my-product-name'
let myLoadingScreenElement = document.querySelector('.custom-loading-screen')

// Initialize Dopple Visual and load the product once the document is ready
window.addEventListener('load', async () => {
    const renderCanvas = document.getElementById('my-canvas')
    visual = new Atlatl.Visual(renderCanvas)
    
    // Replace with your client ID here
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', {
        // Disable the default Dopple-generated loading screen
        showLoadingScreen: false
    })

    // Create and load the ProductTemplate
    const template = new Atlatl.ProductTemplate(visual, namespace, name)
    await template.load()

    // Create the Product instance
    myProduct = new Atlatl.Product(template)
    
    // Hide the loading screen to show the product once the product is ready
    await myProduct.ready()
    myLoadingScreenElement.classList.add('done-loading')
})