web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2024-12-16 11:37:29 +02:00
Code Releases Activity
42fbd4c799
video.js/docs/api/vjs.Html5.md
heff aac97d287a Release 4.11.4
2015-01-23 10:50:22 -08:00

23 KiB
Raw Blame History

vjs.Html5

EXTENDS: vjs.MediaTechController
DEFINED IN: src/js/media/html5.js#L12

HTML5 Media Controller - Wrapper for HTML5 Media API

INDEX

METHODS

addChild( child, [options] )

Adds a child component inside this component

myComponent.el();
// -> <div class='my-component'></div>
myComonent.children();
// [empty array]

var myButton = myComponent.addChild('MyButton');
// -> <div class='my-component'><div class="my-button">myButton<div></div>
// -> myButton === myComonent.children()[0];

Pass in options for child constructors and options for children of the child

var myButton = myComponent.addChild('MyButton', {
  text: 'Press Me',
  children: {
    buttonChildExample: {
      buttonChildOption: true
    }
  }
});
PARAMETERS:
  • child String|vjs.Component The class name or instance of a child to add
  • options Object (OPTIONAL) Options, including options to be passed to children of the child.
RETURNS:
  • vjs.Component The child component (created by this process if a string was used)

inherited from: src/js/component.js#L362

addClass( classToAdd )

Add a CSS class name to the component's element

PARAMETERS:
  • classToAdd String Classname to add
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L826

buildCSSClass()

Allows sub components to stack CSS class names

RETURNS:
  • String The constructed class name

inherited from: src/js/component.js#L536

canControlPlaybackRate() STATIC

Check if playbackRate is supported in this browser/device.

RETURNS:
  • [type] [description]

defined in: src/js/media/html5.js#L380

canControlVolume() STATIC

Check if the volume can be changed in this browser/device. Volume cannot be changed in a lot of mobile devices. Specifically, it can't be changed from 1 on iOS.

RETURNS:
  • Boolean

defined in: src/js/media/html5.js#L370

children()

Get an array of all child components

var kids = myComponent.children();
RETURNS:
  • Array The children

inherited from: src/js/component.js#L296

clearInterval( intervalId )

Clears an interval and removes the associated dispose listener

PARAMETERS:
  • intervalId Number The id of the interval to clear
RETURNS:
  • Number Returns the interval ID

inherited from: src/js/component.js#L1219

clearTimeout( timeoutId )

Clears a timeout and removes the associated dispose listener

PARAMETERS:
  • timeoutId Number The id of the timeout to clear
RETURNS:
  • Number Returns the timeout ID

inherited from: src/js/component.js#L1181

contentEl()

Return the component's DOM element for embedding content. Will either be el_ or a new element defined in createEl.

RETURNS:
  • Element

inherited from: src/js/component.js#L239

createEl( [tagName], [attributes] )

Create the component's DOM element

PARAMETERS:
  • tagName String (OPTIONAL) Element's node type. e.g. 'div'
  • attributes Object (OPTIONAL) An object of element attributes that should be set on the element
RETURNS:
  • Element

inherited from: src/js/component.js#L200

dimensions( width, height )

Set both width and height at the same time

PARAMETERS:
  • width Number|String
  • height Number|String
RETURNS:
  • vjs.Component The component

inherited from: src/js/component.js#L938

dispose()

Dispose of the component and all child components

inherited from: src/js/component.js#L84

el()

Get the component's DOM element

var domEl = myComponent.el();
RETURNS:
  • Element

inherited from: src/js/component.js#L220

enableTouchActivity()

Report user touch activity when touch events occur

User activity is used to determine when controls should show/hide. It's relatively simple when it comes to mouse events, because any mouse event should show the controls. So we capture mouse events that bubble up to the player and report activity when that happens.

