The Product Loading Screen

This topic dwells on how to customize the product loading screen in Customer's Canvas. 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 in order to inform a user about the error.

All the cases described above can be handled using the loadEditor method. It accepts the onFirstLoad callback functions as its optional parameter and returns a Promise. Using this, you can handle successful product loads and catch errors thrown when a product is loading. Let us see how it works:

JavaScript
<!DOCTYPE html>

<html lang="en">
<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="http://code.jquery.com/jquery-2.1.1.min.js"></script>
    <script type="text/javascript" src="http://example.com/Resources/Libs/jquery/loadmask/jquery.loadmask.min.js"></script>
    <link href="http://example.com/Resources/Libs/jquery/loadmask/jquery.loadmask.css" rel="stylesheet" type="text/css" />
    <!-- The IFrame API script. IMPORTANT! Do not remove or change the ID. -->
    <script id="CcIframeApiScript" type="text/javascript" src="http://example.com/Resources/SPEditor/Scripts/IFrame/IframeApi.js">
    </script>
</head>

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

<script>
    //Defining the product.
    productDefinition = { surfaces: [ "postcard" ] };
    
    var editorFrame = $("#editorFrame");
    
    var editor = null;
    
    var frameParent = editorFrame.parent();

    //Loading the product into the editor.
    frameParent.mask("Loading...");
    //Loading the editor.
    CustomersCanvas.IframeApi.loadEditor(editorFrame[0], productDefinition, 
                                        function () { frameParent.mask("The product is being configured for the first launch. It may take a while.") })
        //If the product is successfully loaded into the editor.
        .then(function (e) {
        editor = e;
        //Hiding a load message.
        frameParent.unmask();
    })
        //If there was an error thrown when loading the editor.
        .catch(function (error) {
        //Displaying user-friendly error message.
        frameParent.mask("An error occured.");
        console.error("Load failed with exception: ", error);
    });
</script>
  1. In the first step, a default loading message is displayed; in the snippet it is "Loading...".
  2. After that, we load the product into the editor and provide an onFirstLoad callback function as its parameter. If it is the first launch of a product, then the loading message is replaced with "The product is being configured for the first launch. It may take a while.".
  3. If the product is loaded successfully, the loading message is hidden.
  4. If an exception is thrown when the product is loading, the loading message is replaced with the "Server error." message.

See Also

Manual

IFrame API Reference