@meisterplayer/plugin-htmlui

HTML Ui

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

How do I get set up?

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.

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:

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.

<div data-mstr-id="custom-element-1" data-mstr-events="mouseover" class="custom-wrapper-class">
    <div class="seekbar-container">
        <span data-mstr-standard="seekbar"></span>
    </div>
    <div class="bottom-bar-container">
        <span data-mstr-standard="playbutton"></span>
    </div>
</div>

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.

Configuration

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:[<element[data-mstr-id]>]:<eventtype>".

For example, take the template below:

<div data-mstr-id="custom-element-1" data-mstr-events="mouseover" class="custom-wrapper-class">
    <div data-mstr-id="custom-element-2" data-mstr-events="mousedown, mousemove, mouseup" class="custom-inner-class">
        <div data-mstr-events="click" class="custom-button-class">

        </div>
    </div>
</div>

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:

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:[<element[data-mstr-id]>]:<eventtype>".
• eventType :: String
  The type of event, that was emitted from the DOM. Examples include "mouseover" or "click". This is always the same as the <eventtype> 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.