docs(middleware): update the middleware guide with setTech and other …

…corrections (#4926)

docs/guides/middleware.md

@@ -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
 
 ```
 +----------+                      +----------+
@@ -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) {
@@ -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,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`.