HTML Ui #

A plugin for the Meister.js video player that allows you to create your own ui, optionally making use of preconfigured elements.

$3

When initializing the player add HtmlUi with it's own configuration to the configuration object.
If you do not configure the plugin or leave the ui-configuration property empty (or the queryselector does not resolve to a node) the plugin will revert to using the default userinterface.

``JavaScript
var player = new Meister("#querySelector", {
HtmlUi: {
ui: document.querySelector('#custom-ui-element'), // (optional) Root element of your custom Ui or string containing HTML
registeredCallback: function (registeredEvent) { // Callback to call when events are registered on a custom element.
console.log('Registered events to a custom element: ', registeredEvent);
},
standard: { // Options to pass to the preconfigured elements.
stepForward: 30,
}
}
});

player.on('ui:custom-element:mouseover', function (e) {
console.log('This is a mouseover event from a custom-element :', e);
});
`

##### Registering Elements #####

By passing a function to the registeredCallback config object you can further customize your elements. This is called with a HtmlUiElementRegisteredEvent for every element that has the "data-mstr-events" attribute. This allows you to bind Meister events back to the element:


`JavaScript
var player = new Meister("#querySelector", {
HtmlUi: {
ui: document.querySelector('#custom-ui-element'),
registeredCallback: function (registeredEvent) {
var meisterInstance = registeredEvent.meister

if (registeredEvent.id === 'custom-time-display') {
// Update the current time display when the time changes.
var timeDisplayElement = registeredEvent.element;
meisterInstance.on('playerTimeUpdate', function(timeUpdateEvent) {
timeDisplayElement.textContent = formatTime(timeUpdateEvent.currentTime) + " / " + formatTime(timeUpdateEvent.duration);
});
}
}
}
});
`

For a list of all properties of the HtmlUiElementRegisteredEvent see the Configuration section of this document.

#### Standard Components ####

You can also opt to use custom prebuilt elements by using the "data-mstr-standard" attribute with the desired element name as the value. This will replace the element on which the attribute is set with the prebuilt element.

`HTML


In the template above the two span elements will be replaced with prebuilt elements. These are the same elements that are used in the StandardUi plugin.
The following values for "data-mstr-standard" are supported:

- "captionsbutton": Insert a button that allows the user to toggle captions should they be available.
- "fullscreenbutton": Insert a button that allows the user to toggle fullscreen playback.
- "playbutton": Insert a button that allows the user to play and pause the media.
- "playlistbuttons": Insert a set of two buttons that allow the user to navigate through a playlist.
- "qualitybutton": Insert a button that allows the user to select different playback qualities should they be available.
- "seekbar": Insert a seek bar that allows the user to seek to different parts of the media. It also displays playback position and buffer info where available.
- "spinner": Insert a spinner that shows up when the player is buffering or processing other tasks.
- "stepbackbutton": Insert a button that allows the user to seek backwards a specific amount of time. Amount can be configured by using standard.stepBack value
- "stepforwardbutton": Insert a button that allows the user to seek forwards a specific amount of time. Amount can be configured by using standard.stepForward value
- "timedisplay": Insert a label that displays the current position of the media as well as the duration.
- "volumeslider": Insert a control module that allows the user to change the volume.

$3

Options are required unless marked as [optional].

ui :: HTMLElement|String*
Either a direct reference to a DOM node that can be parsed as custom ui, or a url to a html template to use as the custom ui.
IMPORTANT Read the section on remote template when using the url option.
[optional] remoteTemplateReady :: Function*
When using a remote template url this callback is called when the template has been downloaded, parsed, and was injected into the DOM.
[optional] registeredCallback :: Function*
This callback is called when all events were registered to an element with the "data-mstr-events" attribute. It is called with a HtmlUiElementRegisteredEvent as the single argument with the following properties:
- element :: HTMLElement
Reference to the HTMLElement on which the events were registered.
- events :: String[]
List of eventnames that were registered on the element.
- id :: String
The data-mstr-id of the element, should it have one.
- meister :: Meister
The meister instance this element registered the events on.
[optional] standard :: Object*
Settings for the preconfigured elements. These mirror the options available for the StandardUi plugin for now.
[optional] disablePauseWithLive :: Boolean*
Flag indicating whether the viewer can pause live content or not. Defaults to false.
* [optional] hiddenClassName :: String
(css)Class name used to hide controls. Defaults to .mstr-hide-controls.

#### Option: Custom Events ####

Optionally you can use the eventbus of Meisterplayer to register and handle UI-events from the HtmlUi. An advantage of using Meister's eventbus is the reference to the meister-instance which triggered the UI-event, you would have to maintain a registry of instances and some way to determine the instance that fired an UI-event if you'd chosen to implement your own event-handling.

You can register events to your elements by setting the data-mstr-events attribute on the element, with a comma seperated list of eventnames as the value. Should one of the specified events trigger on the DOM node this will be emitted through the Meister instance's event bus with the following format: "ui:[]:".

For example, take the template below:

`HTML


As you can see it contains three elements, and all three elements have the data-mstr-events attribute. This would result in the following event handles:

- "ui:custom-element-1:mouseover"
- "ui:custom-element-2:mousedown"
- "ui:custom-element-2:mousemove"
- "ui:custom-element-2:mouseup"
- "ui:click" (Since the innermost div does not have an data-mstr-id the event is not namespaced)

You can register callbacks for these handles on the Meister instance:

`JavaScript
player.on('ui:custom-element-1:mouseover', function(customEvent) {
console.log('Mouseover on custom-element-1', customEvent);
});
`

All custom ui events callbacks are called with a HtmlUiEvent as the single argument. In this event the following properties are available:
- element :: HTMLElement
Reference to the DOM node on which the event was registered.
- event :: Event
The original DOM event.
- eventName :: String
The complete event string the callback was registered under. Follows the following format "ui:[]:".
- eventType :: String
The type of event, that was emitted from the DOM. Examples include "mouseover" or "click". This is always the same as the part of the eventName.
- meister :: Meister
Reference to the meister instance the event was emitted on.


#### Option: Directives ####

Directives are meant for more complex (but functionally 'standard') events.
Currently the events that trigger hiding the UI have been refactored into an autoHideShow Directive. If you create your own template and want the controls to auto-hide (and show when the mouse enters the player) you should put data-mstr-directive="autoHideShow" on the node you want the events triggered upon.

In the end using directives will provide you with a very flexible way to handle stuff in the UI, mostly events, but you can implement your own methods. A directive will be able to access the meister-instance and the HtmlUI-configuration.

##### autoHideShow #####

The default template handles auto-hiding using the autoHideShow-directive. It triggers custom Meister events;

uiEvent:hideControls
uiEvent:showControls
uiEvent:hideCursor
uiEvent:showCursor

The HtmlUi plugin handles those events by adding config.hiddenClassName to the controls; which hides the UI with css. If no config.hiddenClassName is set it defaults to .mstr-hide-controls.
If you have your own template and use the autoHideShow-directive and do not want to use mstr-hide-controls you should set config.hiddenClassName` to something of your liking.