Mechanisms for Displaying Device-Specific Carousel Images

Mechanisms for Displaying Device-Specific Carousel Images

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:

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 to call the new function mapCarouselImages()

   javascriptCopy

   1define('Example.DeviceSpecificCarousel.DeviceSpecificCarousel'
   2 , [
   3     'Utils'
   4   , 'underscore'
   5   ]
   6, function
   7  (
   8    Utils
   9  , _
   10  )
   11{
   12    'use strict';
   13 
   14    return {
   15      mountToApp: function mountToApp (container)
   16      {
   17        var Layout = container.getComponent('Layout')
   18      , Environment = container.getComponent('Environment')
   19      , replaceCarouselImages = Utils.isPhoneDevice() || Utils.isTabletDevice()
   20      , self = this;
   21 
   22//Determines which images you want to replace the existing images with.
   23 
   24        if (Layout && Environment && replaceCarouselImages)
   25        {
   26          var carouselImages = 
   27          Utils.isPhoneDevice() ? Environment.getConfig('home.carouselImagesMobile')
   28        : Utils.isTabletDevice() ? Environment.getConfig('home.carouselImagesTablet')
   29        : []
   30 
   31//Checks if the replacement carousel images have been provided. If they have been, the updated array is passed to the Home.View context object.
   32 
   33        if (carouselImages.length)
   34        {
   35          Layout.addToViewContextDefinition('Home.View', 'carouselImages', 'array', function ()
   36          {
   37            return self.mapCarouselImages(carouselImages);
   38          });
   39        }
   40       }
   41      }
   42 
   43//A utility function used to generate the correct URLs for each banner image.
   44 
   45    , mapCarouselImages: function mapCarouselImages (urlArray)
   46      {
   47        return _.map(urlArray, function (url)
   48        {
   49          return _.getAbsoluteUrlOfNonManagedResources(url)
   50        });
   51       }
   52      }
   53});

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.

   jsonCopy

   1{
   2     "properties":
   3    {
   4    "home.carouselImagesMobile":
   5    {
   6      "group": "layout"
   7    , "type": "array"
   8    , "title": "Carousel Images Mobile"
   9    , "description": "Carousel Image URLs for Mobile Devices"
   10    , "items":
   11      {
   12        "type": "string"
   13      , "title": "URL"
   14      }
   15   , "default": []
   16   }
   17   , "home.carouselImagesTablet":
   18     {
   19       "group": "layout"
   20     , "type": "array"
   21     , "title": "Carousel Images Tablet"
   22     , "description": "Carousel Image URLs for Tablet Devices"
   23     , "items":
   24       {
   25         "type": "string"
   26       , "title": "URL"
   27       }
   28    , "default": []
   29    }
   30   }
   31  }

   After the above c