overlays

The overlays plugin enables overlaying DOM elements on top of the video.
It takes care of scaling and boxing overlays, so that your UI will fit perfectly on top of the video regardless of whether or not the player is in fullscreen, or if it’s running on a mobile device or a desktop.
It provides methods to add, remove, show and hide overlays.

Example

// Add a DIV element (assume myDecisionDiv is a predefined var referencing a DOM element)
player.overlays.add('decisionOverlay', myDecisionDiv, {visible: false});

// Show the element whenever a 'decision.start' event is triggered
player.on('decision.start', function() {
    player.overlays.show('decisionOverlay');
});

// Hide the element whenever a 'decision.end' event is triggered
player.on('decision.end', function() {
    player.overlays.hide('decisionOverlay');
});

Init Options

options : object

Initialization options for the overlays plugin.

options.masterContainerStyle : object
property

Object containing CSS style attributes that will be used to style the master container.
The master container is a div that will contain all the overlays added via the overlays plugin.
The given object will be merged with the default object.

Default: {
display: 'block',
position: 'absolute',
width: '100%',
height: '100%',
top: '0',
left: '0',
overflow: 'hidden',
'backface-visibility': 'hidden',
'-webkit-backface-visibility': 'hidden',
'-webkit-user-select': 'none',
'-moz-user-select': 'none',
'-ms-user-select': 'none',
'pointer-events': 'none'
}

Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "masterContainerStyle": {
                "background-color": "blue"
            }
        }
    }
}

options.fastclickOptions : object
property

By default, Fastclick will be attached to master container.
fastclickOptions will be passed as the 2nd argument to the FastClick.attach() method.

Default: null

options.defaultOptions : object
property

The default options applied to each added overlay.

options.defaultOptions.wrapperStyle : object
property

Each overlay will have a wrapper div which is managed by the plugin.
The wrapperStyle object contains CSS style attributes to be applied to each wrapper.
The given object will be merged with the default object.

Default: {
display: 'block',
position: 'absolute',
width: '100%',
height: '100%',
top: '0',
left: '0',
overflow: 'hidden'
}

Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "wrapperStyle": {
                    "font-size": "20px"
                }
            }
        }
    }
}
options.defaultOptions.boxing : boolean
property

The default boxing value applied to each overlay. See add for details.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "boxing": false
            }
        }
    }
}
options.defaultOptions.scaling : boolean
property

The default scaling value applied to each overlay. See add for details.

Default: false
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "scaling": true
            }
        }
    }
}
options.defaultOptions.fastclick : boolean
property

Set to false to disable Fastclick‘s functionality for overlays (by adding the needsclick class to the wrapper div).

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "fastclick": false
            }
        }
    }
}
options.defaultOptions.pointerEvents : boolean
property

The default pointerEvents value applied to each overlay. See add for details.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "pointerEvents": false
            }
        }
    }
}
options.defaultOptions.width : number
property

The default width value applied to each overlay. See add for details.

Default: 854
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "width": 1280,
                "height": 720
            }
        }
    }
}
options.defaultOptions.height : number
property

The default height value applied to each overlay. See add for details.

Default: 480
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "width": 1280,
                "height": 720
            }
        }
    }
}
options.defaultOptions.visible : boolean
property

The default visible value applied to each overlay. See add for details.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "visible": false
            }
        }
    }
}
options.defaultOptions.hideTimeout : number
property

The default options.timeout value applied to each overlay when invoking hide.

Default: 5000
See: hide
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "hideTimeout": 15000 // 15 seconds
            }
        }
    }
}
options.defaultOptions.includeInCheckpoints : boolean
property

The default options.includeInCheckpoints value applied to each overlay. See add for details.

Default: true
Example

// playerOptions.json
{
    "plugins": {
        "overlays": {
            "defaultOptions": {
                "includeInCheckpoints": false
            }
        }
    }
}

Properties

player.overlays.version : string
propertyreadonly

The overlays plugin’s version string.

Example

console.log('The overlays plugin version is', player.overlays.version);

