1
0
mirror of https://github.com/videojs/video.js.git synced 2024-12-12 11:15:04 +02:00
video.js/docs/guides/hooks.md
Brandon Casey 77357b1cd2 feat: implement player lifecycle hooks and trigger beforesetup/setup hooks (#3639)
Allows you to hook into `beforesetup` and `setup` hooks for all players that are created by videojs.
2016-11-04 14:25:32 -04:00

121 lines
3.9 KiB
Markdown

# Hooks
Hooks exist so that users can "hook" on to certain video.js player lifecycle
## Current Hooks
Currently, the following hooks are avialable:
### beforesetup
`beforesetup` is called just before the player is created. This allows:
* modification of the options passed to the video.js function (`videojs('some-id, options)`)
* modification of the dom video element that will be used for the player
`beforesetup` hook functions should:
* take two arguments
1. videoEl: dom video element that video.js is going to use to create a player
2. options: options that video.js was intialized with and will later pass to the player during creation
* return options that will merge and override options that video.js with intialized with
Example: adding beforesetup hook
```js
var beforeSetup = function(videoEl, options) {
// videoEl.id will be some-id here, since that is what video.js
// was created with
videoEl.className += ' some-super-class';
// autoplay will be true here, since we passed in as such
(options.autoplay) {
options.autoplay = false
}
// options that are returned here will be merged with old options
// in this example options will now be
// {autoplay: false, controls: true}
return options;
};
videojs.hook('beforesetup', beforeSetup);
videojs('some-id', {autoplay: true, controls: true});
```
### setup
`setup` is called just after the player is created. This allows:
* plugin or custom functionalify to intialize on the player
* changes to the player object itself
`setup` hook functions:
* Take one argument
* player: the player that video.js created
* Don't have to return anything
Example: adding setup hook
```js
var setup = function(player) {
// initialize the foo plugin
player.foo();
};
var foo = function() {};
videojs.plugin('foo', foo);
videojs.hook('setup', setup);
var player = videojs('some-id', {autoplay: true, controls: true});
```
## Usage
### Adding
In order to use hooks you must first include video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
Example: adding hooks
```js
videojs.hook('beforesetup', function(videoEl, options) {
// videoEl will be the element with id=vid1
// options will contain {autoplay: false}
});
videojs.hook('setup', function(player) {
// player will be the same player that is defined below
// as `var player`
});
var player = videojs('vid1', {autoplay: false});
```
After adding your hooks they will automatically be run at the correct time in the video.js lifecycle.
### Getting
To access the array of hooks that currently exists and will be run on the video.js object you can use the `videojs.hooks` function.
Example: getting all hooks attached to video.js
```js
var beforeSetupHooks = videojs.hooks('beforesetup');
var setupHooks = videojs.hooks('setup');
```
### Removing
To stop hooks from being executed during the video.js lifecycle you will remove them using `videojs.removeHook`.
Example: remove a hook that was defined by you
```js
var beforeSetup = function(videoEl, options) {};
// add the hook
videojs.hook('beforesetup', beforeSetup);
// remove that same hook
videojs.removeHook('beforesetup', beforeSetup);
```
You can also use `videojs.hooks` in conjunction with `videojs.removeHook` but it may have unexpected results if used during an asynchronous callbacks as other plugins/functionality may have added hooks.
Example: using `videojs.hooks` and `videojs.removeHook` to remove a hook
```js
// add the hook
videojs.hook('setup', function(videoEl, options) {});
var setupHooks = videojs.hooks('setup');
// remove the hook you just added
videojs.removeHook('setup', setupHooks[setupHooks.length - 1]);
```