Skip to content

Commit

Permalink
docs(middleware): update the middleware guide with setTech and other …
Browse files Browse the repository at this point in the history 
…corrections (#4926)
  • Loading branch information
@ldayananda @gkatsev
ldayananda authored and gkatsev committed Feb 12, 2018
1 parent a1cef80 commit a434551
Showing 1 changed file with 99 additions and 35 deletions.
134 changes: 99 additions & 35 deletions docs/guides/middleware.md
View file
Expand Up @@ -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()`.

### 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`.
### setSource

### 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`.
`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`.

### 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).
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

```
+----------+ +----------+
Expand All @@ -38,28 +53,44 @@ Mediators are called on the `Player` first, run through middleware (from left to
+----------+ +----------+
```

### Termination and Mediators
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`.

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`.
### Middleware Getters

```
mediate to tech
+------------->
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).

```
+----------+ +----------+
| | | |
| +-----call{method}-----> |
| +---mediate-to-tech----> |
| Player | | Tech |
| <-------{method}-------+ |
| <--mediate-to-player---+ |
| | | |
+----------+ +----------+
```

### Termination and Mediators

<---------------+
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`.

```
+----------+ +----------+
| | | |
| +----+call{method}+----> |
| Player | | Tech |
| <------+{method}+------+ |
| | | |
+----------+ +----------+
```

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) {
Expand All @@ -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
...
},
Expand All @@ -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

Expand All @@ -93,56 +124,89 @@ 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);
```

### Terminating Mediator Methods
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`.

Mediator methods can terminate, by doing the following:
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() {
// Terminate by returning the middleware terminator
return videojs.middleware.TERMINATOR;
// Do nothing, thereby allowing play() to be called on the Tech
},
play: function(terminated, value) {
// the terminated argument should be true here.
},
...
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);
```

## setSource
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).

`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:
### Terminating Mediator Methods

Mediator methods can terminate, by doing the following:

```javascript
videojs.use('*', function(player) {
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);
```

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`.

0 comments on commit a434551

Please sign in to comment.