How to display Device-Specific Carousel Images

Carousel images show a series of images that usually link to various categories or pages on your website. Depending on the customer, you may want to show different images based on their device. The example customization in this section demonstrates how to customize the home page carousel to show different images based on whether the user uses a mobile, tablet, or desktop device. The example customization includes utility functions built into SuiteCommerce that you can use to test the viewport width and the conditional statements that show or hide content based on the device.

Note

The example code in this section is delivered through the extension framework, which is available to sites running SuiteCommerce or the Aconcagua release of SuiteCommerce Advanced or later. However, the underlying mechanisms are available for the Kilimanjaro release of SuiteCommerce Advanced or earlier.

To display device-specific carousel images:

1. Create the entry point file.

Use the Example.DeviceSpecificCarousel.DeviceSpecificCarousel.js file, shown below, as a guide. When the module loads, the following variables are declared:

Two extensibility API components

A flag that tests whether the user is using a mobile or tablet device

A reference to this is to call the new function mapCarouselImages()

define('Example.DeviceSpecificCarousel.DeviceSpecificCarousel'
 , [
     'Utils'
   , 'underscore'
   ]
, function
  (
    Utils
  , _
  )
{
    'use strict';

    return {
      mountToApp: function mountToApp (container)
      {
        var Layout = container.getComponent('Layout')
      , Environment = container.getComponent('Environment')
      , replaceCarouselImages = Utils.isPhoneDevice() || Utils.isTabletDevice()
      , self = this;

//Determines which images you want to replace the existing images with.

        if (Layout && Environment && replaceCarouselImages)
        {
          var carouselImages =
          Utils.isPhoneDevice() ? Environment.getConfig('home.carouselImagesMobile')
        : Utils.isTabletDevice() ? Environment.getConfig('home.carouselImagesTablet')
        : []

//Checks if the replacement carousel images have been provided. If they have been, the updated array is passed to the Home.View context object.

        if (carouselImages.length)
        {
          Layout.addToViewContextDefinition('Home.View', 'carouselImages', 'array', function ()
          {
            return self.mapCarouselImages(carouselImages);
          });
        }
       }
      }

//A utility function used to generate the correct URLs for each banner image.

    , mapCarouselImages: function mapCarouselImages (urlArray)
      {
        return _.map(urlArray, function (url)
        {
          return _.getAbsoluteUrlOfNonManagedResources(url)
        });
       }
      }
});

2. Declare properties in the configuration file.

Use the Example.DeviceSpecificCarousel.DeviceSpecificCarousel.json file, shown below, as a guide. In this example, new properties are declared to add to an existing tab or group. Its structure mimics that of the configuration file of the existing carousel images.

{
   "properties":
  {
  "home.carouselImagesMobile":
  {
    "group": "layout"
  , "type": "array"
  , "title": "Carousel Images Mobile"
  , "description": "Carousel Image URLs for Mobile Devices"
  , "items":
    {
      "type": "string"
    , "title": "URL"
    }
 , "default": []
 }
 , "home.carouselImagesTablet":
   {
     "group": "layout"
   , "type": "array"
   , "title": "Carousel Images Tablet"
   , "description": "Carousel Image URLs for Tablet Devices"
   , "items":
     {
       "type": "string"
     , "title": "URL"
     }
  , "default": []
  }
 }
}

After the above customization is deployed, the two subtabs shown in the following image can be found in the Layout tab on the Configuration record.

3. Deploy your customization.
4. Upload and add the images you want to use for tablet and mobile devices.

Go to Documents > Files > File Cabinet.

Select the img folder.

Click the Add File button and select your images.

5. Go to Commerce > Websites > Configuration.
6. Select the website and domain, and click Configure.
7. Select the Layout tab and add the images to their respective arrays. For example, Layout > Carousel Images Tablet, and Layout > Carousel Images Mobile.
8. Click Save.
9. Test your changes.

Resize your site’s viewport and refresh the page. The different images are displayed if the viewport width is within one of the device types.