Skip to content

Latest commit

 

History

History
549 lines (397 loc) · 14.5 KB

vjs.Component.md

File metadata and controls

549 lines (397 loc) · 14.5 KB
Raw

vjs.Component

EXTENDS: vjs.CoreObject
DEFINED IN: src/js/component.js#L35

Base UI Component class

Components are embeddable UI objects that are represented by both a javascript object and an element in the DOM. They can be children of other components, and can have many children themselves.

// adding a button to the player
var button = player.addChild('button');
button.el(); // -> button element

<div class="video-js">
  <div class="vjs-button">Button</div>
</div>

Components are also event emitters.

button.on('click', function(){
  console.log('Button Clicked!');
});

button.trigger('customevent');

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)

defined in: src/js/component.js#L347

addClass( classToAdd )

Add a CSS class name to the component's element

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

defined in: src/js/component.js#L632

buildCSSClass()

Allows sub components to stack CSS class names

RETURNS:
  • String The constructed class name

defined in: src/js/component.js#L475

children()

Get an array of all child components

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

defined in: src/js/component.js#L281

contentEl()

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

RETURNS:
  • Element

defined in: src/js/component.js#L224

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

defined in: src/js/component.js#L194

dimensions( width, height )

Set both width and height at the same time

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

defined in: src/js/component.js#L744

dispose()

Dispose of the component and all child components

defined in: src/js/component.js#L78

el()

Get the component's DOM element

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

defined in: src/js/component.js#L205

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.

defined in: src/js/component.js#L897

getChild( name )

Returns a child component with the provided name

PARAMETERS:
  • name
RETURNS:
  • vjs.Component

defined in: src/js/component.js#L315

getChildById( id )

Returns a child component with the provided ID

PARAMETERS:
  • id
RETURNS:
  • vjs.Component

defined in: src/js/component.js#L298

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

defined in: src/js/component.js#L733

hide()

Hide the component element if currently showing

RETURNS:
  • vjs.Component

defined in: src/js/component.js#L663

id()

Get the component's ID

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

defined in: src/js/component.js#L243

init( player, options, ready )

the constructor function for the class

PARAMETERS:
  • player
  • options
  • ready

defined in: src/js/component.js#L41

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
  }
}

defined in: src/js/component.js#L443

name()

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

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

defined in: src/js/component.js#L262

off( [type], [fn] )

Remove an event listener from the component's element

myComponent.off("eventName", myFunc);
PARAMETERS:
  • type String (OPTIONAL) Event type. Without type it will remove all listeners.
  • fn Function (OPTIONAL) Event listener. Without fn it will remove all listeners for a type.
RETURNS:
  • vjs.Component

defined in: src/js/component.js#L514

on( type, fn )

Add an event listener to this component's element

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

myPlayer.on("eventName", myFunc);

The context will be the component.

PARAMETERS:
  • type String The event type e.g. 'click'
  • fn Function The event listener
RETURNS:
  • vjs.Component self

defined in: src/js/component.js#L500

one( type, fn )

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

PARAMETERS:
  • type String Event type
  • fn Function Event listener
RETURNS:
  • vjs.Component

defined in: src/js/component.js#L526

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

defined in: src/js/component.js#L173

player()

Return the component's player

RETURNS:
  • vjs.Player

defined in: src/js/component.js#L120

ready( fn )

Bind a listener to the component's ready state

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

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

defined in: src/js/component.js#L585

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

defined in: src/js/component.js#L405

removeClass( classToRemove )

Remove a CSS class name from the component's element

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

defined in: src/js/component.js#L643

show()

Show the component element if hidden

RETURNS:
  • vjs.Component

defined in: src/js/component.js#L653

trigger( type, event )

Trigger an event on an element

myComponent.trigger('eventName');
PARAMETERS:
  • type String The event type to trigger, e.g. 'click'
  • event Event|Object The event object to be passed to the listener
RETURNS:
  • vjs.Component self

defined in: src/js/component.js#L540

triggerReady()

Trigger the ready listeners

RETURNS:
  • vjs.Component

defined in: src/js/component.js#L604

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

defined in: src/js/component.js#L716

EVENTS

resize EVENT

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

defined in: src/js/component.js#L823