Displaying 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 what device they are using. The example customization in this section, demonstrates how to customize the home page carousel to show different images based on whether the user is using 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 to the Kilimanjaro release of SuiteCommerce Advanced or earlier.

Note:

The example in this section should be used as a guide only and should not be used as a direct template.

Mechanisms for Displaying Device-Specific Carousel Images

Before diving into the code, here are some key points to keep in mind.

Built-in utility functions that perform device detection are available in the Utils.js module.
- getDeviceType(widthToCheck): If an integer value is specified for this method, the value you passed is evaluated. Otherwise, a string of either desktop, tablet, or mobile is returned depending on the current viewport width.
- isPhoneDevice(), isTabletDevice(), isDesktopDevice(): Each of these methods runs the device type checker function, evaluates the string it returns, and then returns a value.
When generating paths for new images, create two additional configuration objects and add them to the Configuration record. For details, see SuiteScript 2.x Global Objects.
To replace the existing image path so the correct image is displayed, use the addToViewContextDefintion() method, available in the extensibility API. This method is primarily used to add new properties to a view's getContext() object, but it can also be used to replace existing ones.

Using these mechanisms, you can create something that:

Detects the user's device type.
Gets the partial image paths from the Configuration record and processes them, so that the full URL paths required to load the images can be generated.
Swaps out the property in the home view's context object, so that the correct image is displayed when the template is rendered.

To display device-specific carousel images:

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 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)
        });
       }
      }
});

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.

Configuration record with two new subtabs

Deploy your customization. For details, see Deploy SCA Customizations to NetSuite.
Upload and add the images you want to use for tablet and mobile devices.
1. Go to Documents > Files > File Cabinet.
2. Select the img folder.
3. Click the Add File button and select your images.
Go to Commerce > Websites > Configuration.
Select the website and domain, and click Configure.
Select the Layout tab and add the images to their respective arrays. For example, Layout > Carousel Images Tablet, and Layout > Carousel Images Mobile.
Click Save.
Test your changes.

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

Note:

If you prefer not to use your own code for the carousel slider, you can use the SC Slideshow (Bundle ID 250352) or the SC Photo Gallery (Bundle ID 249422). For more information, see Installing a Bundle.

Mechanisms for Displaying Device-Specific Carousel Images

To display device-specific carousel images:

Related Topics