Responsive Carousel Component Documentation

Updated: 26/09/2018. Version: 1.5.0

enter image description here ATTENTION: This version of component is outdated and will not be supported soon. We strongly recommend to use Flex Gallery component, which is more flexible alternative.

Description

Component allows you to create different types of panels which can rotate in specific direction or in specific angle. Follow the guidelines below in order to change available parameters.Also explains how or convert component from DHTML to MRAID and vice versa.

Initialization

To start with Responsive Carousel Component, you have to load it in your index.html document.

<head>
...
<!--Components-->
<script src="//s1.adform.net/banners/scripts/components/Adform.ResponsiveCarousel.js"></script>
<!--Components-->
...
</head>

See an example of initialization:

// 1. Create new instance
var carousel = new Adform.ResponsiveCarousel({
    panelWidth: 228,
    panelHeight: 190,
    panelSpacing: 20,
    perspective: 800,
    rotationDuration: 0.5,
    rotationDirection: 'horizontal',
    panels: [
        {
            content: Adform.getAsset(1),
            clickUrl: Adform.getClickURL('clickTAG1')
        },
        {
            content: Adform.getAsset(2),
            clickUrl: Adform.getClickURL('clickTAG2')
        },
        {
            content: Adform.getAsset(3),
            clickUrl: Adform.getClickURL('clickTAG3')
        },
        {
            content: Adform.getAsset(4),
            clickUrl: Adform.getClickURL('clickTAG4')
        }
    ]
});

// 2. Initialize Carousel
carousel.init();

Mandatory Settings

These are the properties that have to be present in options’ Object.

Name Type Description
panelWidth number Width in pixels (integer, greater than 0)
panelHeight number Height in pixels (integer, greater than 0)
panelSpacing number Space between adjacent panels (integer)
panels Array Array of Panel Objects

Optional Settings

Name Type Default Description
perspective number 800 CSS perspective (integer, greater than 0)
rotationDuration number 0.5 Carousel rotation duration in seconds (float, greater than 0)
rotationDirection string "auto" Carousel rotation direction ("horizontal", "vertical", "auto")
maxSidePadding number 0 Maximum value of side spacing between container element and Carousel outer element (integer, min. 0)
className string "adf-Carousel" Outer element class name. Note that inner elements will use this className as a prefix as well
container string "#adf-banner" Identifier (id or class) of element to append Carousel as a child to
prevButton string "#adf-navButton-left" Identifier (id or class) of element used (if used) as a previous element navigation button
nextButton string "#adf-navButton-right" Identifier (id or class) of element used (if used) as a next element navigation button

Panel Objects

Responsive Carousel panels can currently be of 4 distinct types. Each of them requires a different object structure, so we will illustrate them separately.

Image Panels

Name Type Value Description
type string "image" This field can be excluded since it’s default type
content string URL Image asset url
clickUrl string URL Click URL, can be excluded if panel doesn’t have to be clickable

Video Panels

If you are using DHTML version, make sure youload VideoPlayer Component to <head></head> tag inside your html document.

<head>
...
<!--Components-->
<script src="//s1.adform.net/banners/scripts/components/Adform.ResponsiveCarousel.js"></script>
<script src="//s1.adform.net/banners/scripts/components/Adform.VideoPlayer.js"></script>
<!--Components-->
...
</head>
Name Type Value Description
type string "video" This field is mandatory
content string array URL Single or multiple video source URLs
poster string URL Poster image asset URL
autoPlay boolean 0 Set to 1 if video has to autoplay once in Carousel center (Banner video settings will override this value)
clickUrl string URL Click URL, can be omitted if panel doesn’t have to be clickable

Custom Panels

Name Type Value Description
type string "custom" This field is mandatory
content string | object HTML This content will be appended to panel element
callback function Javascript You can add a Javascript function which will be executed when panel is loaded

Slider Panels

In order to add slider panels you’ll have to load Slider Component in your index.html document.

<head>
...
<!--Components-->
<script src="//s1.adform.net/banners/scripts/components/Adform.ResponsiveCarousel.js"></script>
<script src="//s1.adform.net/banners/scripts/components/Adform.VideoPlayer.js"></script>
<script src="//s1.adform.net/banners/scripts/components/Adform.Slider.js"></script>
<!--Components-->
...
</head>
Name Type Value Description
type string "slider" This field is mandatory
settings object slider settings Read this document for a deeper insight
clickUrl string URL Default click URL, can be omitted if slides don’t have to be clickable
events object custom events Define previousSlide and nextSlide events id and name for Reports. Default ids are 2 and 3

