Merge pull request #133 from SpringRoll/release/2.4.0

Release 2.4.0

Author: 902seanryan

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0] unreleased
+
+## Added
+
+- Added `manageOwnVisibility` flag to the PausePlugin to make turning off visibility/focus management easier
 
 ## [2.3.4] 2022-06-09
 

README.md

@@ -115,6 +115,23 @@ container.openPath('game.html');
 
 `PausePlugin` sets a className of 'paused' or 'unpaused' on individual pause buttons.
 
+The `PausePlugin` also has an optional flag
+`manageOwnVisibility`. This defaults to `true` and is intended to disable the visibility management of the plugin for environements
+that handle visibility/focus themselves. For most web based contexts this flag will not be needed.
+
+```javascript
+import { PausePlugin, Container } from 'springroll-container';
+
+const container = new Container("#game", {
+  plugins: [
+    // manageOwnVisibility is set to false which means the plugin will not send pause or unpause events if the app is no longer
+    // focused or other similar states (switched tabs, etc)
+    new PausePlugin('button#pause-button', false),
+  ]
+});
+container.openPath('game.html');
+```
+
 ### Captions
 
 There are two plugins that interact with captions: `CaptionsTogglePlugin`, and `CaptionsStylePlugin`.

dist/SpringRoll-Container-umd.js

@@ -1,6 +1,6 @@
 {
   "name": "springroll-container",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "The iframe controller for interacting with SpringRoll applications",
   "main": "./dist/index.js",
   "license": "MIT",

dist/SpringRoll-Container-umd.js.map

@@ -9,11 +9,13 @@ import { Button } from '../ui-elements';
 export class PausePlugin extends ButtonPlugin {
   /**
    * Creates an instance of PausePlugin.
-   * @param {string | HTMLElement} pauseButton selector string or HTML Element for the input(s) 
+   * @param {string | HTMLElement} pauseButton selector string or HTML Element for the input(s)
+   * @param {boolean} manageOwnVisibility whether the plugin should manage container's visibility or some other source will handle it
    * @memberof PausePlugin
    */
-  constructor(pauseButton) {
+  constructor(pauseButton, manageOwnVisibility = true) {
     super('Pause-Button-plugin');
+    this._manageOwnVisibility = manageOwnVisibility;
     this._appBlurred = false;
     this._containerBlurred = false;
     this._focusTimer = null;
@@ -35,7 +37,9 @@ export class PausePlugin extends ButtonPlugin {
       this.onContainerBlur.bind(this)
     );
 
-    if ( pauseButton instanceof HTMLElement ) {
+    this.pageVisibility.enabled = this.manageOwnVisibility;
+
+    if (pauseButton instanceof HTMLElement) {
       this._pauseButton[0] = new Button({
         button: pauseButton,
         onClick: onPauseToggle,
@@ -81,10 +85,29 @@ export class PausePlugin extends ButtonPlugin {
    * @memberof PausePlugin
    * @returns {Boolean}
    */
-  get pause() { 
+  get pause() {
     return this._paused;
   }
 
+  /**
+   * updates _manageOwnVisibility and also re-enables pageVisibility
+   * @memberof PausePlugin
+   * @param {Boolean} manageOwnVisibility
+   */
+  set manageOwnVisibility(manageOwnVisibility) {
+    this._manageOwnVisibility = manageOwnVisibility;
+
+    this.pageVisibility.enabled = this._manageOwnVisibility;
+  }
+
+  /**
+ * @memberof PausePlugin
+ * @returns {Boolean}
+ */
+  get manageOwnVisibility() {
+    return this._manageOwnVisibility;
+  }
+
   /**
    * forces focus onto the iframe application window
    * @memberof PausePlugin
@@ -116,6 +139,9 @@ export class PausePlugin extends ButtonPlugin {
    * @memberof PausePlugin
    */
   manageFocus() {
+    if (!this.manageOwnVisibility) {
+      return;
+    }
     // Unfocus on the iframe
     if (this._keepFocus) {
       this.blurApp();
@@ -132,7 +158,7 @@ export class PausePlugin extends ButtonPlugin {
     // causing rapid toggling of the pause state and related issues,
     // especially in Internet Explorer
     this._focusTimer = setTimeout(
-      function() {
+      function () {
         this._focusTimer = null;
         // A manual pause cannot be overriden by focus events.
         // User must click the resume button.
@@ -215,9 +241,10 @@ export class PausePlugin extends ButtonPlugin {
    */
   init({ iframe }) {
     this.iframe = iframe;
+
     this.client.on(
       'features',
-      function(features) {
+      function (features) {
         if (features.disablePause) {
           this.pauseDisabled = true;
         }

dist/index.js

@@ -44,6 +44,54 @@ describe('PausePlugin', () => {
     expect(pp.pauseButton[0].classList.contains('unpaused')).to.be.true;
   });
 
+  describe('manageOwnVisibility', () => {
+    let disabledPlugin;
+    before(() => {
+      const button = document.createElement('button');
+      document.body.innerHTML = '';
+      button.id = 'ignore';
+      document.body.appendChild(button);
+      disabledPlugin = new PausePlugin('#ignore', false); // disable the focus management of the plugin
+      disabledPlugin.preload({ client: new Bellhop() });
+    });
+
+    it('should set manageOwnVisibility to false', () => {
+      // control
+      expect(pp.manageOwnVisibility).to.be.true;
+
+      expect(disabledPlugin.manageOwnVisibility).to.be.false;
+    });
+
+    it('should set pageVisibility.enabled to false', () => {
+      expect(disabledPlugin.pageVisibility.enabled).to.be.false;
+    });
+
+    it('manageFocus() should not change pause state', async () => {
+      expect(disabledPlugin.pause).to.be.false;
+
+      disabledPlugin._containerBlurred = true;
+      disabledPlugin._appBlurred = true;
+
+      disabledPlugin.manageFocus();
+      await sleep(150);
+      expect(disabledPlugin.pause).to.be.false;
+    });
+
+    it('setting flag to true should re-enable everything', async () => {
+      disabledPlugin.manageOwnVisibility = true;
+
+      expect(disabledPlugin.pageVisibility.enabled).to.be.true;
+      disabledPlugin._containerBlurred = true;
+      disabledPlugin._appBlurred = true;
+
+      disabledPlugin.manageFocus();
+      await sleep(150);
+      expect(disabledPlugin.pause).to.be.true;
+    });
+
+
+  });
+
   describe('manageFocus()', () => {
     it('should set pause to false if only app is blurred', async () => {
       pp.onPauseToggle(); //reset the manual pause state which was being set to true for some reason.