Skip to content

Module: src/ui/Overlays

The Overlays component displays layered visual elements—such as logos or posters—on top of the player viewport. It supports various positioning, scaling and timing modes. Overlays can be added dynamically or defined as part of the media data. An Overlay could be any DOM construct, but for now, only images are supported.

Version
1.1.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
DomSmith
convertTime
Source
Overlays.js, line 17

Constructor

new Overlays(player, parent, optionsopt)

Creates an instance of the Overlays component.

Parameters:
Name Type Attributes Description
player Player

Reference to the VisionPlayer instance.
parent Controller

Reference to the parent instance.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.

Members

Holds the instance configuration for this component.

Properties
Name Type Attributes Default Description
adaptLayout boolean optional true

Aligns overlay positioning with controller and title visibility state.
sanitizeHTML boolean optional false

Sanitizes the HTML of the overlay to prevent XSS attacks.
Type
Object
Source
Overlays.js, line 25

Reference to the main player instance.

Type
Player
Source
Overlays.js, line 34

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
Overlays.js, line 40

A DomSmith instance containing the overlay containers.

Type
DomSmith
Source
Overlays.js, line 46

This array contains overlay data and elements.

Type
Array<Overlays~overlayItem>
Source
Overlays.js, line 52

Methods

private #onDataReady(mediaItem)

Called when the media data is ready. Extracts overlay definitions and sets them up.

Parameters:
Name Type Description
mediaItem Data~mediaItem

Object containing media type info.

Parameters:
Name Type Attributes Description
overlays Array<Data~mediaItem_overlay> optional

The array of overlays from the media data.
Listens
data/ready
Source
Overlays.js, line 106

addOverlay(overlay)

Creates and adds a single overlay item to the DOM.

Parameters:
Name Type Description
overlay Data~mediaItem_overlay

The overlay definition from the media data.
Source
Overlays.js, line 128

private #onLoad(event)

Called when an overlay image loads successfully.

Parameters:
Name Type Description
event Event

Original onload event.
Source
Overlays.js, line 231

private #update(data, topic)

Updates the visibility of overlays based on the current playback time and status.

Parameters:
Name Type Description
data Object

Event data (unused).
topic string

Event topic (checks for "ended" to handle "poster-end" posters).
Listens
media/timeupdate
media/seeked
media/ended
Source
Overlays.js, line 259

private #enable()

Enables the next / prev button functionality. This method listens to canplay events in order to restore a usable state again when the player recovered from a media error (for example by loading another file).

Listens
media/canplay
Source
Overlays.js, line 293

private #disable()

Disables the next / prev button functionality. This method listens to media error events which cause the button to be disabled.

Listens
media/error
data/nomedia
Source
Overlays.js, line 304

private #removeOverlays()

Helper function which removes all overlays.

Source
Overlays.js, line 313

destroy()

This method removes all events, subscriptions and DOM nodes created by this component.

Source
Overlays.js, line 326