API Docs for:
Show:

File: development/modules/mediaplayer/js/mediaplayer.js

import $ from 'jquery';
import plyr from 'plyr';
import {isFunction} from '../../../js/utils/type';
import DOMModule from '../../__base/dommodule';



/**
 * @module Modules
 */



// PRIVATE PROPERTIES
const __player = Symbol('__mediaPlayer');
// PRIVATE METHODS
const _execCmd = Symbol('_executePlayerCommand');


// CONSTANT DEFINITIONS
const ICON_URL = 'https://cdnjs.cloudflare.com/ajax/libs/plyr/2.0.18/plyr.svg';
const CONTROLS = [
    'play-large',
    'play',
    'progress',
    'current-time',
    'mute',
    'volume',
    // 'captions',
    'fullscreen'
];


/**
 * MediaPlayer module
 * @class Modules.MediaPlayer
 * @constructor
 * @extends Modules._DOMModule
 */
class MediaPlayer extends DOMModule {
    constructor(options) {
        super(options);
    }

    /**
     * Creates a new MediaPlayer instance without the "new" keyword but does not
     *     initialize it
     * @method of
     * @static
     * @for Modules.MediaPlayer
     * @param {node|string|configs} node Node, CSS selector or configuration object
     * @return {MediaPlayer} A new instance
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     */
    static of(node) {
        return new MediaPlayer(node);
    }

    /**
     * Finds and initializes all MediaPlayer on a page at once
     * @method findAll
     * @static
     * @for Modules.MediaPlayer
     * @param {string} selector CSS selector to match nodes against
     * @return {array} A list of instances
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     MediaPlayer.findAll('[data-widget=MediaPlayer]');
     */
    static findAll(selector) {
        return $(selector).toArray().map((node) => {
            const player = MediaPlayer.of(node);
            player.render().startUp();
            return player;
        });
    }

    /**
     * Dummy method to make the API compatible with all other modules. May be
     *     hijacked to do some stuff in the future but currently does nothing
     *     more than returning the instance
     * @method render
     * @for Modules.MediaPlayer
     * @return {this} The instance
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render();
     */
    render() {
        return this;
    }

    /**
     * Initializes the player
     * @method startUp
     * @for Modules.MediaPlayer
     * @return {undefined} Nothing
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     */
    startUp() {
        this[__player] = plyr.setup(this.$rootNode.get(0), {
            controls: CONTROLS,
            iconUrl: ICON_URL,
            volume: 7
        });
    }

    /**
     * Returns the type of media for this instance as string. The returned type
     * can be one of "video", "audio", "youtube", "vimeo" or "unknown"
     * @method getMediaType
     * @for Modules.MediaPlayer
     * @return {string} The type of media
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     *     myMediaPlayer.getMediaType();
     */
    getMediaType() {
        return this[_execCmd]('getType') || 'unknown';
    }

    /**
     * Starts the playback of the media
     * @method play
     * @for Modules.MediaPlayer
     * @return {this} The instance
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     *     myMediaPlayer.play();
     */
    play() {
        this[_execCmd]('play');
        return this;
    }

    /**
     * Pauses the playback of the media but does not reset it
     * @method pause
     * @for Modules.MediaPlayer
     * @return {this} The instance
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     *     myMediaPlayer.pause();
     */
    pause() {
        this[_execCmd]('pause');
        return this;
    }

    /**
     * Stops the playback of the media and resets it to zero
     * @method stop
     * @for Modules.MediaPlayer
     * @return {this} The instance
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     *     myMediaPlayer.stop();
     */
    stop() {
        this[_execCmd]('stop');
        return this;
    }

    /**
     * Destroys the player and removes it from the DOM tree
     * @method destroy
     * @for Modules.MediaPlayer
     * @return {undefined} Nothing
     * 
     * @example
     *     import MediaPlayer from './modules/mediaplayer/js/mediaplayer';
     *
     *     const myMediaPlayer = MediaPlayer.of('[data-widget=MediaPlayer]');
     *     myMediaPlayer.render().startUp();
     *     myMediaPlayer.destroy();
     */
    destroy() {
        this[_execCmd]('destroy');
        super.destroy();
    }

    // --- PRIVATE
    [_execCmd](cmd, ...args) {
        if (this[__player] && isFunction(this[__player][cmd])) {
            return this[__player][cmd](...args);
        }
        return null;
    }
}



export default MediaPlayer;