TrophyCustomer's Canvas is honored with a 2020 InterTech Technology Award! Learn more 

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, preloader has the enabled property that shows or hides this preloader. It is true by default.

Custom Preloader

You may want to change the appearance of the standard preloader, for example, change the default icon, colors, or animation. In this case, you need to customize the styles.

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:

  1. Disable the standard preloader.
    let editorConfig = {
        preloader: {
            enabled: false
        }
    };
    
  2. Create a CSS file with your custom implementation in the ~\Configuration\customCss\ subfolder.
  3. Apply your CSS file:
    1. 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" />
      
    2. 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.

See Also

Manual

IFrame API Reference

Downloads