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');
});
- Table of Contents
- Init Options
- Properties
- versionpro
- Methods
Init Options
options : object
Initialization options for the overlays plugin.
- options :
object
- .masterContainerStyle :
object
- .fastclickOptions :
object
- .defaultOptions :
object
- .wrapperStyle :
object
- .boxing :
boolean
- .scaling :
boolean
- .fastclick :
boolean
- .pointerEvents :
boolean
- .width :
number
- .height :
number
- .visible :
boolean
- .hideTimeout :
number
- .includeInCheckpoints :
boolean
- .wrapperStyle :
- .masterContainerStyle :
options.masterContainerStyle : object
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
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
The default options applied to each added overlay.
- .defaultOptions :
object
- .wrapperStyle :
object
- .boxing :
boolean
- .scaling :
boolean
- .fastclick :
boolean
- .pointerEvents :
boolean
- .width :
number
- .height :
number
- .visible :
boolean
- .hideTimeout :
number
- .includeInCheckpoints :
boolean
- .wrapperStyle :
options.defaultOptions.wrapperStyle : object
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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])
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])
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