v1.2.0

added event handler methods

docs/README.md

@@ -423,6 +423,30 @@ Returns the track's current volume; this is the track's volume state and does no
 
 ---
 
+- **the `<track>.on(type, callback)` method**
+
+- Arguments:  
+  - `type`: a valid event type  
+  - `callback`: a function to run as a handler for the indicated event
+
+- Returns: none.
+
+Sets up a recurring event handler. Read more [here](#events).
+
+---
+
+- **the `<track>.one(type, callback)` method**
+
+- Arguments:  
+  - `type`: a valid event type  
+  - `callback`: a function to run as a handler for the indicated event
+
+- Returns: none.
+
+Sets up a single-use event handler. Read more [here](#events).
+
+---
+
 ## Master Audio Methods
 
 The master audio methods are used for controlling *all* sound in the game at once. The master audio does not change you tracks, instead it overrides them. For example, if you have the `'theme'` track muted and the `'beep'` track unmuted, `A.mute(true)` will make `'beep'` silent. `A.mute(false)` will not make `'theme'` audible, however. None of these methods are chainable.
@@ -511,6 +535,30 @@ Shows a loading screen while all previously defined tracks are cached by the bro
 
 ---
 
+- **the `A.on(type, callback)` method**
+
+- Arguments:  
+  - `type`: a valid event type  
+  - `callback`: a function to run as a handler for the indicated event
+
+- Returns: none.
+
+Sets up a recurring event handler. Read more [here](#events).
+
+---
+
+- **the `A.one(type, callback)` method**
+
+- Arguments:  
+  - `type`: a valid event type  
+  - `callback`: a function to run as a handler for the indicated event
+
+- Returns: none.
+
+Sets up a single-use event handler. Read more [here](#events).
+
+---
+
 ## Groups
 
 Groups are ways to collect and organize tracks, but should *not* be confused with playlists (read on for those). These are designed to allow you to select and control a large number of tracks and do something to them. The methods used by groups are very similar to some of the track methods, but as said, generally do something to all of them at once.
@@ -867,38 +915,77 @@ This method removes a story menu link. If there are multiple links with the same
 
 There are two kinds of events that are triggered by HAL--events triggered on the document *only* and events triggered on *both* the track element and the document.
 
-## Event Handlers
+## Track Event Methods
 
-It is recommended that you write events using [jQuery's `on()`](http://api.jquery.com/on/) or [`one()` methods](http://api.jquery.com/one/). For example:
+There are two track event methods you can use; `<track>.on()` and `<track>.one()`. The former triggers a handler each time the indicated event occurs, the latter triggers a handler only once. These methods can only be used with [track events](#list-of-track-events).
 
 ```javascript
-$(document).on(':volume', function (ev) {
-    console.log('track "' + ev.track.$el.attr('data-track') + '"" volume changed');
+A.track('some-song').one(':volume', function () {
+    // occurs only once when the volume of "some-song" is changed
+    console.log('track "some-song" volume changed');
 });
 ```
 
 ```javascript
-A.track('some-song').$el.one(':volume', function () {
+A.track('some-song').on(':volume', function () {
+    // occurs each time the volume of "some-song" is changed
     console.log('track "some-song" volume changed');
 });
 ```
 
+## Global Event Methods
+
+As with track event methods, there are two: `A.on()` and `A.one()`. These event methods monitor *all* tracks for events, and also monitor for [master audio events](#list-of-master-audio-events).
+
+```javascript
+A.one(':volume', function (ev) {
+    // occurs only once when the volume of a track is changed
+    console.log('track "' + ev.track.id + '" volume changed');
+});
+```
+
+```javascript
+A.on(':volume', function (ev) {
+    // occurs each time the volume of any track is changed
+    console.log('track "' + ev.track.id + '" volume changed');
+});
+```
+
 ## List of Track Events
 
-These events are triggered on both the document and the track element. The track's definition is available as `<event>.track`.
+These events are triggered on both the document and the track element. The track's definition is available as `<event>.track`. These events may be used with `<track>.on()` and `<track>.one()` to listen for events on specific tracks, or with `A.on()` and `A.one()` to listen for events on any and all tracks.
+
+| Event        | Description                                |
+| ---          | ---                                        |
+| `:available` | a track's metadata is loaded               |
+| `:loaded`    | a track can be played from start to finish |
+| `:play`      | a track starts playing                     |
+| `:pause`     | a track is paused                          |
+| `:stop`      | a track reaches the end or is stopped      |
+| `:mute`      | a track is muted or unmuted                |
+| `:volume`    | a track's volume is changed                |
+
+## List of Master Audio Events
+
+These events are only available for use with `A.on()` and `A.one()`, and are only triggered on the document element.
+
+| Event            | Description                                 |
+| ---              | ---                                         |
+| `:master-mute`   | the master mute control is muted or unmuted |
+| `:master-volume` | the master volume is changed                |
+
+## The Event Object
 
-- `:available` -> a track's metadata is loaded  
-- `:loaded` -> a track can be played from start to finish  
-- `:play` -> a track starts playing  
-- `:pause` -> a track is paused  
-- `:stop` -> a track reaches the end or is stopped  
-- `:mute` -> a track is muted or unmuted  
-- `:volume` -> a track's volume is changed
+The event object in track events contains the `track` property, which contains the definition of the track that triggered the event.
 
-## Other Events
+| Property                | Description                                  |
+| ---                     | ---                                          |
+| `<event>.track.id`      | The track's name/id.                         |
+| `<event>.track.$el`     | The track's jQuery-wrapped audio element.    |
+| `<event>.track.unwrap`  | The track's `<audio>` element object.        |
+| `<event>.track.sources` | The track's sources; a string array of URLs. |
 
-- `:master-mute` -> the master mute control is muted or unmuted  
-- `:master-volume` -> the master volume is changed
+You can run any valid track methods directly on the track in the event object as well, e.g. `<event>.track.getVolume()`.
 
 ---
 

docs/changelog.md

@@ -1,3 +1,12 @@
+## v1.2.0
+
+This version adds event handler methods to the `track` prototype and to the root `A` object.
+
+- Added the `track#on()` and `track#one()` methods.
+- Added the `A.on()` and `A.one()` methods.
+- Updated the docs with the new event methods and an event section.
+- Internal improvements.
+
 ## v1.1.2
 
 This patch addresses an issue where `options.controls.show` was throwing on false.

src/audio.js

@@ -134,6 +134,21 @@
         }
     };
 
+    var validEvents = {
+        track : [
+            ':available', 
+            ':loaded', 
+            ':play',
+            ':stop',
+            ':mute',
+            ':volume'
+        ],
+        master : [
+            ':master-mute',
+            ':master-volume'
+        ]
+    };
+
     /** 
       * stolen from sugarCube's simpleaudio.js, by Thomas Michael Edwards
       * https://bitbucket.org/tmedwards/sugarcube/src/ab043c3d6dcdc69c208285272e4632c376f7e80d/src/lib/simpleaudio.js
@@ -526,22 +541,85 @@
             setTimeout( function () {
                 cb.call(self, self, duration);
             }, duration);
+        },
+        on : function (type, cb) {
+            if (!cb || typeof cb !== 'function') {
+                console.error('<track>.on() -> invalid callback');
+                return this;
+            }
+            type = type.trim().toLowerCase();
+            if (type[0] !== ':') {
+                type = ':' + type;
+            }
+            if (!validEvents.track.includes(type)) {
+                console.error('<track>.on() -> invalid event type');
+                return this;
+            }
+            this.$el.on(type, cb);
+        },
+        one : function () {
+            if (!cb || typeof cb !== 'function') {
+                console.error('<track>.one() -> invalid callback');
+                return this;
+            }
+            type = type.trim().toLowerCase();
+            if (type[0] !== ':') {
+                type = ':' + type;
+            }
+            if (!validEvents.track.includes(type)) {
+                console.error('<track>.one() -> invalid event type');
+                return this;
+            }
+            this.$el.one(type, cb);
+        }
+    };
+
+    var validMaster = validEvents.track.concat(validEvents.master);
+
+    Audio.on = function (type, cb) {
+        if (!cb || typeof cb !== 'function') {
+            console.error('Chapel.Audio.on() -> invalid callback');
+            return;
+        }
+        type = type.trim().toLowerCase();
+        if (type[0] !== ':') {
+            type = ':' + type;
+        }
+        if (!validMaster.includes(type)) {
+            console.error('Chapel.Audio.on() -> invalid event type');
+            return;
+        }
+        $(document).on(type, cb);
+    };
+    Audio.one = function (type, cb) {
+        if (!cb || typeof cb !== 'function') {
+            console.error('Chapel.Audio.one() -> invalid callback');
+            return;
+        }
+        type = type.trim().toLowerCase();
+        if (type[0] !== ':') {
+            type = ':' + type;
+        }
+        if (!validMaster.includes(type)) {
+            console.error('Chapel.Audio.one() -> invalid event type');
+            return;
         }
+        $(document).one(type, cb);
     };
 
-    $(document).on(':master-mute', Track.renew);
-    $(document).on(':master-volume', Track.renew);
+    Audio.on(':master-mute', Track.renew);
+    Audio.on(':master-volume', Track.renew);
 
     if (options.persistPrefs) {
-        $(document).on(':master-mute', Audio.savePrefs);
-        $(document).on(':master-volume', Audio.savePrefs);
+        Audio.on(':master-mute', Audio.savePrefs);
+        Audio.on(':master-volume', Audio.savePrefs);
     }
 
-    $(document).on(':play', function (ev) {
+    Audio.on(':play', function (ev) {
         ev.track.addToGroup('playing');
     });
 
-    $(document).on(':stop', function (ev) {
+    Audio.on(':stop', function (ev) {
         ev.track.removeFromGroup('playing');
     });