feat: make overlays mutable (#223)

* implement initial add/remove fns

* add tests for add/remove fns

* implement remove functionality with tests

* update 'add' fn test

* update docs to include add/remove fns and remove docs:toc stage

* update index.html example

* update readme toc

* fix refactored docs

* refactor overlays property to be a getter fn

* refactor 'getOverlay' to 'get'

* update readme toc

* change example usage to use const instead of var

---------

Co-authored-by: uomar <[email protected]>

Author: usmanonazim

README.md

@@ -18,6 +18,11 @@ Maintenance Status: Stable
 
 - [Getting Started](#getting-started)
 - [Documentation](#documentation)
+  - [API](#api)
+    - [`player.overlay()`](#playeroverlay)
+    - [`overlay.get()`](#overlayget)
+    - [`overlay.add(object|array)`](#overlayaddobjectarray)
+    - [`overlay.remove(object)`](#overlayremoveobject)
   - [Plugin Options](#plugin-options)
     - [`align`](#align)
     - [`showBackground`](#showbackground)
@@ -45,6 +50,52 @@ There's also a [working example](https://github.com/brightcove/videojs-overlay/b
 
 ## Documentation
 
+### API
+#### `player.overlay()`
+This is the main interface and the way to initialize this plugin. It takes [an options object as input](#plugin-options).
+
+#### `overlay.get()`
+
+Returns an array of all the overlays set up for the current video.
+
+#### `overlay.add(Object|Array)`
+
+Adds one or more overlays to the current list of overlays without replacing the current list of overlays.
+Returns a reference to the added overlays.
+
+```js
+const overlay = player.overlay({
+  content: 'Default overlay content',
+  debug: true,
+  overlays: [{
+    content: 'The video is playing!',
+    start: 'play',
+    end: 'pause'
+  }]
+});
+const addedOverlays = overlay.add({content: "this is a new one", start: "play", end: "pause"});
+```
+
+
+#### `overlay.remove(Object)`
+
+Removes an individual overlay from the list of overlays. Calling this method with an invalid overlay object removes nothing from the list.
+
+```js
+const overlay = player.overlay({
+  content: 'Default overlay content',
+  debug: true,
+  overlays: [{
+    content: 'The video is playing!',
+    start: 'play',
+    end: 'pause'
+  }]
+});
+const overlayToRemove = overlay.get()[0];
+overlay.remove(overlayToRemove);
+```
+
+
 ### Plugin Options
 
 You may pass in an options object to the plugin upon initialization. This

index.html

@@ -18,14 +18,15 @@
   <script src="dist/videojs-overlay.js"></script>
   <script>
     (function(window, videojs) {
-      var player = window.player = videojs('videojs-overlay-player');
-      player.overlay({
+      const player = window.player = videojs('videojs-overlay-player');
+      const overlay = player.overlay({
         content: 'Default overlay content',
         debug: true,
         overlays: [{
           content: 'The video is playing!',
           start: 'play',
-          end: 'pause'
+          end: 'pause',
+          align: 'bottom-right'
         }, {
           start: 0,
           end: 15,
@@ -43,6 +44,7 @@
           end: 'pause'
         }]
       });
+      overlay.add({content: "this is a new one", start: "play", end: "pause"});
     }(window, window.videojs));
   </script>
 </body>

package.json

@@ -89,7 +89,6 @@
       "git add"
     ],
     "README.md": [
-      "npm run docs:toc",
       "git add"
     ]
   },

src/plugin.js

@@ -36,8 +36,8 @@ const isNumber = n => typeof n === 'number' && n === n;
 /**
  * Whether a value is a string with no whitespace.
  *
- * @param  {String} s
- * @return {Boolean}
+ * @param  {string} s
+ * @return {boolean}
  */
 const hasNoWhitespace = s => typeof s === 'string' && (/^\S+$/).test(s);
 
@@ -116,6 +116,7 @@ class Overlay extends Component {
 
   /**
    * Logs debug errors
+   *
    * @param  {...[type]} args [description]
    * @return {[type]}         [description]
    */
@@ -160,11 +161,11 @@ class Overlay extends Component {
   /**
    * Determine whether or not the overlay should hide.
    *
-   * @param  {Number} time
+   * @param  {number} time
    *         The current time reported by the player.
-   * @param  {String} type
+   * @param  {string} type
    *         An event type.
-   * @return {Boolean}
+   * @return {boolean}
    */
   shouldHide_(time, type) {
     const end = this.options_.end;
@@ -195,11 +196,11 @@ class Overlay extends Component {
   /**
    * Determine whether or not the overlay should show.
    *
-   * @param  {Number} time
+   * @param  {number} time
    *         The current time reported by the player.
-   * @param  {String} type
+   * @param  {string} type
    *         An event type.
-   * @return {Boolean}
+   * @return {boolean}
    */
   shouldShow_(time, type) {
     const start = this.options_.start;
@@ -301,6 +302,7 @@ videojs.registerComponent('Overlay', Overlay);
  * @param    {Object} [options={}]
  */
 const plugin = function(options) {
+  const player = this;
   const settings = videojs.mergeOptions(defaults, options);
 
   // De-initialize the plugin if it already has an array of overlays.
@@ -320,37 +322,98 @@ const plugin = function(options) {
   // because it doesn't make sense to pass it to each Overlay component.
   delete settings.overlays;
 
-  this.overlays_ = overlays.map(o => {
-    const mergeOptions = videojs.mergeOptions(settings, o);
-    const attachToControlBar = typeof mergeOptions.attachToControlBar === 'string' || mergeOptions.attachToControlBar === true;
+  const mapOverlays = (items) => {
+    return items.map(o => {
+      const mergeOptions = videojs.mergeOptions(settings, o);
+      const attachToControlBar = typeof mergeOptions.attachToControlBar === 'string' || mergeOptions.attachToControlBar === true;
 
-    if (!this.controls() || !this.controlBar) {
-      return this.addChild('overlay', mergeOptions);
-    }
+      if (!this.controls() || !this.controlBar) {
+        return this.addChild('overlay', mergeOptions);
+      }
 
-    if (attachToControlBar && mergeOptions.align.indexOf('bottom') !== -1) {
-      let referenceChild = this.controlBar.children()[0];
+      if (attachToControlBar && mergeOptions.align.indexOf('bottom') !== -1) {
+        let referenceChild = this.controlBar.children()[0];
 
-      if (this.controlBar.getChild(mergeOptions.attachToControlBar) !== undefined) {
-        referenceChild = this.controlBar.getChild(mergeOptions.attachToControlBar);
-      }
+        if (this.controlBar.getChild(mergeOptions.attachToControlBar) !== undefined) {
+          referenceChild = this.controlBar.getChild(mergeOptions.attachToControlBar);
+        }
 
-      if (referenceChild) {
-        const referenceChildIndex = this.controlBar.children().indexOf(referenceChild);
-        const controlBarChild = this.controlBar.addChild('overlay', mergeOptions, referenceChildIndex);
+        if (referenceChild) {
+          const referenceChildIndex = this.controlBar.children().indexOf(referenceChild);
+          const controlBarChild = this.controlBar.addChild('overlay', mergeOptions, referenceChildIndex);
 
-        return controlBarChild;
+          return controlBarChild;
+        }
       }
+
+      const playerChild = this.addChild('overlay', mergeOptions);
+
+      this.el().insertBefore(
+        playerChild.el(),
+        this.controlBar.el()
+      );
+
+      return playerChild;
+    });
+  };
+
+  this.overlays_ = mapOverlays(overlays);
+
+  /**
+   * Adds one or more items to the existing list of overlays.
+   *
+   * @param {Object|Array} item
+   *        An item (or an array of items) to be added as overlay/s
+   *
+   * @return {Array[Overlay]}
+   *         The array of overlay objects that were added
+   */
+  function add(item) {
+    if (!Array.isArray(item)) {
+      item = [item];
     }
 
-    const playerChild = this.addChild('overlay', mergeOptions);
+    const addedOverlays = mapOverlays(item);
+
+    player.overlays_ = player.overlays_.concat(addedOverlays);
+
+    return addedOverlays;
+  }
+
+  /**
+   *
+   * @param {Overlay} item
+   *        An item to be removed from the array of overlays
+   *
+   * @throws {Error}
+   *        Item to remove must be present in the array of overlays
+   *
+   */
+  function remove(item) {
+    const index = player.overlays_.indexOf(item);
+
+    if (index !== -1) {
+      item.el().parentNode.removeChild(item.el());
+      player.overlays_.splice(index, 1);
+    } else {
+      player.log.warn('overlay does not exist and cannot be removed');
+    }
+  }
+
+  /**
+   * Gets the array of overlays used for the current video
+   *
+   * @return The array of overlay objects currently used by the plugin
+   */
+  function get() {
+    return player.overlays_;
+  }
 
-    this.el().insertBefore(
-      playerChild.el(),
-      this.controlBar.el()
-    );
-    return playerChild;
-  });
+  return {
+    add,
+    remove,
+    get
+  };
 };
 
 plugin.VERSION = VERSION;