web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2025-04-09 07:23:57 +02:00
Code Releases Activity

docs: Update JSDoc comments, so core API docs for the videojs function are accurate. (#5385)

Browse Source
This commit is contained in:
Pat O'Neill 2018-09-28 16:21:18 -04:00 committed by Gary Katsevman
parent c2eb138e66
commit ebf8d6671c
17 changed files with 750 additions and 697 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/js/extend.js
View File

@ -37,22 +37,27 @@ const _inherits = function(subClass, superClass) {
};
/**
* Function for subclassing using the same inheritance that
* videojs uses internally
* Used to subclass an existing class by emulating ES subclassing using the
* `extends` keyword.
*
* @static
* @const
* @function
* @example
* var MyComponent = videojs.extend(videojs.getComponent('Component'), {
* myCustomMethod: function() {
* // Do things in my method.
* }
* });
*
* @param {Object} superClass
* The class to inherit from
* @param {Function} superClass
* The class to inherit from
*
* @param {Object} [subClassMethods={}]
* The class to inherit to
* @param {Object} [subClassMethods={}]
* Methods of the new class
*
* @return {Object}
* The new object with subClassMethods that inherited superClass.
* @return {Function}
* The new class with subClassMethods that inherited superClass.
*/
const extendFn = function(superClass, subClassMethods = {}) {
const extend = function(superClass, subClassMethods = {}) {
let subClass = function() {
superClass.apply(this, arguments);
};
@ -80,4 +85,4 @@ const extendFn = function(superClass, subClassMethods = {}) {
return subClass;
};
export default extendFn;
export default extend;

5
src/js/player.js
View File

@ -3779,7 +3779,10 @@ TRACK_TYPES.names.forEach(function(name) {
});
/**
* Global player list
* Global enumeration of players.
*
* The keys are the player IDs and the values are either the {@link Player}
* instance or `null` for disposed players.
*
* @type {Object}
*/

8
src/js/plugin.js
View File

@ -373,8 +373,12 @@ class Plugin {
/**
* De-register a Video.js plugin.
*
* @param {string} name
* The name of the plugin to be deregistered.
* @param {string} name
* The name of the plugin to be de-registered. Must be a string that
* matches an existing plugin.
*
* @throws {Error}
* If an attempt is made to de-register the base plugin.
*/
static deregisterPlugin(name) {
if (name === BASE_PLUGIN_NAME) {

140
src/js/tech/middleware.js
View File

@ -1,3 +1,7 @@
/**
* @file middleware.js
* @module middleware
*/
import { assign } from '../utils/obj.js';
import toTitleCase from '../utils/to-title-case.js';
@ -6,11 +10,53 @@ const middlewareInstances = {};
export const TERMINATOR = {};
/**
* A middleware object is a plain JavaScript object that has methods that
* match the {@link Tech} methods found in the lists of allowed
* {@link module:middleware.allowedGetters|getters},
* {@link module:middleware.allowedSetters|setters}, and
* {@link module:middleware.allowedMediators|mediators}.
*
* @typedef {Object} MiddlewareObject
*/
/**
* A middleware factory function that should return a
* {@link module:middleware~MiddlewareObject|MiddlewareObject}.
*
* This factory will be called for each player when needed, with the player
* passed in as an argument.
*
* @callback MiddlewareFactory
* @param {Player} player
* A Video.js player.
*/
/**
* Define a middleware that the player should use by way of a factory function
* that returns a middleware object.
*
* @param {string} type
* The MIME type to match or `"*"` for all MIME types.
*
* @param {MiddlewareFactory} middleware
* A middleware factory function that will be executed for
* matching types.
*/
export function use(type, middleware) {
middlewares[type] = middlewares[type] || [];
middlewares[type].push(middleware);
}
/**
* Gets middlewares by type (or all middlewares).
*
* @param {string} type
* The MIME type to match or `"*"` for all MIME types.
*
* @return {Function[]|undefined}
* An array of middlewares or `undefined` if none exist.
*/
export function getMiddleware(type) {
if (type) {
return middlewares[type];
@ -19,10 +65,33 @@ export function getMiddleware(type) {
return middlewares;
}
/**
* Asynchronously sets a source using middleware by recursing through any
* matching middlewares and calling `setSource` on each, passing along the
* previous returned value each time.
*
* @param {Player} player
* A {@link Player} instance.
*
* @param {Tech~SourceObject} src
* A source object.
*
* @param {Function}
* The next middleware to run.
*/
export function setSource(player, src, next) {
player.setTimeout(() => setSourceHelper(src, middlewares[src.type], next, player), 1);
}
/**
* When the tech is set, passes the tech to each middleware's `setTech` method.
*
* @param {Object[]} middleware
* An array of middleware instances.
*
* @param {Tech} tech
* A Video.js tech.
*/
export function setTech(middleware, tech) {
middleware.forEach((mw) => mw.setTech && mw.setTech(tech));
}
@ -30,6 +99,18 @@ export function setTech(middleware, tech) {
/**
* Calls a getter on the tech first, through each middleware
* from right to left to the player.
*
* @param {Object[]} middleware
* An array of middleware instances.
*
* @param {Tech} tech
* The current tech.
*
* @param {string} method
* A method name.
*
* @return {Mixed}
* The final value from the tech after middleware has intercepted it.
*/
export function get(middleware, tech, method) {
return middleware.reduceRight(middlewareIterator(method), tech[method]());
@ -38,16 +119,48 @@ export function get(middleware, tech, method) {
/**
* Takes the argument given to the player and calls the setter method on each
* middleware from left to right to the tech.
*
* @param {Object[]} middleware
* An array of middleware instances.
*
* @param {Tech} tech
* The current tech.
*
* @param {string} method
* A method name.
*
* @param {Mixed} arg
* The value to set on the tech.
*
* @return {Mixed}
* The return value of the `method` of the `tech`.
*/
export function set(middleware, tech, method, arg) {
return tech[method](middleware.reduce(middlewareIterator(method), arg));
}
/**
* Takes the argument given to the player and calls the `call` version of the method
* on each middleware from left to right.
* Takes the argument given to the player and calls the `call` version of the
* method on each middleware from left to right.
*
* Then, call the passed in method on the tech and return the result unchanged
* back to the player, through middleware, this time from right to left.
*
* @param {Object[]} middleware
* An array of middleware instances.
*
* @param {Tech} tech
* The current tech.
*
* @param {string} method
* A method name.
*
* @param {Mixed} arg
* The value to set on the tech.
*
* @return {Mixed}
* The return value of the `method` of the `tech`, regardless of the
* return values of middlewares.
*/
export function mediate(middleware, tech, method, arg = null) {
const callMethod = 'call' + toTitleCase(method);
@ -60,6 +173,11 @@ export function mediate(middleware, tech, method, arg = null) {
return returnValue;
}
/**
* Enumeration of allowed getters where the keys are method names.
*
* @type {Object}
*/
export const allowedGetters = {
buffered: 1,
currentTime: 1,
@ -69,10 +187,20 @@ export const allowedGetters = {
paused: 1
};
/**
* Enumeration of allowed setters where the keys are method names.
*
* @type {Object}
*/
export const allowedSetters = {
setCurrentTime: 1
};
/**
* Enumeration of allowed mediators where the keys are method names.
*
* @type {Object}
*/
export const allowedMediators = {
play: 1,
pause: 1
@ -103,6 +231,12 @@ function executeRight(mws, method, value, terminated) {
}
}
/**
* Clear the middleware cache for a player.
*
* @param {Player} player
* A {@link Player} instance.
*/
export function clearCacheForPlayer(player) {
middlewareInstances[player.id()] = null;
}
@ -111,6 +245,8 @@ export function clearCacheForPlayer(player) {
* {
* [playerId]: [[mwFactory, mwInstance], ...]
* }
*
* @private
*/
function getOrCreateFactory(player, mwFactory) {
const mws = middlewareInstances[player.id()];

124
src/js/utils/browser.js
View File

@ -9,22 +9,52 @@ const USER_AGENT = window.navigator && window.navigator.userAgent || '';
const webkitVersionMap = (/AppleWebKit\/([\d.]+)/i).exec(USER_AGENT);
const appleWebkitVersion = webkitVersionMap ? parseFloat(webkitVersionMap.pop()) : null;
/*
* Device is an iPhone
/**
* Whether or not this device is an iPad.
*
* @static
* @const
* @type {Boolean}
* @constant
* @private
*/
export const IS_IPAD = (/iPad/i).test(USER_AGENT);
/**
* Whether or not this device is an iPhone.
*
* @static
* @const
* @type {Boolean}
*/
// The Facebook app's UIWebView identifies as both an iPhone and iPad, so
// to identify iPhones, we need to exclude iPads.
// http://artsy.github.io/blog/2012/10/18/the-perils-of-ios-user-agent-sniffing/
export const IS_IPHONE = (/iPhone/i).test(USER_AGENT) && !IS_IPAD;
/**
* Whether or not this device is an iPod.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_IPOD = (/iPod/i).test(USER_AGENT);
/**
* Whether or not this is an iOS device.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_IOS = IS_IPHONE || IS_IPAD || IS_IPOD;
/**
* The detected iOS version - or `null`.
*
* @static
* @const
* @type {string|null}
*/
export const IOS_VERSION = (function() {
const match = USER_AGENT.match(/OS (\d+)_/i);
@ -34,7 +64,22 @@ export const IOS_VERSION = (function() {
return null;
}());
/**
* Whether or not this is an Android device.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_ANDROID = (/Android/i).test(USER_AGENT);
/**
* The detected Android version - or `null`.
*
* @static
* @const
* @type {number|string|null}
*/
export const ANDROID_VERSION = (function() {
// This matches Android Major.Minor.Patch versions
// ANDROID_VERSION is Major.Minor as a Number, if Minor isn't available, then only Major is returned
@ -55,11 +100,52 @@ export const ANDROID_VERSION = (function() {
return null;
}());
/**
* Whether or not this is a native Android browser.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_NATIVE_ANDROID = IS_ANDROID && ANDROID_VERSION < 5 && appleWebkitVersion < 537;
/**
* Whether or not this is Mozilla Firefox.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_FIREFOX = (/Firefox/i).test(USER_AGENT);
/**
* Whether or not this is Microsoft Edge.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_EDGE = (/Edge/i).test(USER_AGENT);
/**
* Whether or not this is Google Chrome.
*
* This will also be `true` for Chrome on iOS, which will have different support
* as it is actually Safari under the hood.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_CHROME = !IS_EDGE && ((/Chrome/i).test(USER_AGENT) || (/CriOS/i).test(USER_AGENT));
/**
* The detected Google Chrome version - or `null`.
*
* @static
* @const
* @type {number|null}
*/
export const CHROME_VERSION = (function() {
const match = USER_AGENT.match(/(Chrome|CriOS)\/(\d+)/);
@ -68,6 +154,14 @@ export const CHROME_VERSION = (function() {
}
return null;
}());
/**
* The detected Internet Explorer version - or `null`.
*
* @static
* @const
* @type {number|null}
*/
export const IE_VERSION = (function() {
const result = (/MSIE\s(\d+)\.\d/).exec(USER_AGENT);
let version = result && parseFloat(result[1]);
@ -80,9 +174,31 @@ export const IE_VERSION = (function() {
return version;
}());
/**
* Whether or not this is desktop Safari.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_SAFARI = (/Safari/i).test(USER_AGENT) && !IS_CHROME && !IS_ANDROID && !IS_EDGE;
/**
* Whether or not this is any flavor of Safari - including iOS.
*
* @static
* @const
* @type {Boolean}
*/
export const IS_ANY_SAFARI = (IS_SAFARI || IS_IOS) && !IS_CHROME;
/**
* Whether or not this device is touch-enabled.
*
* @static
* @const
* @type {Boolean}
*/
export const TOUCH_ENABLED = Dom.isReal() && (
'ontouchstart' in window ||
window.navigator.maxTouchPoints ||

22
src/js/utils/computed-style.js
View File

@ -8,21 +8,19 @@ import window from 'global/window';
* A safe getComputedStyle.
*
* This is needed because in Firefox, if the player is loaded in an iframe with
* `display:none`, then `getComputedStyle` returns `null`, so, we do a null-check to
* make sure that the player doesn't break in these cases.
* `display:none`, then `getComputedStyle` returns `null`, so, we do a
* null-check to make sure that the player doesn't break in these cases.
*
* @param {Element} el
* The element you want the computed style of
* @function
* @param {Element} el
* The element you want the computed style of
*
* @param {string} prop
* The property name you want
* @param {string} prop
* The property name you want
*
* @see https://bugzilla.mozilla.org/show_bug.cgi?id=548397
*
* @static
* @const
* @see https://bugzilla.mozilla.org/show_bug.cgi?id=548397
*/
export default function computedStyle(el, prop) {
function computedStyle(el, prop) {
if (!el || !prop) {
return '';
}
@ -35,3 +33,5 @@ export default function computedStyle(el, prop) {
return '';
}
export default computedStyle;

307
src/js/utils/dom.js
View File

@ -12,12 +12,12 @@ import computedStyle from './computed-style';
/**
* Detect if a value is a string with any non-whitespace characters.
*
* @param {string} str
* The string to check
* @private
* @param {string} str
* The string to check
*
* @return {boolean}
* - True if the string is non-blank
* - False otherwise
* Will be `true` if the string is non-blank, `false` otherwise.
*
*/
function isNonBlankString(str) {
@ -28,12 +28,12 @@ function isNonBlankString(str) {
* Throws an error if the passed string has whitespace. This is used by
* class methods to be relatively consistent with the classList API.
*
* @param {string} str
* @private
* @param {string} str
* The string to check for whitespace.
*
* @throws {Error}
* Throws an error if there is whitespace in the string.
*
*/
function throwIfWhitespace(str) {
if ((/\s/).test(str)) {
@ -44,7 +44,8 @@ function throwIfWhitespace(str) {
/**
* Produce a regular expression for matching a className within an elements className.
*
* @param {string} className
* @private
* @param {string} className
* The className to generate the RegExp for.
*
* @return {RegExp}
@ -56,9 +57,10 @@ function classRegExp(className) {
}
/**
* Whether the current DOM interface appears to be real.
* Whether the current DOM interface appears to be real (i.e. not simulated).
*
* @return {boolean}
* Will be `true` if the DOM appears to be real, `false` otherwise.
*/
export function isReal() {
// Both document and window will never be undefined thanks to `global`.
@ -68,12 +70,11 @@ export function isReal() {
/**
* Determines, via duck typing, whether or not a value is a DOM element.
*
* @param {Mixed} value
* The thing to check
* @param {Mixed} value
* The value to check.
*
* @return {boolean}
* - True if it is a DOM element
* - False otherwise
* Will be `true` if the value is a DOM element, `false` otherwise.
*/
export function isEl(value) {
return isObject(value) && value.nodeType === 1;
@ -83,7 +84,8 @@ export function isEl(value) {
* Determines if the current DOM is embedded in an iframe.
*
* @return {boolean}
*
* Will be `true` if the DOM is embedded in an iframe, `false`
* otherwise.
*/
export function isInFrame() {
@ -99,11 +101,12 @@ export function isInFrame() {
/**
* Creates functions to query the DOM using a given method.
*
* @param {string} method
* The method to create the query with.
* @private
* @param {string} method
* The method to create the query with.
*
* @return {Function}
* The query method
* @return {Function}
* The query method
*/
function createQuerier(method) {
return function(selector, context) {
@ -121,19 +124,19 @@ function createQuerier(method) {
}
/**
* Creates an element and applies properties.
* Creates an element and applies properties, attributes, and inserts content.
*
* @param {string} [tagName='div']
* @param {string} [tagName='div']
* Name of tag to be created.
*
* @param {Object} [properties={}]
* @param {Object} [properties={}]
* Element properties to be applied.
*
* @param {Object} [attributes={}]
* @param {Object} [attributes={}]
* Element attributes to be applied.
*
* @param {String|Element|TextNode|Array|Function} [content]
* Contents for the element (see: {@link dom:normalizeContent})
* @param {module:dom~ContentDescriptor} content
* A content descriptor object.
*
* @return {Element}
* The element that was created.
@ -176,11 +179,11 @@ export function createEl(tagName = 'div', properties = {}, attributes = {}, cont
/**
* Injects text into an element, replacing any existing contents entirely.
*
* @param {Element} el
* The element to add text content into
* @param {Element} el
* The element to add text content into
*
* @param {string} text
* The text content to add.
* @param {string} text
* The text content to add.
*
* @return {Element}
* The element with added text content.
@ -212,17 +215,16 @@ export function prependTo(child, parent) {
}
/**
* Check if an element has a CSS class
* Check if an element has a class name.
*
* @param {Element} element
* Element to check
* @param {Element} element
* Element to check
*
* @param {string} classToCheck
* Class name to check for
* @param {string} classToCheck
* Class name to check for
*
* @return {boolean}
* - True if the element had the class
* - False otherwise.
* Will be `true` if the element has a class, `false` otherwise.
*
* @throws {Error}
* Throws an error if `classToCheck` has white space.
@ -236,16 +238,16 @@ export function hasClass(element, classToCheck) {
}
/**
* Add a CSS class name to an element
* Add a class name to an element.
*
* @param {Element} element
* Element to add class name to.
* @param {Element} element
* Element to add class name to.
*
* @param {string} classToAdd
* Class name to add.
* @param {string} classToAdd
* Class name to add.
*
* @return {Element}
* The dom element with the added class name.
* The DOM element with the added class name.
*/
export function addClass(element, classToAdd) {
if (element.classList) {
@ -261,16 +263,16 @@ export function addClass(element, classToAdd) {
}
/**
* Remove a CSS class name from an element
* Remove a class name from an element.
*
* @param {Element} element
* Element to remove a class name from.
* @param {Element} element
* Element to remove a class name from.
*
* @param {string} classToRemove
* Class name to remove
* @param {string} classToRemove
* Class name to remove
*
* @return {Element}
* The dom element with class name removed.
* The DOM element with class name removed.
*/
export function removeClass(element, classToRemove) {
if (element.classList) {
@ -286,33 +288,33 @@ export function removeClass(element, classToRemove) {
}
/**
* The callback definition for toggleElClass.
* The callback definition for toggleClass.
*
* @callback Dom~PredicateCallback
* @param {Element} element
* The DOM element of the Component.
* @callback module:dom~PredicateCallback
* @param {Element} element
* The DOM element of the Component.
*
* @param {string} classToToggle
* The `className` that wants to be toggled
* @param {string} classToToggle
* The `className` that wants to be toggled
*
* @return {boolean|undefined}
* - If true the `classToToggle` will get added to `element`.
* - If false the `classToToggle` will get removed from `element`.
* - If undefined this callback will be ignored
* @return {boolean|undefined}
* If `true` is returned, the `classToToggle` will be added to the
* `element`. If `false`, the `classToToggle` will be removed from
* the `element`. If `undefined`, the callback will be ignored.
*/
/**
* Adds or removes a CSS class name on an element depending on an optional
* Adds or removes a class name to/from an element depending on an optional
* condition or the presence/absence of the class name.
*
* @param {Element} element
* The element to toggle a class name on.
* @param {Element} element
* The element to toggle a class name on.
*
* @param {string} classToToggle
* The class that should be toggled
* @param {string} classToToggle
* The class that should be toggled.
*
* @param {boolean|PredicateCallback} [predicate]
* See the return value for {@link Dom~PredicateCallback}
* @param {boolean|module:dom~PredicateCallback} [predicate]
* See the return value for {@link module:dom~PredicateCallback}
*
* @return {Element}
* The element with a class that has been toggled.
@ -369,16 +371,17 @@ export function setAttributes(el, attributes) {
}
/**
* Get an element's attribute values, as defined on the HTML tag
* Attributes are not the same as properties. They're defined on the tag
* or with setAttribute (which shouldn't be used with HTML)
* This will return true or false for boolean attributes.
* Get an element's attribute values, as defined on the HTML tag.
*
* @param {Element} tag
* Element from which to get tag attributes.
* Attributes are not the same as properties. They're defined on the tag
* or with setAttribute.
*
* @param {Element} tag
* Element from which to get tag attributes.
*
* @return {Object}
* All attributes of the element.
* All attributes of the element. Boolean attributes will be `true` or
* `false`, others will be strings.
*/
export function getAttributes(tag) {
const obj = {};
@ -412,52 +415,52 @@ export function getAttributes(tag) {
}
/**
* Get the value of an element's attribute
* Get the value of an element's attribute.
*
* @param {Element} el
* A DOM element
* A DOM element.
*
* @param {string} attribute
* Attribute to get the value of
* Attribute to get the value of.
*
* @return {string}
* value of the attribute
* The value of the attribute.
*/
export function getAttribute(el, attribute) {
return el.getAttribute(attribute);
}
/**
* Set the value of an element's attribute
* Set the value of an element's attribute.
*
* @param {Element} el
* A DOM element
* A DOM element.
*
* @param {string} attribute
* Attribute to set
* Attribute to set.
*
* @param {string} value
* Value to set the attribute to
* Value to set the attribute to.
*/
export function setAttribute(el, attribute, value) {
el.setAttribute(attribute, value);
}
/**
* Remove an element's attribute
* Remove an element's attribute.
*
* @param {Element} el
* A DOM element
* A DOM element.
*
* @param {string} attribute
* Attribute to remove
* Attribute to remove.
*/
export function removeAttribute(el, attribute) {
el.removeAttribute(attribute);
}
/**
* Attempt to block the ability to select text while dragging controls
* Attempt to block the ability to select text.
*/
export function blockTextSelection() {
document.body.focus();
@ -467,7 +470,7 @@ export function blockTextSelection() {
}
/**
* Turn off text selection blocking
* Turn off text selection blocking.
*/
export function unblockTextSelection() {
document.onselectstart = function() {
@ -492,7 +495,7 @@ export function unblockTextSelection() {
* Element whose `ClientRect` we want to calculate.
*
* @return {Object|undefined}
* Always returns a plain
* Always returns a plain object - or `undefined` if it cannot.
*/
export function getBoundingClientRect(el) {
if (el && el.getBoundingClientRect && el.parentNode) {
@ -518,26 +521,26 @@ export function getBoundingClientRect(el) {
}
/**
* The postion of a DOM element on the page.
* Represents the position of a DOM element on the page.
*
* @typedef {Object} module:dom~Position
* @typedef {Object} module:dom~Position
*
* @property {number} left
* Pixels to the left
* Pixels to the left.
*
* @property {number} top
* Pixels on top
* Pixels from the top.
*/
/**
* Offset Left.
* getBoundingClientRect technique from
* John Resig
* Get the position of an element in the DOM.
*
* Uses `getBoundingClientRect` technique from John Resig.
*
* @see http://ejohn.org/blog/getboundingclientrect-is-awesome/
*
* @param {Element} el
* Element from which to get offset
* @param {Element} el
* Element from which to get offset.
*
* @return {module:dom~Position}
* The position of the element that was passed in.
@ -575,9 +578,9 @@ export function findPosition(el) {
}
/**
* x and y coordinates for a dom element or mouse pointer
* Represents x and y coordinates for a DOM element or mouse pointer.
*
* @typedef {Object} Dom~Coordinates
* @typedef {Object} module:dom~Coordinates
*
* @property {number} x
* x coordinate in pixels
@ -587,18 +590,18 @@ export function findPosition(el) {
*/
/**
* Get pointer position in element
* Returns an object with x and y coordinates.
* Get the pointer position within an element.
*
* The base on the coordinates are the bottom left of the element.
*
* @param {Element} el
* Element on which to get the pointer position on
* @param {Element} el
* Element on which to get the pointer position on.
*
* @param {EventTarget~Event} event
* Event object
* @param {EventTarget~Event} event
* Event object.
*
* @return {Dom~Coordinates}
* A Coordinates object corresponding to the mouse position.
* @return {module:dom~Coordinates}
* A coordinates object corresponding to the mouse position.
*
*/
export function getPointerPosition(el, event) {
@ -626,12 +629,11 @@ export function getPointerPosition(el, event) {
/**
* Determines, via duck typing, whether or not a value is a text node.
*
* @param {Mixed} value
* Check if this value is a text node.
* @param {Mixed} value
* Check if this value is a text node.
*
* @return {boolean}
* - True if it is a text node
* - False otherwise
* Will be `true` if the value is a text node, `false` otherwise.
*/
export function isTextNode(value) {
return isObject(value) && value.nodeType === 3;
@ -640,8 +642,8 @@ export function isTextNode(value) {
/**
* Empties the contents of an element.
*
* @param {Element} el
* The element to empty children from
* @param {Element} el
* The element to empty children from
*
* @return {Element}
* The element with no children
@ -653,26 +655,37 @@ export function emptyEl(el) {
return el;
}
/**
* This is a mixed value that describes content to be injected into the DOM
* via some method. It can be of the following types:
*
* Type | Description
* -----------|-------------
* `string` | The value will be normalized into a text node.
* `Element` | The value will be accepted as-is.
* `TextNode` | The value will be accepted as-is.
* `Array` | A one-dimensional array of strings, elements, text nodes, or functions. These functions should return a string, element, or text node (any other return value, like an array, will be ignored).
* `Function` | A function, which is expected to return a string, element, text node, or array - any of the other possible values described above. This means that a content descriptor could be a function that returns an array of functions, but those second-level functions must return strings, elements, or text nodes.
*
* @typedef {string|Element|TextNode|Array|Function} module:dom~ContentDescriptor
*/
/**
* Normalizes content for eventual insertion into the DOM.
*
* This allows a wide range of content definition methods, but protects
* from falling into the trap of simply writing to `innerHTML`, which is
* an XSS concern.
* This allows a wide range of content definition methods, but helps protect
* from falling into the trap of simply writing to `innerHTML`, which could
* be an XSS concern.
*
* The content for an element can be passed in multiple types and
* combinations, whose behavior is as follows:
*
* @param {string|Element|TextNode|Array|Function} content
* - String: Normalized into a text node.
* - Element/TextNode: Passed through.
* - Array: A one-dimensional array of strings, elements, nodes, or functions
* (which return single strings, elements, or nodes).
* - Function: If the sole argument, is expected to produce a string, element,
* node, or array as defined above.
* @param {module:dom~ContentDescriptor} content
* A content descriptor value.
*
* @return {Array}
* All of the content that was passed in normalized.
* All of the content that was passed in, normalized to an array of
* elements or text nodes.
*/
export function normalizeContent(content) {
@ -705,12 +718,11 @@ export function normalizeContent(content) {
/**
* Normalizes and appends content to an element.
*
* @param {Element} el
* Element to append normalized content to.
* @param {Element} el
* Element to append normalized content to.
*
*
* @param {string|Element|TextNode|Array|Function} content
* See the `content` argument of {@link dom:normalizeContent}
* @param {module:dom~ContentDescriptor} content
* A content descriptor value.
*
* @return {Element}
* The element with appended normalized content.
@ -727,26 +739,24 @@ export function appendContent(el, content) {
* @param {Element} el
* Element to insert normalized content into.
*
* @param {string|Element|TextNode|Array|Function} content
* See the `content` argument of {@link dom:normalizeContent}
* @param {module:dom~ContentDescriptor} content
* A content descriptor value.
*
* @return {Element}
* The element with inserted normalized content.
*
*/
export function insertContent(el, content) {
return appendContent(emptyEl(el), content);
}
/**
* Check if event was a single left click
* Check if an event was a single left click.
*
* @param {EventTarget~Event} event
* Event object
* @param {EventTarget~Event} event
* Event object.
*
* @return {boolean}
* - True if a left click
* - False if not a left click
* Will be `true` if a single left click, `false` otherwise.
*/
export function isSingleLeftClick(event) {
// Note: if you create something draggable, be sure to
@ -792,14 +802,14 @@ export function isSingleLeftClick(event) {
* Finds a single DOM element matching `selector` within the optional
* `context` of another DOM element (defaulting to `document`).
*
* @param {string} selector
* A valid CSS selector, which will be passed to `querySelector`.
* @param {string} selector
* A valid CSS selector, which will be passed to `querySelector`.
*
* @param {Element|String} [context=document]
* A DOM element within which to query. Can also be a selector
* string in which case the first matching element will be used
* as context. If missing (or no element matches selector), falls
* back to `document`.
* @param {Element|String} [context=document]
* A DOM element within which to query. Can also be a selector
* string in which case the first matching element will be used
* as context. If missing (or no element matches selector), falls
* back to `document`.
*
* @return {Element|null}
* The element that was found or null.
@ -810,17 +820,18 @@ export const $ = createQuerier('querySelector');
* Finds a all DOM elements matching `selector` within the optional
* `context` of another DOM element (defaulting to `document`).
*
* @param {string} selector
* A valid CSS selector, which will be passed to `querySelectorAll`.
* @param {string} selector
* A valid CSS selector, which will be passed to `querySelectorAll`.
*
* @param {Element|String} [context=document]
* A DOM element within which to query. Can also be a selector
* string in which case the first matching element will be used
* as context. If missing (or no element matches selector), falls
* back to `document`.
* @param {Element|String} [context=document]
* A DOM element within which to query. Can also be a selector
* string in which case the first matching element will be used
* as context. If missing (or no element matches selector), falls
* back to `document`.
*
* @return {NodeList}
* A element list of elements that were found. Will be empty if none were found.
* A element list of elements that were found. Will be empty if none
* were found.
*
*/
export const $$ = createQuerier('querySelectorAll');

10
src/js/utils/events.js
View File

@ -4,9 +4,9 @@
* This should work very similarly to jQuery's events, however it's based off the book version which isn't as
* robust as jquery's, so there's probably some differences.
*
* @file events.js
* @module events
*/
import * as DomData from './dom-data';
import * as Guid from './guid.js';
import log from './log.js';
@ -398,8 +398,8 @@ export function off(elem, type, fn) {
* data hash to pass along with the event
*
* @return {boolean|undefined}
* - Returns the opposite of `defaultPrevented` if default was prevented
* - Otherwise returns undefined
* Returns the opposite of `defaultPrevented` if default was
* prevented. Otherwise, returns `undefined`
*/
export function trigger(elem, event, hash) {
// Fetches element data and a reference to the parent (for bubbling).
@ -452,7 +452,7 @@ export function trigger(elem, event, hash) {
}
/**
* Trigger a listener only once for an event
* Trigger a listener only once for an event.
*
* @param {Element|Object} elem
* Element or object to bind to.
@ -461,7 +461,7 @@ export function trigger(elem, event, hash) {
* Name/type of event
*
* @param {Event~EventListener} fn
* Event Listener function
* Event listener function
*/
export function one(elem, type, fn) {
if (Array.isArray(type)) {

62
src/js/utils/fn.js
View File

@ -6,20 +6,24 @@ import { newGUID } from './guid.js';
import window from 'global/window';
/**
* Bind (a.k.a proxy or Context). A simple method for changing the context of a function
* It also stores a unique id on the function so it can be easily removed from events.
* Bind (a.k.a proxy or context). A simple method for changing the context of
* a function.
*
* @param {Mixed} context
* The object to bind as scope.
* It also stores a unique id on the function so it can be easily removed from
* events.
*
* @param {Function} fn
* The function to be bound to a scope.
* @function
* @param {Mixed} context
* The object to bind as scope.
*
* @param {number} [uid]
* An optional unique ID for the function to be set
* @param {Function} fn
* The function to be bound to a scope.
*
* @return {Function}
* The new function that will be bound into the context given
* @param {number} [uid]
* An optional unique ID for the function to be set
*
* @return {Function}
* The new function that will be bound into the context given
*/
export const bind = function(context, fn, uid) {
// Make sure the function has a unique ID
@ -47,13 +51,14 @@ export const bind = function(context, fn, uid) {
* Wraps the given function, `fn`, with a new function that only invokes `fn`
* at most once per every `wait` milliseconds.
*
* @param {Function} fn
* The function to be throttled.
* @function
* @param {Function} fn
* The function to be throttled.
*
* @param {number} wait
* The number of milliseconds by which to throttle.
* @param {Number} wait
* The number of milliseconds by which to throttle.
*
* @return {Function}
* @return {Function}
*/
export const throttle = function(fn, wait) {
let last = Date.now();
@ -77,23 +82,24 @@ export const throttle = function(fn, wait) {
*
* Inspired by lodash and underscore implementations.
*
* @param {Function} func
* The function to wrap with debounce behavior.
* @function
* @param {Function} func
* The function to wrap with debounce behavior.
*
* @param {number} wait
* The number of milliseconds to wait after the last invocation.
* @param {number} wait
* The number of milliseconds to wait after the last invocation.
*
* @param {boolean} [immediate]
* Whether or not to invoke the function immediately upon creation.
* @param {boolean} [immediate]
* Whether or not to invoke the function immediately upon creation.
*
* @param {Object} [context=window]
* The "context" in which the debounced function should debounce. For
* example, if this function should be tied to a Video.js player,
* the player can be passed here. Alternatively, defaults to the
* global `window` object.
* @param {Object} [context=window]
* The "context" in which the debounced function should debounce. For
* example, if this function should be tied to a Video.js player,
* the player can be passed here. Alternatively, defaults to the
* global `window` object.
*
* @return {Function}
* A debounced function.
* @return {Function}
* A debounced function.
*/
export const debounce = function(func, wait, immediate, context = window) {
let timeout;

43
src/js/utils/format-time.js
View File

@ -4,14 +4,16 @@
*/
/**
* Format seconds as a time string, H:MM:SS or M:SS. Supplying a guide (in seconds)
* will force a number of leading zeros to cover the length of the guide.
* Format seconds as a time string, H:MM:SS or M:SS. Supplying a guide (in
* seconds) will force a number of leading zeros to cover the length of the
* guide.
*
* @param {number} seconds
* Number of seconds to be turned into a string
* @private
* @param {number} seconds
* Number of seconds to be turned into a string
*
* @param {number} guide
* Number (in seconds) to model the string after
* @param {number} guide
* Number (in seconds) to model the string after
*
* @return {string}
* Time formatted as H:MM:SS or M:SS
@ -44,14 +46,16 @@ const defaultImplementation = function(seconds, guide) {
return h + m + s;
};
// Internal pointer to the current implementation.
let implementation = defaultImplementation;
/**
* Replaces the default formatTime implementation with a custom implementation.
*
* @param {Function} customImplementation
* A function which will be used in place of the default formatTime implementation.
* Will receive the current time in seconds and the guide (in seconds) as arguments.
* A function which will be used in place of the default formatTime
* implementation. Will receive the current time in seconds and the
* guide (in seconds) as arguments.
*/
export function setFormatTime(customImplementation) {
implementation = customImplementation;
@ -64,6 +68,27 @@ export function resetFormatTime() {
implementation = defaultImplementation;
}
export default function(seconds, guide = seconds) {
/**
* Delegates to either the default time formatting function or a custom
* function supplied via `setFormatTime`.
*
* Formats seconds as a time string (H:MM:SS or M:SS). Supplying a
* guide (in seconds) will force a number of leading zeros to cover the
* length of the guide.
*
* @static
* @example formatTime(125, 600) === "02:05"
* @param {number} seconds
* Number of seconds to be turned into a string
*
* @param {number} guide
* Number (in seconds) to model the string after
*
* @return {string}
* Time formatted as H:MM:SS or M:SS
*/
function formatTime(seconds, guide = seconds) {
return implementation(seconds, guide);
}
export default formatTime;

27
src/js/utils/log.js
View File

@ -69,7 +69,21 @@ export const logByType = (type, args) => {
/**
* Logs plain debug messages. Similar to `console.log`.
*
* @class
* Due to [limitations](https://github.com/jsdoc3/jsdoc/issues/955#issuecomment-313829149)
* of our JSDoc template, we cannot properly document this as both a function
* and a namespace, so its function signature is documented here.
*
* #### Arguments
* ##### *args
* Mixed[]
*
* Any combination of values that could be passed to `console.log()`.
*
* #### Return Value
*
* `undefined`
*
* @namespace
* @param {Mixed[]} args
* One or more messages or objects that should be logged.
*/
@ -83,7 +97,7 @@ log = function(...args) {
* in that logging level. These strings are used to create a regular expression
* matching the function name being called.
*
* Levels provided by video.js are:
* Levels provided by Video.js are:
*
* - `off`: Matches no calls. Any value that can be cast to `false` will have
* this effect. The most restrictive.
@ -107,12 +121,13 @@ log.levels = {
};
/**
* Get or set the current logging level. If a string matching a key from
* {@link log.levels} is provided, acts as a setter. Regardless of argument,
* returns the current logging level.
* Get or set the current logging level.
*
* If a string matching a key from {@link module:log.levels} is provided, acts
* as a setter.
*
* @param {string} [lvl]
* Pass to set a new logging level.
* Pass a valid level to set a new logging level.
*
* @return {string}
* The current logging level.

15
src/js/utils/merge-options.js
View File

@ -5,16 +5,23 @@
import {each, isPlain} from './obj';
/**
* Deep-merge one or more options objects, recursively merging **only** plain
* object properties.
* Merge two objects recursively.
*
* Performs a deep merge like
* {@link https://lodash.com/docs/4.17.10#merge|lodash.merge}, but only merges
* plain objects (not arrays, elements, or anything else).
*
* Non-plain object values will be copied directly from the right-most
* argument.
*
* @static
* @param {Object[]} sources
* One or more objects to merge into a new object.
*
* @return {Object}
* A new object that is the merged result of all sources.
*/
export default function mergeOptions(...sources) {
function mergeOptions(...sources) {
const result = {};
sources.forEach(source => {
@ -38,3 +45,5 @@ export default function mergeOptions(...sources) {
return result;
}
export default mergeOptions;

83
src/js/utils/time-ranges.js
View File

@ -7,29 +7,30 @@
* Returns the time for the specified index at the start or end
* of a TimeRange object.
*
* @function time-ranges:indexFunction
* @typedef {Function} TimeRangeIndex
*
* @param {number} [index=0]
* The range number to return the time for.
* @param {number} [index=0]
* The range number to return the time for.
*
* @return {number}
* The time that offset at the specified index.
* @return {number}
* The time offset at the specified index.
*
* @depricated index must be set to a value, in the future this will throw an error.
* @deprecated The index argument must be provided.
* In the future, leaving it out will throw an error.
*/
/**
* An object that contains ranges of time for various reasons.
* An object that contains ranges of time.
*
* @typedef {Object} TimeRange
* @typedef {Object} TimeRange
*
* @property {number} length
* The number of time ranges represented by this Object
* The number of time ranges represented by this object.
*
* @property {time-ranges:indexFunction} start
* @property {module:time-ranges~TimeRangeIndex} start
* Returns the time offset at which a specified time range begins.
*
* @property {time-ranges:indexFunction} end
* @property {module:time-ranges~TimeRangeIndex} end
* Returns the time offset at which a specified time range ends.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges
@ -38,16 +39,17 @@
/**
* Check if any of the time ranges are over the maximum index.
*
* @param {string} fnName
* The function name to use for logging
* @private
* @param {string} fnName
* The function name to use for logging
*
* @param {number} index
* The index to check
* @param {number} index
* The index to check
*
* @param {number} maxIndex
* The maximum possible index
* @param {number} maxIndex
* The maximum possible index
*
* @throws {Error} if the timeRanges provided are over the maxIndex
* @throws {Error} if the timeRanges provided are over the maxIndex
*/
function rangeCheck(fnName, index, maxIndex) {
if (typeof index !== 'number' || index < 0 || index > maxIndex) {
@ -59,24 +61,25 @@ function rangeCheck(fnName, index, maxIndex) {
* Get the time for the specified index at the start or end
* of a TimeRange object.
*
* @param {string} fnName
* The function name to use for logging
* @private
* @param {string} fnName
* The function name to use for logging
*
* @param {string} valueIndex
* The property that should be used to get the time. should be 'start' or 'end'
* @param {string} valueIndex
* The property that should be used to get the time. should be
* 'start' or 'end'
*
* @param {Array} ranges
* An array of time ranges
* @param {Array} ranges
* An array of time ranges
*
* @param {Array} [rangeIndex=0]
* The index to start the search at
* @param {Array} [rangeIndex=0]
* The index to start the search at
*
* @return {number}
* The time that offset at the specified index.
* @return {number}
* The time that offset at the specified index.
*
*
* @depricated rangeIndex must be set to a value, in the future this will throw an error.
* @throws {Error} if rangeIndex is more than the length of ranges
* @deprecated rangeIndex must be set to a value, in the future this will throw an error.
* @throws {Error} if rangeIndex is more than the length of ranges
*/
function getRange(fnName, valueIndex, ranges, rangeIndex) {
rangeCheck(fnName, rangeIndex, ranges.length - 1);
@ -86,8 +89,9 @@ function getRange(fnName, valueIndex, ranges, rangeIndex) {
/**
* Create a time range object given ranges of time.
*
* @param {Array} [ranges]
* An array of time ranges.
* @private
* @param {Array} [ranges]
* An array of time ranges.
*/
function createTimeRangesObj(ranges) {
if (ranges === undefined || ranges.length === 0) {
@ -109,15 +113,16 @@ function createTimeRangesObj(ranges) {
}
/**
* Should create a fake `TimeRange` object which mimics an HTML5 time range instance.
* Create a `TimeRange` object which mimics an
* {@link https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges|HTML5 TimeRanges instance}.
*
* @param {number|Array} start
* The start of a single range or an array of ranges
* @param {number|Array[]} start
* The start of a single range (a number) or an array of ranges (an
* array of arrays of two numbers each).
*
* @param {number} end
* The end of a single range.
*
* @private
* The end of a single range. Cannot be used with the array form of
* the `start` argument.
*/
export function createTimeRanges(start, end) {
if (Array.isArray(start)) {

43
src/js/utils/url.js
View File

@ -33,11 +33,12 @@ import window from 'global/window';
/**
* Resolve and parse the elements of a URL.
*
* @param {String} url
* The url to parse
* @function
* @param {String} url
* The url to parse
*
* @return {url:URLObject}
* An object of url details
* @return {url:URLObject}
* An object of url details
*/
export const parseUrl = function(url) {
const props = ['protocol', 'hostname', 'port', 'pathname', 'search', 'hash', 'host'];
@ -93,16 +94,16 @@ export const parseUrl = function(url) {
};
/**
* Get absolute version of relative URL. Used to tell flash correct URL.
* Get absolute version of relative URL. Used to tell Flash the correct URL.
*
* @function
* @param {string} url
* URL to make absolute
*
* @param {string} url
* URL to make absolute
* @return {string}
* Absolute URL
*
* @return {string}
* Absolute URL
*
* @see http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue
* @see http://stackoverflow.com/questions/470832/getting-an-absolute-url-from-a-relative-one-ie6-issue
*/
export const getAbsoluteURL = function(url) {
// Check if absolute URL
@ -121,12 +122,13 @@ export const getAbsoluteURL = function(url) {
* Returns the extension of the passed file name. It will return an empty string
* if passed an invalid path.
*
* @param {string} path
* The fileName path like '/path/to/file.mp4'
* @function
* @param {string} path
* The fileName path like '/path/to/file.mp4'
*
* @return {string}
* The extension in lower case or an empty string if no
* extension could be found.
* @returns {string}
* The extension in lower case or an empty string if no
* extension could be found.
*/
export const getFileExtension = function(path) {
if (typeof path === 'string') {
@ -144,11 +146,12 @@ export const getFileExtension = function(path) {
/**
* Returns whether the url passed is a cross domain request or not.
*
* @param {string} url
* The url to check.
* @function
* @param {string} url
* The url to check.
*
* @return {boolean}
* Whether it is a cross domain request or not.
* @return {boolean}
* Whether it is a cross domain request or not.
*/
export const isCrossOrigin = function(url) {
const winLoc = window.location;

507
src/js/video.js
View File

@ -26,7 +26,7 @@ import * as browser from './utils/browser.js';
import * as Url from './utils/url.js';
import {isObject} from './utils/obj';
import computedStyle from './utils/computed-style.js';
import extendFn from './extend.js';
import extend from './extend.js';
import xhr from 'xhr';
// Include the built-in techs
@ -36,6 +36,7 @@ import { use as middlewareUse, TERMINATOR } from './tech/middleware.js';
/**
* Normalize an `id` value by trimming off a leading `#`
*
* @private
* @param {string} id
* A string, maybe with a leading `#`.
*
@ -45,21 +46,83 @@ import { use as middlewareUse, TERMINATOR } from './tech/middleware.js';
const normalizeId = (id) => id.indexOf('#') === 0 ? id.slice(1) : id;
/**
* Doubles as the main function for users to create a player instance and also
* the main library object.
* The `videojs` function can be used to initialize or retrieve a player.
*
* @param {string|Element} id
* Video element or video element ID
* The `videojs()` function doubles as the main function for users to create a
* {@link Player} instance as well as the main library namespace.
*
* @param {Object} [options]
* Optional options object for config/settings
* It can also be used as a getter for a pre-existing {@link Player} instance.
* However, we _strongly_ recommend using `videojs.getPlayer()` for this
* purpose because it avoids any potential for unintended initialization.
*
* @param {Component~ReadyCallback} [ready]
* Optional ready callback
* Due to [limitations](https://github.com/jsdoc3/jsdoc/issues/955#issuecomment-313829149)
* of our JSDoc template, we cannot properly document this as both a function
* and a namespace, so its function signature is documented here.
*
* #### Arguments
* ##### id
* string|Element, **required**
*
* Video element or video element ID.
*
* ##### options
* Object, optional
*
* Options object for providing settings.
* See: [Options Guide](https://docs.videojs.com/tutorial-options.html).
*
* ##### ready
* {@link Component~ReadyCallback}, optional
*
* A function to be called when the {@link Player} and {@link Tech} are ready.
*
* #### Return Value
*
* The `videojs()` function returns a {@link Player} instance.
*
* @namespace
*
* @borrows AudioTrack as AudioTrack
* @borrows Component.getComponent as getComponent
* @borrows module:computed-style~computedStyle as computedStyle
* @borrows module:events.on as on
* @borrows module:events.one as one
* @borrows module:events.off as off
* @borrows module:events.trigger as trigger
* @borrows EventTarget as EventTarget
* @borrows module:extend~extend as extend
* @borrows module:fn.bind as bind
* @borrows module:format-time.formatTime as formatTime
* @borrows module:format-time.resetFormatTime as resetFormatTime
* @borrows module:format-time.setFormatTime as setFormatTime
* @borrows module:merge-options.mergeOptions as mergeOptions
* @borrows module:middleware.use as use
* @borrows Player.players as players
* @borrows Plugin.registerPlugin as registerPlugin
* @borrows Plugin.deregisterPlugin as deregisterPlugin
* @borrows Plugin.getPlugins as getPlugins
* @borrows Plugin.getPlugin as getPlugin
* @borrows Plugin.getPluginVersion as getPluginVersion
* @borrows Tech.getTech as getTech
* @borrows Tech.registerTech as registerTech
* @borrows TextTrack as TextTrack
* @borrows module:time-ranges.createTimeRanges as createTimeRange
* @borrows module:time-ranges.createTimeRanges as createTimeRanges
* @borrows module:url.isCrossOrigin as isCrossOrigin
* @borrows module:url.parseUrl as parseUrl
* @borrows VideoTrack as VideoTrack
*
* @param {string|Element} id
* Video element or video element ID.
*
* @param {Object} [options]
* Options object for providing settings.
* See: [Options Guide](https://docs.videojs.com/tutorial-options.html).
*
* @param {Component~ReadyCallback} [ready]
* A function to be called when the {@link Player} and {@link Tech} are
* ready.
*
* @return {Player}
* A player instance
* The `videojs()` function returns a {@link Player|Player} instance.
*/
function videojs(id, options, ready) {
let player = videojs.getPlayer(id);
@ -111,19 +174,19 @@ function videojs(id, options, ready) {
/**
* An Object that contains lifecycle hooks as keys which point to an array
* of functions that are run when a lifecycle is triggered
*
* @private
*/
videojs.hooks_ = {};
/**
* Get a list of hooks for a specific lifecycle
*
* @function videojs.hooks
* @param {string} type
* the lifecyle to get hooks from
*
* @param {string} type
* the lifecyle to get hooks from
*
* @param {Function|Function[]} [fn]
* Optionally add a hook (or hooks) to the lifecycle that your are getting.
* @param {Function|Function[]} [fn]
* Optionally add a hook (or hooks) to the lifecycle that your are getting.
*
* @return {Array}
* an array of hooks, or an empty array if there are none.
@ -172,11 +235,11 @@ videojs.hookOnce = function(type, fn) {
/**
* Remove a hook from a specific videojs lifecycle.
*
* @param {string} type
* the lifecycle that the function hooked to
* @param {string} type
* the lifecycle that the function hooked to
*
* @param {Function} fn
* The hooked function to remove
* @param {Function} fn
* The hooked function to remove
*
* @return {boolean}
* The function that was removed or undef
@ -224,7 +287,7 @@ if (window.VIDEOJS_NO_DYNAMIC_STYLE !== true && Dom.isReal()) {
setup.autoSetupTimeout(1, videojs);
/**
* Current software version. Follows semver.
* Current Video.js version. Follows [semantic versioning](https://semver.org/).
*
* @type {string}
*/
@ -303,19 +366,7 @@ videojs.getAllPlayers = () =>
// we filter those out.
Object.keys(Player.players).map(k => Player.players[k]).filter(Boolean);
/**
* Expose players object.
*
* @memberOf videojs
* @property {Object} players
*/
videojs.players = Player.players;
/**
* Get a component class object by name
*
* @borrows Component.getComponent as videojs.getComponent
*/
videojs.getComponent = Component.getComponent;
/**
@ -343,27 +394,8 @@ videojs.registerComponent = (name, comp) => {
Component.registerComponent.call(Component, name, comp);
};
/**
* Get a Tech class object by name
*
* @borrows Tech.getTech as videojs.getTech
*/
videojs.getTech = Tech.getTech;
/**
* Register a Tech so it can referred to by name.
* This is used in the tech order for the player.
*
* @borrows Tech.registerTech as videojs.registerTech
*/
videojs.registerTech = Tech.registerTech;
/**
* Register a middleware to a source type.
*
* @param {String} type A string representing a MIME type.
* @param {function(player):object} middleware A middleware factory that takes a player.
*/
videojs.use = middlewareUse;
/**
@ -371,7 +403,6 @@ videojs.use = middlewareUse;
* that the middleware is being terminated.
*
* @type {object}
* @memberOf {videojs}
* @property {object} middleware.TERMINATOR
*/
Object.defineProperty(videojs, 'middleware', {
@ -387,90 +418,32 @@ Object.defineProperty(videojs.middleware, 'TERMINATOR', {
});
/**
* A suite of browser and device tests from {@link browser}.
* A reference to the {@link module:browser|browser utility module} as an object.
*
* @type {Object}
* @private
* @see {@link module:browser|browser}
*/
videojs.browser = browser;
/**
* Whether or not the browser supports touch events. Included for backward
* compatibility with 4.x, but deprecated. Use `videojs.browser.TOUCH_ENABLED`
* instead going forward.
* Use {@link module:browser.TOUCH_ENABLED|browser.TOUCH_ENABLED} instead; only
* included for backward-compatibility with 4.x.
*
* @deprecated since version 5.0
* @deprecated Since version 5.0, use {@link module:browser.TOUCH_ENABLED|browser.TOUCH_ENABLED instead.
* @type {boolean}
*/
videojs.TOUCH_ENABLED = browser.TOUCH_ENABLED;
/**
* Subclass an existing class
* Mimics ES6 subclassing with the `extend` keyword
*
* @borrows extend:extendFn as videojs.extend
*/
videojs.extend = extendFn;
/**
* Merge two options objects recursively
* Performs a deep merge like lodash.merge but **only merges plain objects**
* (not arrays, elements, anything else)
* Other values will be copied directly from the second object.
*
* @borrows merge-options:mergeOptions as videojs.mergeOptions
*/
videojs.extend = extend;
videojs.mergeOptions = mergeOptions;
/**
* Change the context (this) of a function
*
* > NOTE: as of v5.0 we require an ES5 shim, so you should use the native
* `function() {}.bind(newContext);` instead of this.
*
* @borrows fn:bind as videojs.bind
*/
videojs.bind = Fn.bind;
/**
* Register a Video.js plugin.
*
* @borrows plugin:registerPlugin as videojs.registerPlugin
* @method registerPlugin
*
* @param {string} name
* The name of the plugin to be registered. Must be a string and
* must not match an existing plugin or a method on the `Player`
* prototype.
*
* @param {Function} plugin
* A sub-class of `Plugin` or a function for basic plugins.
*
* @return {Function}
* For advanced plugins, a factory function for that plugin. For
* basic plugins, a wrapper function that initializes the plugin.
*/
videojs.registerPlugin = Plugin.registerPlugin;
/**
* Deregister a Video.js plugin.
*
* @borrows plugin:deregisterPlugin as videojs.deregisterPlugin
* @method deregisterPlugin
*
* @param {string} name
* The name of the plugin to be deregistered. Must be a string and
* must match an existing plugin or a method on the `Player`
* prototype.
*
*/
videojs.deregisterPlugin = Plugin.deregisterPlugin;
/**
* Deprecated method to register a plugin with Video.js
*
* @deprecated
* videojs.plugin() is deprecated; use videojs.registerPlugin() instead
* @deprecated videojs.plugin() is deprecated; use videojs.registerPlugin() instead
*
* @param {string} name
* The plugin name
@ -483,39 +456,8 @@ videojs.plugin = (name, plugin) => {
return Plugin.registerPlugin(name, plugin);
};
/**
* Gets an object containing multiple Video.js plugins.
*
* @param {Array} [names]
* If provided, should be an array of plugin names. Defaults to _all_
* plugin names.
*
* @return {Object|undefined}
* An object containing plugin(s) associated with their name(s) or
* `undefined` if no matching plugins exist).
*/
videojs.getPlugins = Plugin.getPlugins;
/**
* Gets a plugin by name if it exists.
*
* @param {string} name
* The name of a plugin.
*
* @return {Function|undefined}
* The plugin (or `undefined`).
*/
videojs.getPlugin = Plugin.getPlugin;
/**
* Gets a plugin's version, if available
*
* @param {string} name
* The name of a plugin.
*
* @return {string}
* The plugin's version or an empty string.
*/
videojs.getPluginVersion = Plugin.getPluginVersion;
/**
@ -543,264 +485,43 @@ videojs.addLanguage = function(code, data) {
};
/**
* Log messages
* A reference to the {@link module:log|log utility module} as an object.
*
* @borrows log:log as videojs.log
* @type {Function}
* @see {@link module:log|log}
*/
videojs.log = log;
/**
* Creates an emulated TimeRange object.
*
* @borrows time-ranges:createTimeRanges as videojs.createTimeRange
*/
/**
* @borrows time-ranges:createTimeRanges as videojs.createTimeRanges
*/
videojs.createTimeRange = videojs.createTimeRanges = createTimeRanges;
/**
* Format seconds as a time string, H:MM:SS or M:SS
* Supplying a guide (in seconds) will force a number of leading zeros
* to cover the length of the guide
*
* @borrows format-time:formatTime as videojs.formatTime
*/
videojs.formatTime = formatTime;
/**
* Replaces format-time with a custom implementation, to be used in place of the default.
*
* @borrows format-time:setFormatTime as videojs.setFormatTime
*
* @method setFormatTime
*
* @param {Function} customFn
* A custom format-time function which will be called with the current time and guide (in seconds) as arguments.
* Passed fn should return a string.
*/
videojs.setFormatTime = setFormatTime;
/**
* Resets format-time to the default implementation.
*
* @borrows format-time:resetFormatTime as videojs.resetFormatTime
*
* @method resetFormatTime
*/
videojs.resetFormatTime = resetFormatTime;
/**
* Resolve and parse the elements of a URL
*
* @borrows url:parseUrl as videojs.parseUrl
*
*/
videojs.parseUrl = Url.parseUrl;
/**
* Returns whether the url passed is a cross domain request or not.
*
* @borrows url:isCrossOrigin as videojs.isCrossOrigin
*/
videojs.isCrossOrigin = Url.isCrossOrigin;
/**
* Event target class.
*
* @borrows EventTarget as videojs.EventTarget
*/
videojs.EventTarget = EventTarget;
/**
* Add an event listener to element
* It stores the handler function in a separate cache object
* and adds a generic handler to the element's event,
* along with a unique id (guid) to the element.
*
* @borrows events:on as videojs.on
*/
videojs.on = Events.on;
/**
* Trigger a listener only once for an event
*
* @borrows events:one as videojs.one
*/
videojs.one = Events.one;
/**
* Removes event listeners from an element
*
* @borrows events:off as videojs.off
*/
videojs.off = Events.off;
/**
* Trigger an event for an element
*
* @borrows events:trigger as videojs.trigger
*/
videojs.trigger = Events.trigger;
/**
* A cross-browser XMLHttpRequest wrapper. Here's a simple example:
* A cross-browser XMLHttpRequest wrapper.
*
* @param {Object} options
* settings for the request.
* @function
* @param {Object} options
* Settings for the request.
*
* @return {XMLHttpRequest|XDomainRequest}
* The request object.
* @return {XMLHttpRequest|XDomainRequest}
* The request object.
*
* @see https://github.com/Raynos/xhr
* @see https://github.com/Raynos/xhr
*/
videojs.xhr = xhr;
/**
* TextTrack class
*
* @borrows TextTrack as videojs.TextTrack
*/
videojs.TextTrack = TextTrack;
/**
* export the AudioTrack class so that source handlers can create
* AudioTracks and then add them to the players AudioTrackList
*
* @borrows AudioTrack as videojs.AudioTrack
*/
videojs.AudioTrack = AudioTrack;
/**
* export the VideoTrack class so that source handlers can create
* VideoTracks and then add them to the players VideoTrackList
*
* @borrows VideoTrack as videojs.VideoTrack
*/
videojs.VideoTrack = VideoTrack;
/**
* Determines, via duck typing, whether or not a value is a DOM element.
*
* @borrows dom:isEl as videojs.isEl
* @deprecated Use videojs.dom.isEl() instead
*/
/**
* Determines, via duck typing, whether or not a value is a text node.
*
* @borrows dom:isTextNode as videojs.isTextNode
* @deprecated Use videojs.dom.isTextNode() instead
*/
/**
* Creates an element and applies properties.
*
* @borrows dom:createEl as videojs.createEl
* @deprecated Use videojs.dom.createEl() instead
*/
/**
* Check if an element has a CSS class
*
* @borrows dom:hasElClass as videojs.hasClass
* @deprecated Use videojs.dom.hasClass() instead
*/
/**
* Add a CSS class name to an element
*
* @borrows dom:addElClass as videojs.addClass
* @deprecated Use videojs.dom.addClass() instead
*/
/**
* Remove a CSS class name from an element
*
* @borrows dom:removeElClass as videojs.removeClass
* @deprecated Use videojs.dom.removeClass() instead
*/
/**
* Adds or removes a CSS class name on an element depending on an optional
* condition or the presence/absence of the class name.
*
* @borrows dom:toggleElClass as videojs.toggleClass
* @deprecated Use videojs.dom.toggleClass() instead
*/
/**
* Apply attributes to an HTML element.
*
* @borrows dom:setElAttributes as videojs.setAttribute
* @deprecated Use videojs.dom.setAttributes() instead
*/
/**
* Get an element's attribute values, as defined on the HTML tag
* Attributes are not the same as properties. They're defined on the tag
* or with setAttribute (which shouldn't be used with HTML)
* This will return true or false for boolean attributes.
*
* @borrows dom:getElAttributes as videojs.getAttributes
* @deprecated Use videojs.dom.getAttributes() instead
*/
/**
* Empties the contents of an element.
*
* @borrows dom:emptyEl as videojs.emptyEl
* @deprecated Use videojs.dom.emptyEl() instead
*/
/**
* Normalizes and appends content to an element.
*
* The content for an element can be passed in multiple types and
* combinations, whose behavior is as follows:
*
* - String
* Normalized into a text node.
*
* - Element, TextNode
* Passed through.
*
* - Array
* A one-dimensional array of strings, elements, nodes, or functions (which
* return single strings, elements, or nodes).
*
* - Function
* If the sole argument, is expected to produce a string, element,
* node, or array.
*
* @borrows dom:appendContents as videojs.appendContet
* @deprecated Use videojs.dom.appendContent() instead
*/
/**
* Normalizes and inserts content into an element; this is identical to
* `appendContent()`, except it empties the element first.
*
* The content for an element can be passed in multiple types and
* combinations, whose behavior is as follows:
*
* - String
* Normalized into a text node.
*
* - Element, TextNode
* Passed through.
*
* - Array
* A one-dimensional array of strings, elements, nodes, or functions (which
* return single strings, elements, or nodes).
*
* - Function
* If the sole argument, is expected to produce a string, element,
* node, or array.
*
* @borrows dom:insertContent as videojs.insertContent
* @deprecated Use videojs.dom.insertContent() instead
*/
[
'isEl',
'isTextNode',
@ -821,27 +542,21 @@ videojs.VideoTrack = VideoTrack;
};
});
/**
* A safe getComputedStyle.
*
* This is because in Firefox, if the player is loaded in an iframe with `display:none`,
* then `getComputedStyle` returns `null`, so, we do a null-check to make sure
* that the player doesn't break in these cases.
* See https://bugzilla.mozilla.org/show_bug.cgi?id=548397 for more details.
*
* @borrows computed-style:computedStyle as videojs.computedStyle
*/
videojs.computedStyle = computedStyle;
/**
* Export the Dom utilities for use in external plugins
* and Tech's
* A reference to the {@link module:dom|DOM utility module} as an object.
*
* @type {Object}
* @see {@link module:dom|dom}
*/
videojs.dom = Dom;
/**
* Export the Url utilities for use in external plugins
* and Tech's
* A reference to the {@link module:url|URL utility module} as an object.
*
* @type {Object}
* @see {@link module:url|url}
*/
videojs.url = Url;

4
test/unit/extend.test.js
View File

@ -1,5 +1,5 @@
/* eslint-env qunit */
import extendFn from '../../src/js/extend.js';
import extend from '../../src/js/extend.js';
QUnit.module('extend.js');
@ -8,7 +8,7 @@ QUnit.test('should add implicit parent constructor call', function(assert) {
const Parent = function() {
superCalled = true;
};
const Child = extendFn(Parent, {
const Child = extend(Parent, {
foo: 'bar'
});
const child = new Child();

18
test/unit/tech/tech.test.js
View File

@ -3,7 +3,7 @@ import Tech from '../../../src/js/tech/tech.js';
import Html5 from '../../../src/js/tech/html5.js';
import Button from '../../../src/js/button.js';
import { createTimeRange } from '../../../src/js/utils/time-ranges.js';
import extendFn from '../../../src/js/extend.js';
import extend from '../../../src/js/extend.js';
import MediaError from '../../../src/js/media-error.js';
import AudioTrack from '../../../src/js/tracks/audio-track';
import VideoTrack from '../../../src/js/tracks/video-track';
@ -42,7 +42,7 @@ QUnit.module('Media Tech', {
});
QUnit.test('Tech.registerTech and Tech.getTech', function(assert) {
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
const oldTechs = Tech.techs_;
const oldDefaultTechOrder = Tech.defaultTechOrder_;
@ -222,7 +222,7 @@ QUnit.test('switching sources should clear all remote tracks that are added with
};
// Define a new tech class
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
// Create source handler
const handler = {
@ -307,7 +307,7 @@ QUnit.test('should add the source handler interface to a tech', function(assert)
const sourceB = { src: 'no-support', type: 'no-support' };
// Define a new tech class
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
// Extend Tech with source handlers
Tech.withSourceHandlers(MyTech);
@ -506,7 +506,7 @@ QUnit.test('should add the source handler interface to a tech', function(assert)
QUnit.test('should handle unsupported sources with the source handler API', function(assert) {
// Define a new tech class
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
// Extend Tech with source handlers
Tech.withSourceHandlers(MyTech);
@ -555,7 +555,7 @@ QUnit.test('should track whether a video has played', function(assert) {
});
QUnit.test('delegates deferrables to the source handler', function(assert) {
const MyTech = extendFn(Tech, {
const MyTech = extend(Tech, {
seekable() {
throw new Error('You should not be calling me!');
},
@ -605,7 +605,7 @@ QUnit.test('delegates deferrables to the source handler', function(assert) {
QUnit.test('delegates only deferred deferrables to the source handler', function(assert) {
let seekingCount = 0;
const MyTech = extendFn(Tech, {
const MyTech = extend(Tech, {
seekable() {
throw new Error('You should not be calling me!');
},
@ -663,7 +663,7 @@ QUnit.test('Tech.isTech returns correct answers for techs and components', funct
});
QUnit.test('setSource after tech dispose should dispose source handler once', function(assert) {
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
Tech.withSourceHandlers(MyTech);
@ -707,7 +707,7 @@ QUnit.test('setSource after tech dispose should dispose source handler once', fu
});
QUnit.test('setSource after previous setSource should dispose source handler once', function(assert) {
const MyTech = extendFn(Tech);
const MyTech = extend(Tech);
Tech.withSourceHandlers(MyTech);