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.
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.
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.
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”: []
}
}
}