With touch events it isn't as easy. We can't rely on touch events at the player level, because a tap (touchstart + touchend) on the video itself on mobile devices is meant to turn controls off (and on). User activity is checked asynchronously, so what could happen is a tap event on the video turns the controls off, then the touchend event bubbles up to the player, which if it reported user activity, would turn the controls right back on. (We also don't want to completely block touch events from bubbling up)

Also a touchmove, touch+hold, and anything other than a tap is not supposed to turn the controls back on on a mobile device.

Here we're setting the default component behavior to report user activity whenever touch events happen, and this can be turned off by components that want touch events to act differently.

inherited from: src/js/component.js#L1120

getChild( name )

Returns a child component with the provided name

PARAMETERS:
  • name
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L330

getChildById( id )

Returns a child component with the provided ID

PARAMETERS:
  • id
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L313

hasClass( classToCheck )

Check if a component's element has a CSS class name

PARAMETERS:
  • classToCheck String Classname to check
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L816

height( [num], [skipListeners] )

Get or set the height of the component (CSS values)

Setting the video tag dimension values only works with values in pixels. Percent values will not work. Some percents can be used, but width()/height() will return the number + %, not the actual computed width/height.

PARAMETERS:
  • num Number|String (OPTIONAL) New component height
  • skipListeners Boolean (OPTIONAL) Skip the resize event trigger
RETURNS:
  • vjs.Component This component, when setting the height
  • Number|String The height, when getting

inherited from: src/js/component.js#L927

hide()

Hide the component element if currently showing

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L857

id()

Get the component's ID

var id = myComponent.id();
RETURNS:
  • String

inherited from: src/js/component.js#L258

init( player, options, ready )

PARAMETERS:
  • player
  • options
  • ready

defined in: src/js/media/html5.js#L14

initChildren()

Add and initialize default child components from options

// when an instance of MyComponent is created, all children in options
// will be added to the instance by their name strings and options
MyComponent.prototype.options_.children = {
  myChildComponent: {
    myChildOption: true
  }
}

// Or when creating the component
var myComp = new MyComponent(player, {
  children: {
    myChildComponent: {
      myChildOption: true
    }
  }
});

The children option can also be an Array of child names or child options objects (that also include a 'name' key).

var myComp = new MyComponent(player, {
  children: [
    'button',
    {
      name: 'button',
      someOtherOption: true
    }
  ]
});

inherited from: src/js/component.js#L481

initControlsListeners()

Set up click and touch listeners for the playback element On desktops, a click on the video itself will toggle playback, on a mobile device a click on the video toggles controls. (toggling controls is done by toggling the user state between active and inactive)

A tap can signal that a user has become active, or has become inactive e.g. a quick tap on an iPhone movie should reveal the controls. Another quick tap should hide them again (signaling the user is in an inactive viewing state)

In addition to this, we still want the user to be considered inactive after a few seconds of inactivity.

Note: the only part of iOS interaction we can't mimic with this setup is a touch and hold on the video element counting as activity in order to keep the controls showing, but that shouldn't be an issue. A touch and hold on any controls will still keep the user active

inherited from: src/js/media/media.js#L55

isSupported() STATIC

Check if HTML5 video is supported by this browser/device

RETURNS:
  • Boolean

defined in: src/js/media/html5.js#L290

name()

Get the component's name. The name is often used to reference the component.

var name = myComponent.name();
RETURNS:
  • String

inherited from: src/js/component.js#L277

off( [first], [second], [third] )

Remove an event listener from this component's element

myComponent.off('eventType', myFunc);

If myFunc is excluded, ALL listeners for the event type will be removed. If eventType is excluded, ALL listeners will be removed from the component.

Alternatively you can use off to remove listeners that were added to other elements or components using myComponent.on(otherComponent.... In this case both the event type and listener function are REQUIRED.

myComponent.off(otherElement, 'eventType', myFunc);
myComponent.off(otherComponent, 'eventType', myFunc);
PARAMETERS:
  • first String|vjs.Component (OPTIONAL) The event type or other component
  • second Function|String (OPTIONAL) The listener function or event type
  • third Function (OPTIONAL) The listener for other component
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L646

on( first, second, third )

Add an event listener to this component's element

var myFunc = function(){
  var myComponent = this;
  // Do something when the event is fired
};

myComponent.on('eventType', myFunc);

The context of myFunc will be myComponent unless previously bound.

Alternatively, you can add a listener to another element or component.

myComponent.on(otherElement, 'eventName', myFunc);
myComponent.on(otherComponent, 'eventName', myFunc);

The benefit of using this over vjs.on(otherElement, 'eventName', myFunc) and otherComponent.on('eventName', myFunc) is that this way the listeners will be automatically cleaned up when either component is disposed. It will also bind myComponent as the context of myFunc.

NOTE: When using this on elements in the page other than window and document (both permanent), if you remove the element from the DOM you need to call vjs.trigger(el, 'dispose') on it to clean up references to it and allow the browser to garbage collect it.

PARAMETERS:
  • first String|vjs.Component The event type or other component
  • second Function|String The event handler or event type
  • third Function The event handler
RETURNS:
  • vjs.Component self

inherited from: src/js/component.js#L577

onClick( event )

Handle a click on the media element. By default will play/pause the media.

PARAMETERS:
  • event

inherited from: src/js/media/media.js#L139

onTap()

Handle a tap on the media element. By default it will toggle the user activity state, which hides and shows the controls.

inherited from: src/js/media/media.js#L159

one( first, second, [third] )

Add an event listener to be triggered only once and then removed

myComponent.one('eventName', myFunc);

Alternatively you can add a listener to another element or component that will be triggered only once.

myComponent.one(otherElement, 'eventName', myFunc);
myComponent.one(otherComponent, 'eventName', myFunc);
PARAMETERS:
  • first String|vjs.Component The event type or other component
  • second Function|String The listener function or event type
  • third Function (OPTIONAL) The listener function for other component
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L691

options( obj )

Deep merge of options objects

Whenever a property is an object on both options objects the two properties will be merged using vjs.obj.deepMerge.

This is used for merging options for child components. We want it to be easy to override individual options on a child component without having to rewrite all the other default options.

Parent.prototype.options_ = {
  children: {
    'childOne': { 'foo': 'bar', 'asdf': 'fdsa' },
    'childTwo': {},
    'childThree': {}
  }
}
newOptions = {
  children: {
    'childOne': { 'foo': 'baz', 'abc': '123' }
    'childTwo': null,
    'childFour': {}
  }
}

this.options(newOptions);

RESULT

{
  children: {
    'childOne': { 'foo': 'baz', 'asdf': 'fdsa', 'abc': '123' },
    'childTwo': null, // Disabled. Won't be initialized.
    'childThree': {},
    'childFour': {}
  }
}
PARAMETERS:
  • obj Object Object of new option values
RETURNS:
  • Object A NEW object of this.options_ and obj merged

inherited from: src/js/component.js#L179

player()

Return the component's player

RETURNS:
  • vjs.Player

inherited from: src/js/component.js#L126

ready( fn )

Bind a listener to the component's ready state

Different from event listeners in that if the ready event has already happened it will trigger the function immediately.

PARAMETERS:
  • fn Function Ready listener
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L769

removeChild( component )

Remove a child component from this component's list of children, and the child component's element from this component's element

PARAMETERS:
  • component vjs.Component Component to remove

inherited from: src/js/component.js#L420

removeClass( classToRemove )

Remove a CSS class name from the component's element

PARAMETERS:
  • classToRemove String Classname to remove
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L837

removeControlsListeners()

Remove the listeners used for click and tap controls. This is needed for toggling to controls disabled, where a tap/touch should do nothing.

inherited from: src/js/media/media.js#L123

setInterval( fn, interval )

Creates an interval and sets up disposal automatically.

PARAMETERS:
  • fn Function The function to run every N seconds.
  • interval Number Number of ms to delay before executing specified function.
RETURNS:
  • Number Returns the interval ID

inherited from: src/js/component.js#L1198

setPoster()

Provide a default setPoster method for techs

Poster support for techs should be optional, so we don't want techs to break if they don't have a way to set a poster.

inherited from: src/js/media/media.js#L260

setTimeout( fn, timeout )

Creates timeout and sets up disposal automatically.

PARAMETERS:
  • fn Function The function to run after the timeout.
  • timeout Number Number of ms to delay before executing specified function.
RETURNS:
  • Number Returns the timeout ID

inherited from: src/js/component.js#L1158

show()

Show the component element if hidden

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L847

trigger( event )

Trigger an event on an element

myComponent.trigger('eventName');
myComponent.trigger({'type':'eventName'});
PARAMETERS:
  • event Event|Object|String A string (the type) or an event object with a type attribute
RETURNS:
  • vjs.Component self

inherited from: src/js/component.js#L724

triggerReady()

Trigger the ready listeners

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L788

width( [num], skipListeners )

Set or get the width of the component (CSS values)

Setting the video tag dimension values only works with values in pixels. Percent values will not work. Some percents can be used, but width()/height() will return the number + %, not the actual computed width/height.

PARAMETERS:
  • num Number|String (OPTIONAL) Optional width number
  • skipListeners Boolean Skip the 'resize' event trigger
RETURNS:
  • vjs.Component This component, when setting the width
  • Number|String The width, when getting

inherited from: src/js/component.js#L910

EVENTS

resize EVENT

Fired when the width and/or height of the component changes

inherited from: src/js/component.js#L1020

UNDEFINED

nativeSourceHandler STATIC

The default native source handler. This simply passes the source to the video element. Nothing fancy.

PARAMETERS:
  • source Object The source object
  • tech vjs.Html5 The instance of the HTML5 tech

defined in: src/js/media/html5.js#L310