Customizing the Loading Icon

The loading icon is displayed when data is sent to and from your site. On desktop devices, the default behavior tracks the cursor around the page and is hidden when the transfer is complete. On mobile devices, there is no cursor loading icon, therefore no loading icon is shown during loading.

This section outlines two ways you can customize the loading icon. You can replace the loading icon image without changing it's behavior, or you can fully customize the user experience. For instance, you may want to add loading bars or a full-screen loading page.

To find out more, explore these topics:

Replacing the Loading Icon Image
Replacing the Loading Icon with Custom Loading Behavior
Adding Cursor Tracking

Replacing the Loading Icon Image

Note:

The following procedure does not disable the JavaScript associated with the loading icon.

This section outlines how to replace the loading icon image, without changing it's existing behavior. The loading icon is an image asset included with your site’s source code. To replace the loading icon image, you should change it in the source code with an alternative image that has the same name as the default. This is typically named, ajax-loader.gif. After you deploy your site's source code, the new loading icon appears on your site.

Depending on the type of site and what version you are using, you can find the source code in the following locations:

For sites using the Kilimanjaro release of SuiteCommerce Advanced or earlier, the icon is found in the site's source code at Modules\suitecommerce\GlobalImages\images.
For sites using the Aconcagua release of SuiteCommerce Advanced or later, the icon is found in the site's theme's source at assets\img.

Note:

You should avoid directly replacing the loading icon image file in the File Cabinet because it will be overwritten the next time your site’s source or theme’s source is deployed to your account.

After deploying the new image, you should perform a cache invalidation request on the file location and clear your browser's cache. The loading icon will be served from one of the following file locations depending on which version of SuiteCommerce you use:

https://[domain]/scs/extensions/SC/Threads/3.1.0/img/ajax-loader.gif
https://[domain]/sca-dev-kilimanjaro/img/ajax-loader.gif

For more information about cache invalidation requests, see Cache Invalidation.

Replacing the Loading Icon with Custom Loading Behavior

Important:

As a developer you may want to refer to jQuary.ajaxSetup (2020.1 release of SuiteCommerce and SuiteCommerce Advanced or earlier) or jQuery.Loader (2020.2 release of SuiteCommerce and SuiteCommerce Advanced or later) when creating extensions or custom modules. However, to avoid negatively impacting your site's performance, you should not directly customize these modules.

By default all HTTP requests are tracked using jQuery.ajax(). This includes page loads, requests to the item search API, NetSuite services, and other customizations that use this method. Changing the loading icon's behavior involves unbinding the default event handlers and binding new ones. The code uses these event handlers to show and hide the icon.

When implementing custom loading behavior, keep the following principles in mind:

Inject an element with the loadingIndicator ID that is hidden by default.
Add event listeners to ajaxStart() and ajaxStop(), which determine when to show and hide the loading icon.

To replace the loading icon with custom loading behavior:

Run the following code in a module/extension entry point file to unbind the existing event handlers that are used to show and hide the existing loading icon. This requires an extension or custom module. Referencing the loadingIndicatorShow and loadingIndicatorHide functions in jQuery’s unbind() method removes them from the ajaxStart and ajaxStop events.
```
                  jQuery(document).unbind('ajaxStart', SC.loadingIndicatorShow);
jQuery(document).unbind('ajaxStop', SC.loadingIndicatorHide);
jQuery('#loadingIndicator').remove(); 

                
```
After the default event listeners are unbound, you can add your own event listeners for your custom loading behavior. Either create your own or use a third-party provider. Whichever you choose, you need to bind two callbacks to jQuery’s Ajax events. Use the following code as an example. The exact structure or calls will depend on how your loading indicator’s code works.
```
                  define('CustomLoadingIndicator', [
   'jQuery',
   'LoadingIndicatorLibraryFile'
], function CustomLoadingIndicator (
   jQuery,
   LoadingIndicatorLibraryFile
) {
   'use strict';

   // Dummy code to load third-party loading indicator file
   LoadingIndicatorLibraryFile.mountToApp();

//Code to create new event listeners
jQuery(document)
   .ajaxStart(LoadingIndicatorLibraryFile.loadingIndicatorShow())
   .ajaxStop(LoadingIndicatorLibraryFile.loadingIndicatorHide());
   
  }); 

                
```
Note:
LoadingIndicatorLibraryFile, refers to an arbitrary file that contains the custom loading indicator code, such as that provided from a third-party. If you are writing your own code, ignore this and place the code into the entry point file.
View your changes.

If you are running a local server, you can view your changes by reloading your website. See Test SCA Customizations on a Local Server for more information.

If you are viewing your site in NetSuite, you can deploy your changes using the developer tools. See Deploy SCA Customizations to NetSuite for more information.

Adding Cursor Tracking

If you decide to implement cursor tracking, you should optimize your code for performance by using Underscore's throttle() method. To avoid potential performance issues, include a function/callback, which fires one time every x number of milliseconds. If a function/callback is not included each movement of the mouse triggers your code.

In the following example, the event handler is triggered every 50 milliseconds.

            jQuery(document.body)on({ 
        mousemove: _.throttle(function (event) {
            //Your cursor tracking code
        }, 50);
});

To implement your own cursor tracking, you can bind a mousemove event handler to document.body using jQuery. For more information, see jQuery API documentation. For an example of how to do this, see the jQuary.ajaxSetup or jQuery.Loader modules in your site’s source code.

Replacing the Loading Icon Image

Replacing the Loading Icon with Custom Loading Behavior

To replace the loading icon with custom loading behavior:

Adding Cursor Tracking

Related Topics