Skip to main content

Customizing the 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
  3. spinningCube

Previews:

defaultScreen
DoppleLoading 3D...
animatedCube
Loading 3D...
spinningCube
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' or 'spinningCube'
})

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 "spinning cube" as the loading screen while the product loads
await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', {
loadingScreenType: 'spinningCube'
})

// 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, 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.

CSS
.custom-loading-screen.done-loading {
visibility: hidden;
}
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)

// Display a custom loading screen element over the canvas while product loads
new Atlatl.LoadingScreen(visual, function onShow() {
// Optional: if the custom loading screen isn't shown by default, it may be shown here
myLoadingScreenElement.classList.remove('done-loading')
}, function onHide() {
// Hide the custom loading screen once loading is completed
myLoadingScreenElement.classList.add('done-loading')
})

// 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()
visual.loadingScreen.hide()
})