web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2025-03-17 21:18:27 +02:00
Code Releases Activity

docs(jsdoc): Update the jsdoc comments to modern syntax - Part 2 (#3698)

Browse Source 
Files updates:
* src/js/fullscreen-api.js
* src/js/loading-spinner.js
* src/js/media-error.js
* src/js/menu/menu-button.js
* src/js/menu/menu-item.js
* src/js/menu/menu.js
* src/js/modal-dialog.js
* src/js/plugins.js
* src/js/popup/popup-button.js
* src/js/popup/popup.js
This commit is contained in:
Brandon Casey 2016-12-02 15:12:01 -05:00 committed by Gary Katsevman
parent 1a0b2812ce
commit cfc3ed7f0f
10 changed files with 416 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/js/fullscreen-api.js
View File

@ -1,19 +1,21 @@
/**
* @file fullscreen-api.js
* @module fullscreen-api
* @private
*/
import document from 'global/document';
/*
* Store the browser-specific methods for the fullscreen API
* @type {Object|undefined}
* @private
/**
* Store the browser-specific methods for the fullscreen API.
*
* @type {Object}
* @see [Specification]{@link https://fullscreen.spec.whatwg.org}
* @see [Map Approach From Screenfull.js]{@link https://github.com/sindresorhus/screenfull.js}
*/
const FullscreenApi = {};
// browser API methods
// map approach from Screenful.js - https://github.com/sindresorhus/screenfull.js
const apiMap = [
// Spec: https://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html
[
'requestFullscreen',
'exitFullscreen',

10
src/js/loading-spinner.js
View File

@ -3,20 +3,18 @@
*/
import Component from './component';
/* Loading Spinner
================================================================================ */
/**
* Loading spinner for waiting events
* A loading spinner for use during waiting/loading events.
*
* @extends Component
* @class LoadingSpinner
*/
class LoadingSpinner extends Component {
/**
* Create the component's DOM element
* Create the `LoadingSpinner`s DOM element.
*
* @method createEl
* @return {Element}
* The dom element that gets created.
*/
createEl() {
return super.createEl('div', {

161
src/js/media-error.js
View File

@ -3,17 +3,22 @@
*/
import assign from 'object.assign';
/*
* Custom MediaError class which mimics the standard HTML5 MediaError class.
/**
* A Custom `MediaError` class which mimics the standard HTML5 `MediaError` class.
*
* @param {Number|String|Object|MediaError} value
* @param {number|string|Object|MediaError} value
* This can be of multiple types:
* - Number: should be a standard error code
* - String: an error message (the code will be 0)
* - number: should be a standard error code
* - string: an error message (the code will be 0)
* - Object: arbitrary properties
* - MediaError (native): used to populate a video.js MediaError object
* - MediaError (video.js): will return itself if it's already a
* video.js MediaError object.
* - `MediaError` (native): used to populate a video.js `MediaError` object
* - `MediaError` (video.js): will return itself if it's already a
* video.js `MediaError` object.
*
* @see [MediaError Spec]{@link https://dev.w3.org/html5/spec-author-view/video.html#mediaerror}
* @see [Encrypted MediaError Spec]{@link https://www.w3.org/TR/2013/WD-encrypted-media-20130510/#error-codes}
*
* @class MediaError
*/
function MediaError(value) {
@ -30,7 +35,7 @@ function MediaError(value) {
this.message = value;
} else if (typeof value === 'object') {
// We assign the `code` property manually because native MediaError objects
// We assign the `code` property manually because native `MediaError` objects
// do not expose it as an own/enumerable property of the object.
if (typeof value.code === 'number') {
this.code = value.code;
@ -44,37 +49,45 @@ function MediaError(value) {
}
}
/*
* The error code that refers two one of the defined
* MediaError types
/**
* The error code that refers two one of the defined `MediaError` types
*
* @type {Number}
*/
MediaError.prototype.code = 0;
/*
* An optional message to be shown with the error.
* Message is not part of the HTML5 video spec
* but allows for more informative custom errors.
/**
* An optional message that to show with the error. Message is not part of the HTML5
* video spec but allows for more informative custom errors.
*
* @type {String}
*/
MediaError.prototype.message = '';
/*
* An optional status code that can be set by plugins
* to allow even more detail about the error.
* For example the HLS plugin might provide the specific
* HTTP status code that was returned when the error
* occurred, then allowing a custom error overlay
* to display more information.
/**
* An optional status code that can be set by plugins to allow even more detail about
* the error. For example a plugin might provide a specific HTTP status code and an
* error message for that code. Then when the plugin gets that error this class will
* know how to display an error message for it. This allows a custom message to show
* up on the `Player` error overlay.
*
* @type {Array}
*/
MediaError.prototype.status = null;
// These errors are indexed by the W3C standard numeric value. The order
// should not be changed!
/**
* Errors indexed by the W3C standard. The order **CANNOT CHANGE**! See the
* specification listed under {@link MediaError} for more information.
*
* @enum {array}
* @readonly
* @property {string} 0 - MEDIA_ERR_CUSTOM
* @property {string} 1 - MEDIA_ERR_CUSTOM
* @property {string} 2 - MEDIA_ERR_ABORTED
* @property {string} 3 - MEDIA_ERR_NETWORK
* @property {string} 4 - MEDIA_ERR_SRC_NOT_SUPPORTED
* @property {string} 5 - MEDIA_ERR_ENCRYPTED
*/
MediaError.errorTypes = [
'MEDIA_ERR_CUSTOM',
'MEDIA_ERR_ABORTED',
@ -84,6 +97,12 @@ MediaError.errorTypes = [
'MEDIA_ERR_ENCRYPTED'
];
/**
* The default `MediaError` messages based on the {@link MediaError.errorTypes}.
*
* @type {Array}
* @constant
*/
MediaError.defaultMessages = {
1: 'You aborted the media playback',
2: 'A network error caused the media download to fail part-way.',
@ -100,4 +119,96 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
MediaError.prototype[MediaError.errorTypes[errNum]] = errNum;
}
// jsdocs for instance/static members added above
// instance methods use `#` and static methods use `.`
/**
* W3C error code for any custom error.
*
* @member MediaError#MEDIA_ERR_CUSTOM
* @constant {number}
* @default 0
*/
/**
* W3C error code for any custom error.
*
* @member MediaError.MEDIA_ERR_CUSTOM
* @constant {number}
* @default 0
*/
/**
* W3C error code for media error aborted.
*
* @member MediaError#MEDIA_ERR_ABORTED
* @constant {number}
* @default 1
*/
/**
* W3C error code for media error aborted.
*
* @member MediaError.MEDIA_ERR_ABORTED
* @constant {number}
* @default 1
*/
/**
* W3C error code for any network error.
*
* @member MediaError#MEDIA_ERR_NETWORK
* @constant {number}
* @default 2
*/
/**
* W3C error code for any network error.
*
* @member MediaError.MEDIA_ERR_NETWORK
* @constant {number}
* @default 2
*/
/**
* W3C error code for any decoding error.
*
* @member MediaError#MEDIA_ERR_DECODE
* @constant {number}
* @default 3
*/
/**
* W3C error code for any decoding error.
*
* @member MediaError.MEDIA_ERR_DECODE
* @constant {number}
* @default 3
*/
/**
* W3C error code for any time that a source is not supported.
*
* @member MediaError#MEDIA_ERR_SRC_NOT_SUPPORTED
* @constant {number}
* @default 4
*/
/**
* W3C error code for any time that a source is not supported.
*
* @member MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED
* @constant {number}
* @default 4
*/
/**
* W3C error code for any time that a source is encrypted.
*
* @member MediaError#MEDIA_ERR_ENCRYPTED
* @constant {number}
* @default 5
*/
/**
* W3C error code for any time that a source is encrypted.
*
* @member MediaError.MEDIA_ERR_ENCRYPTED
* @constant {number}
* @default 5
*/
export default MediaError;

96
src/js/menu/menu-button.js
View File

@ -9,15 +9,21 @@ import * as Fn from '../utils/fn.js';
import toTitleCase from '../utils/to-title-case.js';
/**
* A button class with a popup menu
* A `MenuButton` class for any popup {@link Menu}.
*
* @param {Player|Object} player
* @param {Object=} options
* @extends Button
* @class MenuButton
* @extends ClickableComponent
*/
class MenuButton extends ClickableComponent {
/**
* Creates an instance of this class.
*
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {Object} [options={}]
* The key/value store of player options.
*/
constructor(player, options = {}) {
super(player, options);
@ -31,9 +37,7 @@ class MenuButton extends ClickableComponent {
}
/**
* Update menu
*
* @method update
* Update the menu based on the current state of its items.
*/
update() {
const menu = this.createMenu();
@ -62,10 +66,10 @@ class MenuButton extends ClickableComponent {
}
/**
* Create menu
* Create the menu and add all items to it.
*
* @return {Menu} The constructed menu
* @method createMenu
* @return {Menu}
* The constructed menu
*/
createMenu() {
const menu = new Menu(this.player_);
@ -97,15 +101,15 @@ class MenuButton extends ClickableComponent {
/**
* Create the list of menu items. Specific to each subclass.
*
* @method createItems
* @abstract
*/
createItems() {}
/**
* Create the component's DOM element
* Create the `MenuButtons`s DOM element.
*
* @return {Element}
* @method createEl
* The element that gets created.
*/
createEl() {
return super.createEl('div', {
@ -114,10 +118,10 @@ class MenuButton extends ClickableComponent {
}
/**
* Allow sub components to stack CSS class names
* Builds the default DOM `className`.
*
* @return {String} The constructed class name
* @method buildCSSClass
* @return {string}
* The DOM `className` for this object.
*/
buildCSSClass() {
let menuButtonClass = 'vjs-menu-button';
@ -133,15 +137,21 @@ class MenuButton extends ClickableComponent {
}
/**
* When you click the button it adds focus, which
* will show the menu indefinitely.
* So we'll remove focus when the mouse leaves the button.
* Focus is needed for tab navigation.
* Allow sub components to stack CSS class names
* Handle a click on a `MenuButton`.
* See {@link ClickableComponent#handleClick} for instances where this is called.
*
* @method handleClick
* @param {EventTarget~Event} event
* The `keydown`, `tap`, or `click` event that caused this function to be
* called.
*
* @listens tap
* @listens click
*/
handleClick() {
handleClick(event) {
// When you click the button it adds focus, which will show the menu.
// So we'll remove focus when the mouse leaves the button. Focus is needed
// for tab navigation.
this.one(this.menu.contentEl(), 'mouseleave', Fn.bind(this, function(e) {
this.unpressButton();
this.el_.blur();
@ -154,10 +164,13 @@ class MenuButton extends ClickableComponent {
}
/**
* Handle key press on menu
* Handle tab, escape, down arrow, and up arrow keys for `MenuButton`. See
* {@link ClickableComponent#handleKeyPress} for instances where this is called.
*
* @param {Object} event Key press event
* @method handleKeyPress
* @param {EventTarget~Event} event
* The `keydown` event that caused this function to be called.
*
* @listens keydown
*/
handleKeyPress(event) {
@ -182,10 +195,13 @@ class MenuButton extends ClickableComponent {
}
/**
* Handle key press on submenu
* Handle a `keydown` event on a sub-menu. The listener for this is added in
* the constructor.
*
* @param {Object} event Key press event
* @method handleSubmenuKeyPress
* @param {EventTarget~Event} event
* Key press event
*
* @listens keydown
*/
handleSubmenuKeyPress(event) {
@ -202,9 +218,7 @@ class MenuButton extends ClickableComponent {
}
/**
* Makes changes based on button pressed
*
* @method pressButton
* Put the current `MenuButton` into a pressed state.
*/
pressButton() {
if (this.enabled_) {
@ -217,9 +231,7 @@ class MenuButton extends ClickableComponent {
}
/**
* Makes changes based on button unpressed
*
* @method unpressButton
* Take the current `MenuButton` out of a pressed state.
*/
unpressButton() {
if (this.enabled_) {
@ -232,10 +244,10 @@ class MenuButton extends ClickableComponent {
}
/**
* Disable the menu button
* Disable the `MenuButton`. Don't allow it to be clicked.
*
* @return {Component}
* @method disable
* @return {MenuButton}
* Returns itself; method can be chained.
*/
disable() {
// Unpress, but don't force focus on this button
@ -249,10 +261,10 @@ class MenuButton extends ClickableComponent {
}
/**
* Enable the menu button
* Enable the `MenuButton`. Allow it to be clicked.
*
* @return {Component}
* @method disable
* @return {MenuButton}
* Returns itself; method can be chained.
*/
enable() {
this.enabled_ = true;

48
src/js/menu/menu-item.js
View File

@ -8,13 +8,20 @@ import assign from 'object.assign';
/**
* The component for a menu item. `<li>`
*
* @param {Player|Object} player
* @param {Object=} options
* @extends Button
* @class MenuItem
* @extends ClickableComponent
*/
class MenuItem extends ClickableComponent {
/**
* Creates an instance of the this class.
*
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {Object} [options={}]
* The key/value store of player options.
*
*/
constructor(player, options) {
super(player, options);
@ -32,12 +39,19 @@ class MenuItem extends ClickableComponent {
}
/**
* Create the component's DOM element
* Create the `MenuItem's DOM element
*
* @param {string} [type=li]
* Element's node type, not actually used, always set to `li`.
*
* @param {Object} [props={}]
* An object of properties that should be set on the element
*
* @param {Object} [attrs={}]
* An object of attributes that should be set on the element
*
* @param {String=} type Desc
* @param {Object=} props Desc
* @return {Element}
* @method createEl
* The element that gets created.
*/
createEl(type, props, attrs) {
return super.createEl('li', assign({
@ -48,19 +62,25 @@ class MenuItem extends ClickableComponent {
}
/**
* Handle a click on the menu item, and set it to selected
* Any click on a `MenuItem` puts int into the selected state.
* See {@link ClickableComponent#handleClick} for instances where this is called.
*
* @method handleClick
* @param {EventTarget~Event} event
* The `keydown`, `tap`, or `click` event that caused this function to be
* called.
*
* @listens tap
* @listens click
*/
handleClick() {
handleClick(event) {
this.selected(true);
}
/**
* Set this menu item as selected or not
* Set the state for this menu item as selected or not.
*
* @param {Boolean} selected
* @method selected
* @param {boolean} selected
* if the menu item is selected or not
*/
selected(selected) {
if (this.selectable) {

48
src/js/menu/menu.js
View File

@ -7,14 +7,23 @@ import * as Fn from '../utils/fn.js';
import * as Events from '../utils/events.js';
/**
* The Menu component is used to build pop up menus, including subtitle and
* The Menu component is used to build popup menus, including subtitle and
* captions selection menus.
*
* @extends Component
* @class Menu
*/
class Menu extends Component {
/**
* Create an instance of this class.
*
* @param {Player} player
* the player that this component should attach to
*
* @param {Object} [options]
* Object of option names and values
*
*/
constructor(player, options) {
super(player, options);
@ -24,24 +33,25 @@ class Menu extends Component {
}
/**
* Add a menu item to the menu
* Add a {@link MenuItem} to the menu.
*
* @param {Object|string} component
* The name or instance of the `MenuItem` to add.
*
* @param {Object|String} component Component or component type to add
* @method addItem
*/
addItem(component) {
this.addChild(component);
component.on('click', Fn.bind(this, function() {
component.on('click', Fn.bind(this, function(event) {
this.unlockShowing();
// TODO: Need to set keyboard focus back to the menuButton
}));
}
/**
* Create the component's DOM element
* Create the `Menu`s DOM element.
*
* @return {Element}
* @method createEl
* the element that was created
*/
createEl() {
const contentElType = this.options_.contentElType || 'ul';
@ -71,10 +81,12 @@ class Menu extends Component {
}
/**
* Handle key press for menu
* Handle a `keydown` event on this menu. This listener is added in the constructor.
*
* @param {Object} event Event object
* @method handleKeyPress
* @param {EventTarget~Event} event
* A `keydown` event that happened on the menu.
*
* @listens keydown
*/
handleKeyPress(event) {
// Left and Down Arrows
@ -90,9 +102,7 @@ class Menu extends Component {
}
/**
* Move to next (lower) menu item for keyboard users
*
* @method stepForward
* Move to next (lower) menu item for keyboard users.
*/
stepForward() {
let stepChild = 0;
@ -104,9 +114,7 @@ class Menu extends Component {
}
/**
* Move to previous (higher) menu item for keyboard users
*
* @method stepBack
* Move to previous (higher) menu item for keyboard users.
*/
stepBack() {
let stepChild = 0;
@ -118,10 +126,10 @@ class Menu extends Component {
}
/**
* Set focus on a menu item in the menu
* Set focus on a {@link MenuItem} in the `Menu`.
*
* @param {Object|String} item Index of child item set focus on
* @method focus
* @param {Object|string} [item=0]
* Index of child item set focus on.
*/
focus(item = 0) {
const children = this.children().slice();

172
src/js/modal-dialog.js
View File

@ -16,38 +16,40 @@ const ESC = 27;
* is activated - or when ESC is pressed anywhere.
*
* @extends Component
* @class ModalDialog
*/
class ModalDialog extends Component {
/**
* Constructor for modals.
* Create an instance of this class.
*
* @param {Player} player
* @param {Object} [options]
* @param {Mixed} [options.content=undefined]
* Provide customized content for this modal.
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {String} [options.description]
* A text description for the modal, primarily for accessibility.
* @param {Object} [options]
* The key/value store of player options.
*
* @param {Boolean} [options.fillAlways=false]
* Normally, modals are automatically filled only the first time
* they open. This tells the modal to refresh its content
* every time it opens.
* @param {Mixed} [options.content=undefined]
* Provide customized content for this modal.
*
* @param {String} [options.label]
* A text label for the modal, primarily for accessibility.
* @param {string} [options.description]
* A text description for the modal, primarily for accessibility.
*
* @param {Boolean} [options.temporary=true]
* If `true`, the modal can only be opened once; it will be
* disposed as soon as it's closed.
* @param {boolean} [options.fillAlways=false]
* Normally, modals are automatically filled only the first time
* they open. This tells the modal to refresh its content
* every time it opens.
*
* @param {Boolean} [options.uncloseable=false]
* If `true`, the user will not be able to close the modal
* through the UI in the normal ways. Programmatic closing is
* still possible.
* @param {string} [options.label]
* A text label for the modal, primarily for accessibility.
*
* @param {boolean} [options.temporary=true]
* If `true`, the modal can only be opened once; it will be
* disposed as soon as it's closed.
*
* @param {boolean} [options.uncloseable=false]
* If `true`, the user will not be able to close the modal
* through the UI in the normal ways. Programmatic closing is
* still possible.
*/
constructor(player, options) {
super(player, options);
@ -76,10 +78,10 @@ class ModalDialog extends Component {
}
/**
* Create the modal's DOM element
* Create the `ModalDialog`'s DOM element
*
* @method createEl
* @return {Element}
* The DOM element that gets created.
*/
createEl() {
return super.createEl('div', {
@ -94,21 +96,23 @@ class ModalDialog extends Component {
}
/**
* Build the modal's CSS class.
* Builds the default DOM `className`.
*
* @method buildCSSClass
* @return {String}
* @return {string}
* The DOM `className` for this object.
*/
buildCSSClass() {
return `${MODAL_CLASS_NAME} vjs-hidden ${super.buildCSSClass()}`;
}
/**
* Handles key presses on the document, looking for ESC, which closes
* Handles `keydown` events on the document, looking for ESC, which closes
* the modal.
*
* @method handleKeyPress
* @param {Event} e
* @param {EventTarget~Event} e
* The keypress that triggered this event.
*
* @listens keydown
*/
handleKeyPress(e) {
if (e.which === ESC && this.closeable()) {
@ -119,7 +123,8 @@ class ModalDialog extends Component {
/**
* Returns the label string for this modal. Primarily used for accessibility.
*
* @return {String}
* @return {string}
* the localized or raw label of this modal.
*/
label() {
return this.options_.label || this.localize('Modal Window');
@ -129,7 +134,8 @@ class ModalDialog extends Component {
* Returns the description string for this modal. Primarily used for
* accessibility.
*
* @return {String}
* @return {string}
* The localized or raw description of this modal.
*/
description() {
let desc = this.options_.description || this.localize('This is a modal window.');
@ -145,13 +151,22 @@ class ModalDialog extends Component {
/**
* Opens the modal.
*
* @method open
* @fires ModalDialog#beforemodalopen
* @fires ModalDialog#modalopen
*
* @return {ModalDialog}
* Returns itself; method can be chained.
*/
open() {
if (!this.opened_) {
const player = this.player();
/**
* Fired just before a `ModalDialog` is opened.
*
* @event ModalDialog#beforemodalopen
* @type {EventTarget~Event}
*/
this.trigger('beforemodalopen');
this.opened_ = true;
@ -176,6 +191,13 @@ class ModalDialog extends Component {
player.controls(false);
this.show();
this.el().setAttribute('aria-hidden', 'false');
/**
* Fired just after a `ModalDialog` is opened.
*
* @event ModalDialog#modalopen
* @type {EventTarget~Event}
*/
this.trigger('modalopen');
this.hasBeenOpened_ = true;
}
@ -183,13 +205,13 @@ class ModalDialog extends Component {
}
/**
* Whether or not the modal is opened currently.
* If the `ModalDialog` is currently open or closed.
*
* @method opened
* @param {Boolean} [value]
* @param {boolean} [value]
* If given, it will open (`true`) or close (`false`) the modal.
*
* @return {Boolean}
* @return {boolean}
* the current open state of the modaldialog
*/
opened(value) {
if (typeof value === 'boolean') {
@ -199,15 +221,25 @@ class ModalDialog extends Component {
}
/**
* Closes the modal.
* Closes the modal, does nothing if the `ModalDialog` is
* not open.
*
* @fires ModalDialog#beforemodalclose
* @fires ModalDialog#modalclose
*
* @method close
* @return {ModalDialog}
* Returns itself; method can be chained.
*/
close() {
if (this.opened_) {
const player = this.player();
/**
* Fired just before a `ModalDialog` is closed.
*
* @event ModalDialog#beforemodalclose
* @type {EventTarget~Event}
*/
this.trigger('beforemodalclose');
this.opened_ = false;
@ -222,6 +254,13 @@ class ModalDialog extends Component {
player.controls(true);
this.hide();
this.el().setAttribute('aria-hidden', 'true');
/**
* Fired just after a `ModalDialog` is closed.
*
* @event ModalDialog#modalclose
* @type {EventTarget~Event}
*/
this.trigger('modalclose');
if (this.options_.temporary) {
@ -232,13 +271,13 @@ class ModalDialog extends Component {
}
/**
* Whether or not the modal is closeable via the UI.
* Check to see if the `ModalDialog` is closeable via the UI.
*
* @method closeable
* @param {Boolean} [value]
* If given as a Boolean, it will set the `closeable` option.
* @param {boolean} [value]
* If given as a boolean, it will set the `closeable` option.
*
* @return {Boolean}
* @return {boolean}
* Returns the final value of the closable option.
*/
closeable(value) {
if (typeof value === 'boolean') {
@ -270,11 +309,10 @@ class ModalDialog extends Component {
/**
* Fill the modal's content element with the modal's "content" option.
*
* The content element will be emptied before this change takes place.
*
* @method fill
* @return {ModalDialog}
* Returns itself; method can be chained.
*/
fill() {
return this.fillWith(this.content());
@ -282,20 +320,28 @@ class ModalDialog extends Component {
/**
* Fill the modal's content element with arbitrary content.
*
* The content element will be emptied before this change takes place.
*
* @method fillWith
* @fires ModalDialog#beforemodalfill
* @fires ModalDialog#modalfill
*
* @param {Mixed} [content]
* The same rules apply to this as apply to the `content` option.
*
* @return {ModalDialog}
* Returns itself; method can be chained.
*/
fillWith(content) {
const contentEl = this.contentEl();
const parentEl = contentEl.parentNode;
const nextSiblingEl = contentEl.nextSibling;
/**
* Fired just before a `ModalDialog` is filled with content.
*
* @event ModalDialog#beforemodalfill
* @type {EventTarget~Event}
*/
this.trigger('beforemodalfill');
this.hasBeenFilled_ = true;
@ -304,6 +350,12 @@ class ModalDialog extends Component {
parentEl.removeChild(contentEl);
this.empty();
Dom.insertContent(contentEl, content);
/**
* Fired just after a `ModalDialog` is filled with content.
*
* @event ModalDialog#modalfill
* @type {EventTarget~Event}
*/
this.trigger('modalfill');
// Re-inject the re-filled content element.
@ -317,16 +369,30 @@ class ModalDialog extends Component {
}
/**
* Empties the content element.
* Empties the content element. This happens anytime the modal is filled.
*
* This happens automatically anytime the modal is filled.
* @fires ModalDialog#beforemodalempty
* @fires ModalDialog#modalempty
*
* @method empty
* @return {ModalDialog}
* Returns itself; method can be chained.
*/
empty() {
/**
* Fired just before a `ModalDialog` is emptied.
*
* @event ModalDialog#beforemodalempty
* @type {EventTarget~Event}
*/
this.trigger('beforemodalempty');
Dom.emptyEl(this.contentEl());
/**
* Fired just after a `ModalDialog` is emptied.
*
* @event ModalDialog#modalempty
* @type {EventTarget~Event}
*/
this.trigger('modalempty');
return this;
}
@ -338,13 +404,13 @@ class ModalDialog extends Component {
* This does not update the DOM or fill the modal, but it is called during
* that process.
*
* @method content
* @param {Mixed} [value]
* If defined, sets the internal content value to be used on the
* next call(s) to `fill`. This value is normalized before being
* inserted. To "clear" the internal content value, pass `null`.
*
* @return {Mixed}
* The current content of the modal dialog
*/
content(value) {
if (typeof value !== 'undefined') {
@ -354,8 +420,8 @@ class ModalDialog extends Component {
}
}
/*
* Modal dialog default options.
/**
* Default options for `ModalDialog` default options.
*
* @type {Object}
* @private

14
src/js/plugins.js
View File

@ -1,14 +1,20 @@
/**
* @file plugins.js
* @module plugins
*/
import Player from './player.js';
/**
* The method for registering a video.js plugin
*
* @param {String} name The name of the plugin
* @param {Function} init The function that is run when the player inits
* @method plugin
*/
/**
* The method for registering a video.js plugin. {@link videojs:videojs.registerPlugin].
*
* @param {string} name
* The name of the plugin that is being registered
*
* @param {plugins:PluginFn} init
* The function that gets run when a `Player` initializes.
*/
const plugin = function(name, init) {
Player.prototype[name] = init;

34
src/js/popup/popup-button.js
View File

@ -5,15 +5,21 @@ import ClickableComponent from '../clickable-component.js';
import Component from '../component.js';
/**
* A button class with a popup control
* A button class for use with {@link Popup} controls
*
* @param {Player|Object} player
* @param {Object=} options
* @extends ClickableComponent
* @class PopupButton
*/
class PopupButton extends ClickableComponent {
/**
* Create an instance of this class.
*
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {Object} [options]
* The key/value store of player options.
*/
constructor(player, options = {}) {
super(player, options);
@ -21,9 +27,7 @@ class PopupButton extends ClickableComponent {
}
/**
* Update popup
*
* @method update
* Update the `Popup` that this button is attached to.
*/
update() {
const popup = this.createPopup();
@ -43,18 +47,17 @@ class PopupButton extends ClickableComponent {
}
/**
* Create popup - Override with specific functionality for component
* Create a `Popup`. - Override with specific functionality for component
*
* @return {Popup} The constructed popup
* @method createPopup
* @abstract
*/
createPopup() {}
/**
* Create the component's DOM element
* Create the `PopupButton`s DOM element.
*
* @return {Element}
* @method createEl
* The element that gets created.
*/
createEl() {
return super.createEl('div', {
@ -63,10 +66,10 @@ class PopupButton extends ClickableComponent {
}
/**
* Allow sub components to stack CSS class names
* Builds the default DOM `className`.
*
* @return {String} The constructed class name
* @method buildCSSClass
* @return {string}
* The DOM `className` for this object.
*/
buildCSSClass() {
let menuButtonClass = 'vjs-menu-button';
@ -80,7 +83,6 @@ class PopupButton extends ClickableComponent {
return `vjs-menu-button ${menuButtonClass} ${super.buildCSSClass()}`;
}
}
Component.registerComponent('PopupButton', PopupButton);

10
src/js/popup/popup.js
View File

@ -10,15 +10,15 @@ import * as Events from '../utils/events.js';
* The Popup component is used to build pop up controls.
*
* @extends Component
* @class Popup
*/
class Popup extends Component {
/**
* Add a popup item to the popup
*
* @param {Object|String} component Component or component type to add
* @method addItem
* @param {Object|string} component
* Component or component type to add
*
*/
addItem(component) {
this.addChild(component);
@ -28,10 +28,10 @@ class Popup extends Component {
}
/**
* Create the component's DOM element
* Create the `PopupButton`s DOM element.
*
* @return {Element}
* @method createEl
* The element that gets created.
*/
createEl() {
const contentElType = this.options_.contentElType || 'ul';