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(middleware): update the middleware guide with setTech and other corrections (#4926)

Browse Source
This commit is contained in:
ldayananda 2018-02-12 18:55:08 -05:00 committed by Gary Katsevman
parent a1cef809b3
commit a434551555
1 changed files with 105 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
docs/guides/middleware.md
View File

@ -5,28 +5,43 @@ Middleware is a Video.js feature that allows interaction with and modification o
## Table of Contents
* [Understanding Middleware](#understanding-middleware)
* [setSource](#setsource)
* [setTech](#setTech)
* [Middleware Setters](#middleware-setters)
* [Middleware Getters](#middleware-getters)
* [Middleware Mediators](#middleware-mediators)
* [Termination and Mediators](#termination-and-mediators)
* [Using Middleware](#using-middleware)
* [Terminating Mediator Methods](#terminating-mediator-methods)
* [setSource](#setsource)
## Understanding Middleware
Middleware are functions that return an object with methods matching those on the `Tech`. There are currently a limited set of allowed methods that will be understood by middleware. These are: `buffered`, `currentTime`, `setCurrentTime`, `duration`, `seekable`, `played`, `play`, `pause` and `paused`.
Middleware are functions that return an object, a class instance, a prototype, etc, scoped to the Player with methods matching those on the `Tech`. There are currently a limited set of allowed methods that will be understood by middleware. These are: `buffered`, `currentTime`, `setCurrentTime`, `duration`, `seekable`, `played`, `play`, `pause` and `paused`. These allowed methods are split into three categories: [getters](#middleware-getters), [setters](#middleware-setters), and [mediators](#middleware-mediators).
These allowed methods are split into three categories: `getters`, `setters`, and `mediators`.
There are a few special methods that affect middleware: `setSource` and `setTech`. These are called internally by Video.js when you call `player.src()`.
### setSource
`setSource` is a required method for all middleware and must be included in the returned object. This method will setup the routing between a specific source and middleware and eventually sets the source on the `Tech`.
If your middleware is not manipulating, redirecting or rejecting the source, you can pass along the source by doing the following:
```javascript
videojs.use('*', function(player) {
return {
setSource: function(srcObj, next) {
// pass null as the first argument to indicate that the source is not rejected
next(null, srcObj);
}
};
});
```
### setTech
`setTech` is a method that associates middleware with a specific `Tech` once it has been selected by the `Player`, after middleware make a decision on which source to set. This does not need to be included in your middleware.
### Middleware Setters
Setters will be called on the `Player` first and run through middleware (from left to right) before calling the method, with its arguments, on the `Tech`.
### Middleware Getters
Getters are called on the `Tech` first and are run though middleware (from right to left) before returning the result to the `Player`.
### Middleware Mediators
Mediators are called on the `Player` first, run through middleware (from left to right), then called on the `Tech`. The result is returned to the `Player` unchanged, while calling the middleware from right to left. For more information on mediators, check out the [mediator section](#termination-and-mediators).
```
+----------+ +----------+
@ -38,28 +53,44 @@ Mediators are called on the `Player` first, run through middleware (from left to
+----------+ +----------+
```
Setters will be called on the `Player` first and run through middleware in the order they were registered in (from left to right in the diagram) before calling the method, with its arguments, on the `Tech`.
### Middleware Getters
Getters are called on the `Tech` first and are run though middleware in reverse of the order they were registered in (from right to left in the diagram) before returning the result to the `Player`.
### Middleware Mediators
Mediators are methods that not only change the state of the `Tech`, but also return some value back to the `Player`. Currently, these are `play` and `pause`.
Mediators are called on the `Player` first, run through middleware in the order they were registered (from left to right in the below diagram), then called on the `Tech`. The result is returned to the `Player` unchanged, while calling the middleware in the reverse order of how they were registered (from right to left in the diagram.) For more information on mediators, check out the [mediator section](#termination-and-mediators).
```
+----------+ +----------+
| | | |
| +---mediate-to-tech----> |
| Player | | Tech |
| <--mediate-to-player---+ |
| | | |
+----------+ +----------+
```
### Termination and Mediators
Mediators are the third category of allowed methods. These are methods that not only change the state of the Tech, but also return some value back to the Player. Currently, these are `play` and `pause`.
Mediators make a round trip: starting at the `Player`, mediating to the `Tech` and returning the result to the `Player` again. A `call{method}` method must be supplied by the middleware which is used when mediating to the `Tech`. On the way back to the `Player`, the `{method}` will be called instead, with 2 arguments: `terminated`, a Boolean indicating whether a middleware terminated during the mediation to the tech portion, and `value`, which is the value returned from the `Tech`.
```
mediate to tech
+------------->
+----------+ +----------+
| | | |
| +-----call{method}-----> |
| +----+call{method}+----> |
| Player | | Tech |
| <-------{method}-------+ |
| <------+{method}+------+ |
| | | |
+----------+ +----------+
<---------------+
mediate to player
```
Mediators make a round trip: starting at the `Player`, mediating to the `Tech` and returning the result to the `Player` again. A `call{method}` method must be supplied by the middleware which is used when mediating to the `Tech`. On the way back to the `Player`, the `{method}` will be called instead, with 2 arguments: `terminated`, a Boolean indicating whether a middleware terminated during the mediation to the tech portion, and `value`, which is the value returned from the `Tech`. A barebones example of a middleware with Mediator methods is:
A skeleton of a middleware with Mediator methods is given below:
```
var myMiddleware = function(player) {
@ -68,7 +99,7 @@ var myMiddleware = function(player) {
// mediating to the Tech
...
},
pause: function(terminated, value) {
play: function(terminated, value) {
// mediating back to the Player
...
},
@ -77,7 +108,7 @@ var myMiddleware = function(player) {
};
```
Middleware termination occurs when a middleware method decides to stop mediating to the Tech. We'll see more examples of this in the [next section](#terminating-mediator-methods).
Middleware termination occurs when a middleware method decides to stop mediating to the `Tech`. We'll see more examples of this in the [next section](#terminating-mediator-methods).
## Using Middleware
@ -93,24 +124,64 @@ You can also register a middleware on all sources by registering it on `*`.
videojs.use('*', myMiddleware);
```
Your middleware should be a function that takes a player as an argument and returns an object with methods on it like below:
Your middleware should be a function that is scoped to a player and returns an object, class instance, etc, with methods on it that match those on the `Tech`. An example of a middleware that returns an object is below:
```javascript
var myMiddleware = function(player) {
return {
setSource: function(srcObj, next) {
// pass null as the first argument to indicate that the source is not rejected
next(null, srcObj);
},
currentTime: function(ct) {
return ct / 2;
},
setCurrentTime: function(time) {
return time * 2;
},
...
}
};
};
videojs.use('*', myMiddleware);
```
This middleware gives the appearance of the video source playing at double its speed, by halving the time we _get_ from the `Tech`, and doubling the time we _set_ on the `Tech`.
An example of a middleware that uses Mediator methods is below:
```javascript
var myMiddleware = function(player) {
return {
setSource: function(srcObj, next) {
// pass null as the first argument to indicate that the source is not rejected
next(null, srcObj);
},
callPlay: function() {
// Do nothing, thereby allowing play() to be called on the Tech
},
play: function(terminated, value) {
if (terminated) {
console.log('The play was middleware terminated.');
// the value is a play promise
} else if (value && value.then) {
value
.then(function() {
console.log('The play succeeded!')
})
.catch(function (err) {
console.log('The play was rejected', err);
});
}
}
};
};
videojs.use('*', myMiddleware);
```
This middleware allows the call to `play()` to go through to the `Tech`, and checks in `play` whether the play succeeded or not. A more detailed example can be found in our [sandbox](https://github.com/videojs/video.js/blob/master/sandbox/middleware-play.html.example).
### Terminating Mediator Methods
Mediator methods can terminate, by doing the following:
@ -118,31 +189,24 @@ Mediator methods can terminate, by doing the following:
```javascript
var myMiddleware = function(player) {
return {
setSource: function(srcObj, next) {
// pass null as the first argument to indicate that the source is not rejected
next(null, srcObj);
},
callPlay: function() {
// Terminate by returning the middleware terminator
return videojs.middleware.TERMINATOR;
},
play: function(terminated, value) {
// the terminated argument should be true here.
},
...
if (terminated) {
console.log('The play was middleware terminated.');
}
}
};
};
videojs.use('*', myMiddleware);
```
## setSource
`setSource` is a required method for all middleware and must be included in the returned object. If your middlware is not manipulating or rejecting the source, you can pass along the source by doing the following:
```javascript
videojs.use('*', function(player) {
return {
setSource: function(srcObj, next) {
// pass null as the first argument to indicate that the source is not rejected
next(null, srcObj);
}
};
});
```
This middleware always terminates calls to `play()` by returning the `TERMINATOR` in `callPlay`. In `play` we are able to see that the call to `play()` was terminated and was never called on the `Tech`.