NOTE: Carousel format can has max 20 assets, including:
- video files
- carousel images
- slider images

Methods

Resizes Responsive Carousel outer element to specified width and height (in pixels).

Returns outer element.

Example:

document.querySelector('#banner').appendChild(carousel.getElement());

Rotates Carousel back or forth of the amount of panels specified.

Example:

document.querySelector('#previousButton').addEventListener('click', function () {
    carousel.moveBy(-1);
});

Registers event listener for the provided event name.

Param Type
eventName string
listener function 
carousel.on('rotationEnd', function() {
    // Called whenever rotation completes, can be used to send engaging rotation events
    Adform.sendEvent(['1', 'Rotate']);
});

Removes the event listener. If listener is null or undefined, removes all listeners associated with the provided event name.

Param Type
eventName string
listener function

Example

var testHtml = document.createElement('div');
testHtml.id = "test";
testHtml.className = "u-fullWidthHeight";

var callback = function() {
    document.getElementById('test').addEventListener("click", function () {
        alert('I have been clicked');
    });
};

var carousel = new Adform.ResponsiveCarousel({
    panelWidth: 228,
    panelHeight: 190,
    panelSpacing: 20,
    maxSidePadding: 60,
    perspective: 800,
    rotationDuration: 0.5,
    rotationDirection: 'horizontal',
    container: '#myBanner',
    className: 'myCarousel',
    prevButton: '.leftArrow',
    nextButton: '.rightArrow',
    panels: [
        {
            content: Adform.getAsset(1),
            clickUrl: Adform.getClickURL('clickTAG1')
        },
        {
            type: "video",
            content: [Adform.getAsset(2), Adform.getAsset(3)],
            poster: Adform.getAsset(4),
            autoPlay: 1,
            clickUrl: Adform.getClickURL('clickTAG2')
        },
        {
            type: "slider",
            settings: {
                isVertical: true,
                animation: {
                    scaleAtTheStart: 1, 
                    transitionDuration: 0.4,
                    scaleAtTheEnd: 1,
                    panelDistance: 1,
                },
                panels: [
                    Adform.getAsset(5),
                    Adform.getAsset(6),
                    Adform.getAsset(7),
                    Adform.getAsset(8)
                ]
            },
            clickUrl: Adform.getClickURL('clickTAG3'),
            events: {
                previousSlide: {id: "2", name: "Previous Slide"},
                nextSlide: {id: "3", name: "Next Slide"},
            }
        },
        {
            type: "custom",
            content: testHtml,
            callback: callback
        },
        {
            content: Adform.getAsset(9),
            clickUrl: Adform.getClickURL('clickTAG5')
        },
        {
            content: Adform.getAsset(10)
        }
    ]
});

carousel.on('rotationEnd', function() {
    Adform.sendEvent(['1', 'Rotate']);
});

carousel.init();

Switch from regular DHTML technology to mobile MRAID

This component is compatible with both MRAID and DHTML technologies, and thus it can be used in Mobile Standard or Display Standard types of ads.

To switch from DHTML to MRAID, follow the steps below:
1. Open Responsive Carousel template in HTML5 Studio.
2. Export banner from HTML5 Studio to your computer.
3. Extract the downloaded .zip and open ADFBannerProperties.xml with any editor.
4. Replace the following parameters

<format>Standard</format>
<name>Responsive Carousel Ad</name>

with

<format>Standard (Mobile App)</format>
<name>Responsive Carousel Ad</name>

After the replacement, save the file.
5. Then, go to Responsive_Carousel_main_asset and open index.html. In <head> tag replace 


<script type="text/javascript">
    var components = [
        'VideoPlayer'
    ];
    document.write('<script src="'+ (window.API_URL || 'https://s1.adform.net/banners/scripts/rmb/Adform.DHTML.js?bv='+ Math.random()) +'"><\/script>');
</script>

with
<script src="mraid.js"></script>

After replacement, save the file.
6. Select all banner files and zip it.
7. Upload this .zip to HTML5 Studio.