Merge pull request #69 from SpringRoll/release/2.0.2

Release/2.0.2

Author: chipbell4

README.md

@@ -73,11 +73,13 @@ container.openPath('path/to/game.html');
 ```
 
 ## Plugins
+This section provides instructions on how to use the built-in plugins for SpringRoll Container. For writing or updating older plugins, see the [Plugin Authoring Guide](https://github.com/SpringRoll/SpringRollContainer/tree/main/src/plugins).
 
 The Container has several built-in plugins that allow the user to control various aspects of a game/application.
 These are initialized with either a query selector string (similar to what you would pass to [document.querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector))
 or an `HTMLElement`.
 
+
 Plugins in the SpringRollContainer correspond to a matching [feature in SpringRoll Core](https://github.com/SpringRoll/SpringRoll/tree/develop/src#features).
 If the container has a plugin enabled corresponding to a feature that the game doesn't contain, the container will automatically _hide the corresponding UI element_.
 For example, if the container has the `CaptionsTogglePlugin` enabled with a corresponding button to toggle captions but the game doesn't actually _have_ captions, the container will hide the captions toggle button automatically.
@@ -86,7 +88,7 @@ For example, if the container has the `CaptionsTogglePlugin` enabled with a corr
 ```javascript
 import { PausePlugin, HelpPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container("#game", {
+const container = new Container("#game", {
   plugins: [
     new PausePlugin('button#pause-button'), // Pauses or unpauses the game
     new HelpPlugin('button#help'), // requests a hint or help from the game
@@ -105,7 +107,7 @@ There are two plugins that interact with captions: `CaptionsTogglePlugin`, and `
 ```javascript
 import { CaptionsStylePlugin, CaptionsToggleplugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     new CaptionsTogglePlugin('#captions'),
     new CaptionsStylePlugin(
@@ -162,7 +164,7 @@ The sound plugin supports a total of eight controls:
 ```javascript
 import { SoundPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     new SoundPlugin({
       soundButtons: '#soundButton', // mutes or unmutes all game audio
@@ -197,7 +199,7 @@ import {
   Container
   } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
       new HitAreaScalePlugin('#hitAreaScaleSlider', {defaultHitAreaScale = 0.5}),
       new DragThresholdScalePlugin('#dragThresholdScaleSlider', {defaultDragThresholdScale = 0.5}),
@@ -241,7 +243,7 @@ Note that these plugins accept HTML range inputs, rather than buttons.
 ```javascript
 import { ButtonSizePlugin, PointerSizePlugin, LayersPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     new ButtonSizePlugin('#button-slider-selector', {
       defaultButtonSize: 0.5, // button size goes from 0.0 to 1.0. Default = 0.5
@@ -266,7 +268,7 @@ The HUD plugin allows users to position HUD elements within a game by docking to
 ```javascript
 import { HUDPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     // expects exactly four(4) radio buttons with values "top", "bottom", "left", "right,
     new HUDPlugin('#hud-position-button-selector', {
@@ -293,7 +295,7 @@ The Keyboard Map Plugin allows users to re-map the keys/controls used in-game to
 ```javascript
 import { ControlSensitivityPlugin, KeyboardMapPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     //ControlSensitivityPlugin expects an input of type=range for it's input.
     new ControlSensitivityPlugin('#sensitivity-slider-selector', {
@@ -330,7 +332,7 @@ Keybindings are tracked visually by setting the textContent of the buttons thems
 ```javascript
 import { ColorVisionPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     // expects exactly five(5) radio buttons with values "none", "achromatopsia", "tritanopia", "deuteranopia",
     // and "protanopia" indicating the types of color visions supported.
@@ -365,7 +367,7 @@ The `openPath` method of the Container provides a mechanism for providing option
 `playOptions`:
 
 ```javascript
-var container = new springroll.Container('#game');
+var container = new Container('#game');
 container.openPath('game.html', {
     playOptions: {
         difficulty: 7,
@@ -433,7 +435,7 @@ It is included in the container constructor like any other plugin:
 ```javascript
 import { UserDataPlugin, Container } from 'springroll-container';
 
-const container = new springroll.Container('#game', {
+const container = new Container('#game', {
   plugins: [
     new UserDataPlugin(),
   ]

dist/SpringRoll-Container-umd.js

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

dist/SpringRoll-Container-umd.js.map

@@ -0,0 +1,111 @@
+# Authoring Plugins
+
+The process for writing a Container plugin differs based on whether it is going to be a built-in plugin, or external.
+
+Plugins for Container should take the form of an ES6 module, preferably with a named export. E.g.:
+```javascript
+export class MyContainerPlugin() {...}
+```
+
+When developing a plugin for Container v2.x there are 3 main lifecycle hooks to keep in mind: `preload`, `init`, and `start`.
+
+`preload()`: Preload must return a `Promise`. It can be async. The method is passed the Container instance. In general, most plugins will only need to access the [Bellhop client](https://github.com/SpringRoll/Bellhop). However, the entire Container instance is available should you require it.
+*Note: if this method is missing or the returned promise is rejected, Container will automatically discard your plugin and it will not be loaded in properly.*
+
+Example:
+```javascript
+export class ContainerPlugin() {
+  constructor() {...}
+
+  async preload({ client }) {
+    this.client = client;
+  }
+}
+```
+
+`init()`: The init method is called once all plugin `preload` promises have resolved. Most setup that involves interacting with the Springroll Application via Bellhop would happen here. Any event listeners (bellhop or otherwise) should go here. `init()` is also passed the Container instance if you need it.
+
+`start()`: The `start()` method is called after all preloaded plugins have finished their `init()` calls. This method allows plugins to depend on others by allowing a second plugin to `start()` after a first plugin has ran `init()`. This can help ease race conditions between plugins, as they are not guarenteed to call `init()` in a consistent order. Similarly to `preload()`, `start()` is also passed the Container instance if required.
+
+In general every plugin will follow a similar blueprint and will look something like this:
+```javascript
+export class ContainerPlugin() {
+  constructor() {...}
+
+  async preload({ client }) {
+    this.client = client;
+  }
+
+  init() {...}
+
+  start() {...}
+
+  //Any other helper functions required
+}
+```
+
+However, some more customized plugins plugins may have additional concerns. These are detailed below.```
+
+## External Plugin
+External Plugins are generally specific to an application or organization and follow the above blueprint. They don't tend to follow a Springroll Application feature like `sound` or `captions`, and may just be additional custom functionality for your particular page. In this case, you can implement the methods you need for your plugin with no additional considerations.
+
+## Porting Container v1.x plugins to v2.x
+Exactly how you go about porting your plugin from the SpringRollContainer 1 to 2 will depend on how the original plugin was written. The `init()` function for Container 2.0 plugins will loosely correspond to the older `setup()` from Container 1.0.
+
+The older hook methods `open` and `opened` should now be implemented as event listeners in the main plugin.:
+```javascript
+export class MyPlugin {
+  preload() {
+    return Promise.resolve();
+  }
+
+  init({ client }) {
+    client.on('opened', () => {
+      // do things
+    });
+
+    client.on('open', () => {
+      // do things
+    });
+  }
+}
+```
+
+
+## Internal a.k.a. Built-In Plugins
+If you're developing for SpringrollContainer directly the process is still the same but there are base plugin classes available to keep your plugins DRY and more consistent.
+
+### [BasePlugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/base-plugins/BasePlugin.js)
+[Example Plugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/plugins/KeyboardMapPlugin.js)
+The most barebones plugin class avaialable. Should be used if none of the other plugins match your needs.
+Provides very basic implementations of `preload()`, `init()`, and `start()`.
+
+| It also provides a few useful helper functions: | |
+| --- | --- |
+| `SendProperty(prop, value)` | Sends a single property and it's value through Bellhop to the application. `prop` should match the springroll feature name. Also [saves the property](https://github.com/SpringRoll/SpringRollContainer#saved-data-api) for re-use |
+| `warn(warningText)` | prints out an informative console warning |
+---
+
+### [ButtonPlugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/base-plugins/ButtonPlugin.js)
+[Example Plugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/plugins/CaptionsTogglePlugin.js)
+The `ButtonPlugin` is useful for any plugin that requires a `mute` state (i.e. on or off). It extends the `BasePlugin` and has access to all of the methods above.
+| It also includes: | |
+| --- | --- |
+| `_setMuteProp(prop, button, muted)` | Sets the current state of the property, and sends it to the application. This also handles applying styles to the button or buttons to match. `button` can be a single instance of a button or an array of matching buttons.
+---
+
+### [SliderPlugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/base-plugins/SliderPlugin.js)
+[Example Plugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/plugins/LayersPlugin.js)
+If your plugin requires a range input to control volume or a similar setting this plugin will handle most of it. It can only accept one setting to control however so if you require more than one setting (e.g. `MusicVolume` and `VoiceOverVolume`) consider breaking it out into multiple plugins or just using `BasePlugin`. If your plugin extends this base class all you have to do is pass the configuration options through the `super()` call and the `SliderPlugin` handles the rest.
+
+### [RadioGroupPlugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/base-plugins/RadioGroupPlugin.js)
+[Example Plugin](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/plugins/ColorVisionPlugin.js)
+The RadioGroupPlugin is used for any plugin that uses groups of radio buttons to allow selection between pre-determined options. Similarly to the SliderPlugin above, the RadioGroupPlugin handles most of the set up behind the scenes and you won't have to interact directly with any of its methods.
+
+### UI-Elements
+Container also provides a few base ui-element classes to help set up any HTML controls you have. These are:
+- [Slider](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/ui-elements/Slider.js)
+- [Button](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/ui-elements/Button.js)
+- [RadioGroup](https://github.com/SpringRoll/SpringRollContainer/blob/main/src/ui-elements/RadioGroup.js)
+
+Note: these are used automatically by the `RadioGroupPlugin` and `SliderPlugin`. So these should only be required if you're not using one of those two as your base.

dist/index.js

@@ -216,16 +216,16 @@ export class SoundPlugin extends ButtonPlugin {
       this.voSliders[i].enableSliderEvents(this.onVOVolumeChange.bind(this));
     }
 
-    if (this.soundSliders[0].slider) {
+    if (this.soundSliders[0] && this.soundSliders[0].slider) {
       this.soundVolume = this.soundSliders[0].value;
     }
-    if (this.musicSliders[0].slider) {
+    if (this.musicSliders[0] && this.musicSliders[0].slider) {
       this.musicVolume = this.musicSliders[0].value;
     }
-    if (this.sfxSliders[0].slider) {
+    if (this.sfxSliders[0] && this.sfxSliders[0].slider) {
       this.sfxVolume = this.sfxSliders[0].value;
     }
-    if (this.voSliders[0].slider) {
+    if (this.voSliders[0] && this.voSliders[0].slider) {
       this.voVolume = this.voSliders[0].value;
     }
   }
@@ -391,16 +391,16 @@ export class SoundPlugin extends ButtonPlugin {
   start() {
 
     for (let i = 0; i < this.soundButtonsLength; i++) {
-      this.soundButtons[i].enableButtons();
+      this.soundButtons[i].enableButton();
     }
     for (let i = 0; i < this.musicButtonsLength; i++) {
-      this.musicButtons[i].enableButtons();
+      this.musicButtons[i].enableButton();
     }
     for (let i = 0; i < this.sfxButtonsLength; i++) {
-      this.sfxButtons[i].enableButtons();
+      this.sfxButtons[i].enableButton();
     }
     for (let i = 0; i < this.voButtonsLength; i++) {
-      this.voButtons[i].enableButtons();
+      this.voButtons[i].enableButton();
     }
 
     this.soundMuted = !!SavedData.read(SoundPlugin.soundMutedKey);