Common API

All Delight VR HTML elements are prefixed with “dl8-” and share a common API that, like with standardized HTML elements, is exported as attributes on the element. The following attributes are common amongst all Delight VR elements:

display-mode="<string>"

Defines the display mode behavior when the play button on a given content embed element is pressed. Due to minimal screen estate and good responsive practises the display-mode=”inline” attribute always defaults to “fullscreen” on mobile devices. If you want to explicitly change that behavior you can set the display-mode to “force-inline”. The default display-mode is “inline”.

Possible values: inline fullscreen force-inline

width="<css-value>" [optional]

The width of the embed element. Enter any valid CSS value such as 100%, px, rem and so forth. When left blank the other two dimension attributes “height” and “aspect” take precedence. When none of the three dimension attributes are given, width is set to 100% to completely fill the parent.

height="<css-value>" [optional]

The height of the embed element. Enter any valid CSS value such as 100%, px, rem and so forth. When left blank the other two dimension attributes “width” and “aspect” take precedence.

aspect="<string>" [optional]

The aspect ratio of the embed element. The aspect is given as a string value in the format “w:h”. The default is “16:10”.

poster="<uri>" [optional]

Defines a fallback image that is displayed as a default before initializing or playing any content. It can be any valid URI that points to an image. You an use any image format you would normally use as an image in the web. The default is the plain secondary dark color, which is part of the theme (also see Customization).

title="<string>" [optional]

Defines the content title string that appears on the embed and in the Delight VR player HUD on the top of the content. The default is no title. For the title to be readable on all screen sizes you should keep it under 50 characters if possible.

author="<string>" [optional]

Defines the content’s author as a string that appears on the embed below the title of the content. The default is no author.

author-href="<string>" [optional]

Defines the url to the author’s website. The user can access this link by clicking on the author text. Note that the author-href isn’t visible without the user supplying an author. The default is no author-href.

start-lat="<number>" [optional]

Defines the camera’s starting angle latitude in degrees. The default is 0 degrees.

start-lon="<number>" [optional]

Defines the camera’s starting angle longitude in degrees. The default is 0 degrees.

focal-length="<number>" [optional]

The camera’s starting field of view. The smaller the focal length the wider the lens. The unit of focal length is mm. The default is 15 mm.

min-focal-length="<number>" [optional]

The camera’s minimum field of view. The smaller the focal length the wider the lens. The unit of focal length is mm. The default is 10 mm.

max-focal-length="<number>" [optional]

The camera’s maximum field of view. The smaller the focal length the wider the lens. The unit of focal length is mm. The default is 80 mm.

preferred-controls="<string>" [optional]

The preferred camera control mode. Defaults to “MAGIC_WINDOW_CONTROLS”.

Can be one of “MAGIC_WINDOW_CONTROLS” and “DRAG_CONTROLS”.

drag-controls-damping="<number>" [optional]

The higher the value the more the drag control camera floats before coming to a halt. The attribute accepts ranges between 0.025 and 0.2. The default is 0.1

disable-scroll-capture [optional]

This attribute disables capturing of scroll events on content element.

disable-touch-capture [optional]

This attribute disables capturing of touch events on content element.

disable-mouse-capture [optional]

This attribute disables capturing of mouse events on content element.

disable-vertical-touch-dragging [optional]

Adding this attribute to a content element vertical touch-dragging and only allows touch-dragging on the horizontal-axis.

disable-vertical-mouse-dragging [optional]

Adding this attribute to a content element vertical mouse-dragging and only allows mouse-dragging on the horizontal-axis (non-mobile devices).

autostart [optional]

A boolean attribute that automatically starts the element with the attribute in the player. Video content with the autostart attribute is muted by default.

disable-tap-to-unmute [optional]

Use this attribute on an element with the autostart attribute to prevent the default mute behaviour.

autostart-vr [optional]

Automatically start the content element in VR mode by providing this attribute.


Programmatic Actions

To control the player embed via Javascript Delight VR offers the following APIs on the element. This can be used for example for starting the player automatically after the site is loaded.

Start player:

var element = document.querySelector("dl8-video") 
element.start()

Exit player:

var element = document.querySelector("dl8-video") 
element.exit()

Update dimensions:

var element = document.querySelector("dl8-video") 
element.updateDimensions()

You can call this function on the element to trigger a size recalculation. This is especially useful when the visibility of the element changes. The player updates the dimensions according to the new DOM state.


Programmatic Events

Delight VR offers some custom events that you can listen to. These are useful when you need detailed insights into the player lifecycle and want to trigger certain logic after detecting them:

x-dl8-evt-ready‘ (all player resources have been initialized):

document.addEventListener('x-dl8-evt-ready', function () { 
  // when DOM is also loaded you are good to call Delight VR element APIs like .start()
}

x-dl8-evt-loading-started‘ (content loading started)  :

document.addEventListener('x-dl8-evt-loading-started', function () { 
  // resource loading has been started
  // for example after the user presses the play button on the embed 
}

x-dl8-evt-loading-progress‘ :

document.addEventListener('x-dl8-evt-loading-progress', function (t) { 
  // resource loading has progressed
  // the 't' param indicates the progress from 0.0 to 1.0  
}

x-dl8-evt-loading-finished‘ (content loading finished)  :

document.addEventListener('x-dl8-evt-loading-finished', function () { 
  // resource loading has finished
}