Methods

player.overlays.add(id, el, [options]) ⇒ Element
method

Add an overlay to the DOM (on top of the player), and register its id with the overlays plugin.

Returns: Element - The element that was successfully added, or null if error occurred.

Param Type Description
id string Required. A unique id for the new overlay.
el Element Required. A DOM element to be added as an overlay on top of the player.
[options] object Optional. An options object.
[options.boxing] boolean | string Default true. If true, overlay will be letterboxed, pillarboxed or pan&scanned to fit on top the video. See scaling. Also accepts string values min or max.
[options.scaling] boolean | string Default false. If true, overlay will be scaled (via CSS transform) to fill the player/letterbox/pillarbox, using the width and height options as the original dimension. Also accepts string values width, height, min or max (which may change the overlay ratio, overriding either the width or height property).
[options.pointerEvents] boolean Default true. If true, overlays will have CSS value pointer-events: auto and clicks will not pass through overlay to underlying overlays. If false, clicks will pass through overlay.
[options.width] number Default 854. The original width of the overlay (value will be used when scaling is true, and width/height ratio will be used when boxing is true).
[options.height] number Default 480. The original height of the overlay (value will be used when scaling is true, and width/height ratio will be used when boxing is true).
[options.visible] boolean Default true. The initial visibility state of the element. Can later be toggled by calling show and hide.
[options.wrapperStyle] object An object that will be merged with (override) the wrapperStyle object. Note that enabling boxing/scaling might dynamically override some of the wrapperStyle’s CSS properties.
[options.includeInCheckpoints] boolean Default true. If set to false, the state of the overlay will not be saved or restored on checkpoints events.

Example

var domElement = document.createElement('div');
domElement.setAttribute('style', 'position: absolute; width: 50%; height: 50%; background-color: green; opacity: 0.5; z-index: 100');
player.overlays.add('myOverlay', domElement, {scaling: true});

player.overlays.remove(id) ⇒ Element
method

Remove an overlay from the DOM, and unregister its id with the overlays plugin.
Use reserved id all in order to remove all added overlays.

Returns: Element - The element that was successfully removed, or null if error occurred.

Param Type Description
id string A unique id that’s been previously registered with the overlays plugin (see add).

Example

player.overlays.remove('myOverlay');

player.overlays.get(id) ⇒ Element
method

Returns a reference to a DOM element that was previously added to the overlays.
Use reserved id all in order to get an array of all added overlays.

Returns: Element - The element, or null if not found.

Param Type Description
id string A unique id that’s been previously registered with the overlays plugin (see add).

Example

var myOverlay = player.overlays.get('myOverlay');
myOverlay.style.visibility = 'hidden';

player.overlays.has(id) ⇒ boolean
method

Checks whether an overlay with given id has been added.

Returns: boolean - True if the id has been registered with the overlays plugin, false otherwise.

Param Type Description
id string An overlay id.

Example

if (!player.overlays.has('maybeOverlay')) {
    player.overlays.add('maybeOverlay', maybeOverlayDiv);
}

player.overlays.show(id, [fn])
method

Show an overlay.
Use reserved id all in order to show all added overlays.

Param Type Description
id string A unique id that’s been previously registered with the overlays plugin (see add).
[fn] module:overlays~show Optional. A user defined function that will be executed immediately after showing the element. The main use-case is animation.

Example

player.overlays.show('myOverlay'); // Overlay will be displayed

player.overlays.hide(id, [fn], [options])
method

Hide an overlay.
Use reserved id all in order to hide all added overlays.

Param Type Description
id string A unique id that’s been previously registered with the overlays plugin (see add).
[fn] module:overlays~hide Optional. A user defined function that will be executed prior to hiding the overlay. The main use-case is animation.
[options] object An optional options object.
[options.timeout] number Default 5000 (5 seconds). The timeout (in milliseconds) following a call to hide afterwhich overlay will be forcibly hidden.

Example

player.overlays.hide('myOverlay'); // Overlay will be hidden
Rate this page: X
Tell us more!