3D Cube Component Documentation

Updated: 03/10/2016. Version: 1.6

Example of Standard 3D Box MPU & 3D Box Leaderboard::

3D Box MPU Template in Adform HTML STUDIO
3D Box Leader Template in Adform HTML STUDIO

Example of Expandable 3D Box MPU & 3D Box Leaderboard:

3D Box MPU Expandable Template in Adform HTML STUDIO
3D Box Leader Expandable Template in Adform HTML STUDIO

Description

3D Box component allows users to create a highly interactive banner with cube feature. Cube feature enables you to set up to 20 walls (panels). It rotates through 3D cube element contents. Not less than 2 walls are needed in order to create a banner with cube feature. 3D Box component allows to create Standard 3D units or Expandable 3D units.

Initialization

To start with 3D Box Component, follow these steps:

1) Load it 3D Cube component your index.html document.

<!-- Components -->
<script src="//s1.adform.net/Banners/Scripts/assets/components/Adf.Cube.min.js"></script>
<!-- Components -->

2) Add following styles for component to work properly:

/* Main elements styles - Do not remove them, you can edit them as you prefer */
.adf-Cube {
    position: absolute;

    animation-fill-mode: forwards;
    -webkit-animation-fill-mode: forwards;
    -moz-animation-fill-mode: forwards;
    -ms-animation-fill-mode: forwards;

    transform-style: preserve-3d;
    -webkit-transform-style: preserve-3d;
    -moz-transform-style: preserve-3d;
    -ms-transform-style: preserve-3d;

    -ms-touch-action: none;
    background: transparent;
    opacity: 0;
}

.adf-Cube--tranformed {
    -webkit-transform: translateZ(-1000px);
    -moz-transform: translateZ(-1000px);
    -o-transform: translateZ(-1000px);
    transform: translateZ(-1000px);
}

.adf-Cube > .cube-Panel {
    position: absolute;

    -webkit-backface-visibility: hidden;
    -moz-backface-visibility: hidden;

    background-size: cover;
}
See the example of initialization:
<body>
    <div id="adf-cube">
        <div style="width: 100%; height: 100%; background: yellow;"></div>
        <div style="width: 100%; height: 100%; background: green;"></div>
        <div style="width: 100%; height: 100%; background: red;"></div>
        <div style="width: 100%; height: 100%; background: orange;"></div>
    </div>

    <script>
        var adfCube = new Adf.Cube();
        adfCube.init({
            cubeId: 'adf-cube',
            direction: 'horizontal',
            cubeWidth: dhtml.collapsedWidth,
            cubeHeight: dhtml.collapsedHeight,
            autoRotateEnabled: true,
            autoRotate: 6,
            autoRotateDirection: 'rotateNext',
            autoRotateDelay: 3,
            bannerShowDelay: 1,
            transition: 0.8,
            defaultButtonsOnPanels: true,
            bannerEventStartingId: 1,
            buttonPlacement: 'horizontal'
        });
    </script>

Mandatory Settings

These are the properties that have to be set in order to complete the setup of cube component:

Parameter Type Default Description
cubeId string ‘adf-cube’ Id of the element which should become 3D cube
slides integer 4 Number of walls (slides) displayed on box (min 2, max 20)

Optional Settings

The following settings are not mandatory and have default values:

Parameter Type Default Description
direction string ‘horizontal’ Direction of cube rotation (‘horizontal’, ‘vertical’)
cubeWidth integer banner width Width in pixels. Overwrites default width size when component needs to be used as part of initially wider ad
cubeHeight integer banner height Height in pixels. Overwrites default width size when component needs to be used as part of initially wider ad
autoRotateEnabled boolean true Set box auto rotation (true, false)
autoRotate integer 30 Indicates how many times cube should turn
autoRotateDelay integer 3 Time in seconds delay before each rotation
autoRotateDirection string “rotateNext” Direction in which cube will rotate automatically (“rotateNext”, “rotatePrevious”)
bannerShowDelay integer 1 Time in seconds when banner should be shown
transition float 0.8 Duration in seconds for transition animation
bannerEventStartingId integer 1 Sends banner events: on swipe left bannerEventStartingId, on swipe right bannerEventStartingId + 1, on click left bannerEventStartingId + 2, on click right bannerEventStartingId + 3
defaultButtonsOnPanels boolearn true Indicates if each of cube panel should contain default buttons
buttonPlacement string “horizontal” Indicates if default buttons should be placed “horizontaly” or “verticaly”

Methods


adfCube.init(settings)

Initializes Cube banner with predefined settings.


adfCube.rotate(direction)

Rotates cube banner to direction provided (adfCube.ROTATE_NEXT or adfCube.ROTATE_PREVIOUS)

Example:

dhtml.byId("adf-rotate-button").onclick = function () {
    adfCube.rotate(adfCube.ROTATE_NEXT);
};

adfCube.on(eventName, listener)

Registers event listener for the provided event name.

Param Type
eventName string
listener function

Example:

adfCube.on(adfCube.ROTATE_END, function() {
    // Called whenever rotation ends, can be used to trigger events after cube rotates.
    var banner = dhtml.byId('adf-banner');
    Adform.lib.addClass(banner, 'my-new-class');
});

Available events:

Event Value Description
adfCube.ROTATE_START “cubeRotateStart” fires when 3D Cube begins to rotate
adfCube.ROTATE_END “cubeRotateEnd” fires when 3D Cube completes rotation
adfCube.TOUCH_START “cubeTouchStart” fires when 3D Cube is being interacted with touch event
adfCube.TOUCH_MOVE “cubeTouchMove” fires when 3D Cube is being interacted with touchmove event
adfCube.CLICK_PREV “cubeClickPrev” fires when 3D Cube is rotated backwards by clicking on 3D Cube button
adfCube.CLICK_NEXT “cubeClickNext” fires when 3D Cube is rotated forwards by clicking on 3D Cube button
adfCube.SWIPE_PREV “cubeSwipePrev” fires when 3D Cube is rotated backwards by swiping 3D Cube
adfCube.SWIPE_NEXT “cubeSwipeNext “ fires when 3D Cube is rotated forwards by swiping 3D Cube

adfCube.off(eventName, listener)

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

Param Type
eventName string
listener function

var components = [ 'SingleExpanding' ];

Switch from 3D Standard units to 3D Expandable units

SingleExpanding Component

You can also use this component with expanding banners. In order to do that, load it to Single Expanding Component located in Adform library in index.html <head> tag:

Setup

To switch from Standard**3D Box MPU** or 3D Box Leader to 3D Box MPU Expandable (Single file) or 3D Box Leader Expandable (Single file) requires Single Expanding Component. To proceed follow the steps below:
1. Open 3D Box MPU/ 3D Box Leaderboard 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>3D Box Leader</format>
<name>3D Box Leader</name>

or

<format>3D Box MPU</format>
<name>3D Box MPU</name>

with

<format>Single Expanding</format>
<name>3D Box MPU| 3D Box Leader</name>

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



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

with

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

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