The Product Loading Screen

This topic dwells on how to customize the product loading screen in the Design Editor. While a product is loading, there are three moments that may confuse a user:

The first launch of a product is usually time-consuming, and if users are not warned about this, they may be confused. So, it is a good idea to ask users to wait and tell them that the product will load faster on the second and following launches.
The second and following product loads are also not instantaneous and displaying a message explaining that the system is working and a product is loading can help to avoid unwanted actions like page refreshing.
Sometimes errors happen, and if this is the case, the related message has to be displayed to inform a user about the error.

Standard Preloader

The listed cases can be handled using the loadEditor method that accepts the preloader object as an optional configuration parameter. Using this parameter, you can display custom messages when a product is loading. The following example shows how this works.

HTML

<!DOCTYPE html>

<html lang="en">
<head>
    <meta charset="utf-8" />
    <!-- The IFrame API script. IMPORTANT! Do not remove or change the ID. -->
    <script id="CcIframeApiScript" type="text/javascript" src="https://{yourInstanceUrl}/Resources/Generated/IframeApi.js">
    </script>
</head>

<body>
    <!-- The iframe to display the editor in. -->
    <iframe id="editorFrame" width="100%" height="800px"></iframe>
</body>
</html>

<script>

    var editor = null;

    // Defining the product.
    let productDefinition = {
        surfaces: ["postcard"]
    };

    // Configuring the preloader messages in the editor's config.
    let editorConfig = {
        preloader: {
            firstTimeMessage: "Wait a moment. The product is being configured for the first launch.",
            errorMessage: "An error occurred!"
        }
    };

    // Loading the editor.
    CustomersCanvas.IframeApi.loadEditor(document.getElementById("editorFrame"), productDefinition, editorConfig)
        // If the product is successfully loaded into the editor, you can refer to the instance.
        .then(function (e) {
        editor = e;
    });
</script>

Here, we configure the preloader object. The firstTimeMessage property specifies what message is shown for the first launch of a product. If it is not set, then "The product is being configured for the first time. It may take a while." appears by default. The errorMessage property specifies what message is shown if an exception is thrown while loading the product.

Also, the preloader has the enabled property that shows or hides this preloader. It is true by default.

To change the default icon or its color, you can pass themeConfiguration into the editor. As a result, the editor will open with the new preloader.

JavaScript

let editorConfig = {
    themeConfiguration: {
        primaryColor: "#0090FF",
        logo: "https://example.com/logo.svg"
    }
};

Here, primaryColor redefines the primary color for the UI theme, and logo changes the preloader image. To specify a color, pass a string in the CSS format. The image can be specified through either a URL, a base64 string, or an SVG element.

You can also change the preloader style at runtime as follows:

JavaScript

await editor.setThemeConfiguration({
    primaryColor: "rgb(120, 24, 123)",
    logo: "https://example.com/logo.svg"
});

Custom Preloader

You can also implement your own preloader with a different animation.

If you build the Design Editor from source code, you can change the styles of the standard preloader in the \src\design-editor-iframe-api\LoadMask\LoadMask.less file. For example, to display a new image, define the .icon-cc-logo:before style in either LoadMask.less or your custom CSS file as follows:

CSS

.icon-cc-logo:before {
    background-image: url('logo.svg');
    background-position: 0 0;
    display: block;
    height: 100px;
    width: 100px;
    content: "" !important;
}

If you have a cloud version or a compiled on-premises version, then you can develop a custom preloader:

Disable the standard preloader.

let editorConfig = {
    preloader: {
        enabled: false
    }
};

Create a CSS file with your custom implementation in the ~\Configuration\customCss\ subfolder.

Apply your CSS file:

Add a link to your styles in the file where you load the editor from.

<link rel="stylesheet" href="https://{yourInstanceUrl}/Configuration/customCss/loader.css" />

Pass your styles in the editor's config.

let editorConfig = {
    customStyle: "loader",
    preloader: {
        enabled: false
    }
};

For reference, you can download a code sample illustrating a custom preloader.

The Product Loading Screen

Standard Preloader

Custom Preloader

See Also

Manual

IFrame API Reference

Downloads