Changed the API a bit and fixed some small bugs

jylauril · Jan 18, 2013 · ce0532e · ce0532e
1 parent 46651e3
commit ce0532e
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -49,15 +49,15 @@ $('#runner').runner();
 
 
 
-`start` - Start the runner. If runner is not already initialized, it will first initialize and then start itself. Fires `runnerStarted` event.
+`start` - Start the runner. If runner is not already initialized, it will first initialize and then start itself. Fires `runnerStart` event.
 
 ```javascript
 $('#runner').runner('start');
 ```
 
 
 
-`stop` - Stop the runner. Fires `runnerStopped` event.
+`stop` - Stop the runner. Fires `runnerStop` event.
 
 ```javascript
 $('#runner').runner('stop');
@@ -81,12 +81,26 @@ $('#runner').runner('toggle');
 
 
 
-`reset` - Resets the time and settings to the original (initial) values. **Note that if the runner is running when invoking this method, this does not stop the runner, it just resets the time back to where it started and continues from there.**
+`reset` - Resets the time and settings to the original (initial) values. Fires `runnerReset` event. **Note that if the runner is running when invoking this method, this does not stop the runner, it just resets the time back to where it started and continues from there.**
 
 ```javascript
 $('#runner').runner('reset');
 ```
 
+To stop the runner along with the reset, you can provide an additional boolean true parameter for the command.
+
+```javascript
+$('#runner').runner('reset', true);
+```
+
+
+
+`version` - Returns the current version string of the runner plugin
+
+```javascript
+$('#runner').runner('version');
+```
+
 
 
 `info` - Returns a JavaScript object with information about the current status of the runner.
@@ -108,7 +122,7 @@ You can alter the behavior by passing options object to the initialization.
 
 * `startAt` - (integer) Time in milliseconds from which the runner should start running. Defaults to 0. This works with both counting up and down, as long as the value is within the current run direction.
 
-* `stopAt` - (integer) Time in milliseconds at which the runner should stop running and invoke the `runnerStopped` event. Default is null (don't stop).
+* `stopAt` - (integer) Time in milliseconds at which the runner should stop running and invoke the `runnerStop` and `runnerFinish` events. Default is null (don't stop).
 
 * `milliseconds` - (boolean) If set to false, the default formatter will omit the milliseconds from displaying. Defaults to true (show milliseconds). **Note that if you use a custom formatter, this option will not affect the first value of that custom formatter function. This option, however, is passed in as third argument.**
 
@@ -119,14 +133,17 @@ You can alter the behavior by passing options object to the initialization.
 
 ## Events
 
-#### There are currently 3 events that gets fired:
+#### There are currently 5 events that gets fired:
 
-* `runnerStarted` - This event gets fired when the `start` method is invoked.
+* `runnerStart` - This event gets fired when the `start` method is invoked.
 
-* `runnerStopped` - This event gets fired when the `stop` method is invoked. Note that this event is also fired when the runner reaches the `stopAt` value.
+* `runnerStop` - This event gets fired when the `stop` method is invoked. Note that this event is also fired when the runner reaches the `stopAt` value.
 
 * `runnerLap` - This event gets fired when the `lap` method is invoked.
 
+* `runnerReset` - This event gets fired when the `reset` method is invoked.
+
+* `runnerFinish` - This event gets fired when the runner reaches the `stopAt` value.
 
 Each of these events will pass the result of the `info` method as an argument in the event call. See examples for usage.
 
@@ -184,16 +201,28 @@ $('#runner').runner({
     countdown: true,
     startAt: 12 * 60 * 1000,
     stopAt: 0
-}).bind('runnerStopped', function(ev, info) {
-    // check if we have reached the finish, or if the runner was just paused
-    if (info.time == 0) {
-        alert('The eggs are now hard-boiled!');
-    }
+}).on('runnerFinish', function(eventObject, info) {
+    alert('The eggs are now hard-boiled!');
 });
 ```
 
 ## Changelog
 
+### v2.1.0 - *2013-01-18* - Changes to the API and bug fixes
+* The custom format function no longer gets the inbuilt formatter as a second parameter. You can access the runner's inbuilt formatter through `$().runner.format()`.
+* The custom format function now gets the `settings` object as second parameter, which has the `milliseconds` -property that was given as 3rd parameter in the old version.
+* Added a way to stop the runner when calling `reset` method with a boolean true parameter.
+* Runner now fires a `runnerFinish` event after it reaches the `stopAt` value.
+* We now also fire a `runnerReset` event after the `reset` method is called.
+* Streamlined the other events to be more consistent.
+  * `runnerStarted` is now `runnerStart`.
+  * `runnerStopped` is now `runnerStop`.
+
+### v2.0.0 - *2013-01-17* - Rewrote the runner plugin with CoffeeScript
+* Backwards compatible with the 1.x release
+
+### v1.0.0 - *eons ago* - First version of the runner plugin
+
 ## Development
 
 * Source hosted at [GitHub](https://github.com/jylauril/jquery-runner)

diff --git a/build/jquery.runner-min.js b/build/jquery.runner-min.js
diff --git a/build/jquery.runner.js b/build/jquery.runner.js
@@ -1,11 +1,11 @@
 /*!
- * jQuery-runner - v2.0.0 - 2013-01-17
+ * jQuery-runner - v2.1.0 - 2013-01-18
  * https://github.com/jylauril/jquery-runner/
  * Copyright (c) 2013 Jyrki Laurila <https://github.com/jylauril>
  */
 
 ;(function($) {
-var meta = { version: "2.0.0", name: "jQuery-runner" };
+var meta = { version: "2.1.0", name: "jQuery-runner" };
 
 var formatTime, pad, runners, uid, _uid;
 
@@ -23,6 +23,7 @@ uid = function() {
 
 formatTime = function(time, settings) {
   var i, len, ms, output, prefix, separator, step, steps, value, _i, _len;
+  settings = settings || {};
   steps = [3600000, 60000, 1000, 10];
   separator = ['', ':', ':', '.'];
   prefix = '';
@@ -73,6 +74,8 @@ Runner = (function() {
 
   Runner.prototype.updating = false;
 
+  Runner.prototype.finished = false;
+
   Runner.prototype.interval = null;
 
   Runner.prototype.total = 0;
@@ -107,10 +110,13 @@ Runner = (function() {
     var format;
     format = this.settings.format;
     if ($.isFunction(format)) {
-      return format(value, formatTime, this.settings.milliseconds);
+      format;
+
     } else {
-      return formatTime(value, this.settings);
+      formatTime;
+
     }
+    return format(value, this.settings);
   };
 
   Runner.prototype.update = function() {
@@ -130,7 +136,9 @@ Runner = (function() {
       }
       if (stopAt !== null && (countdown && this.total <= stopAt) || (!countdown && this.total >= stopAt)) {
         this.total = stopAt;
+        this.finished = true;
         this.stop();
+        this.fire('runnerFinish');
       }
       this.value(this.total);
       this.updating = false;
@@ -145,14 +153,14 @@ Runner = (function() {
     var _this = this;
     if (!this.running) {
       this.running = true;
-      if (!this.startTime) {
+      if (!this.startTime || this.finished) {
         this.reset();
       }
       this.lastTime = $.now();
       this.interval = setInterval(function() {
         _this.update();
       }, this.settings.interval);
-      this.fire('runnerStarted');
+      this.fire('runnerStart');
     }
   };
 
@@ -161,7 +169,7 @@ Runner = (function() {
       this.running = false;
       clearInterval(this.interval);
       this.update();
-      this.fire('runnerStopped');
+      this.fire('runnerStop');
     }
   };
 
@@ -186,17 +194,23 @@ Runner = (function() {
     return last;
   };
 
-  Runner.prototype.reset = function() {
+  Runner.prototype.reset = function(stop) {
+    if (stop) {
+      this.stop();
+    }
     this.startTime = this.lapTime = this.lastTime = $.now();
     this.total = this.settings.startAt;
     this.value(this.total);
+    this.finished = false;
+    this.fire('runnerReset');
   };
 
   Runner.prototype.info = function() {
     var lap;
     lap = this.lastLap || 0;
     return {
       running: this.running,
+      finished: this.finished,
       time: this.total,
       formattedTime: this.format(this.total),
       startTime: this.startTime,
@@ -233,11 +247,15 @@ if ($) {
           return runner.info();
         }
         break;
+      case 'reset':
+        if (runner) {
+          runner.reset(options);
+        }
+        break;
       case 'start':
       case 'stop':
       case 'toggle':
       case 'lap':
-      case 'reset':
         if (runner) {
           runner[method]();
         }
@@ -249,6 +267,7 @@ if ($) {
     }
     return this;
   };
+  $.fn.runner.format = formatTime;
 } else {
   throw '[' + meta.name + '] jQuery library is required for this plugin to work';
 }

diff --git a/lib/expose.coffee b/lib/expose.coffee
@@ -14,9 +14,11 @@ if $
         switch method
             when 'init' then Runner(@, options, start)
             when 'info' then return runner.info() if runner
-            when 'start', 'stop', 'toggle', 'lap', 'reset' then runner[method]() if runner
+            when 'reset' then runner.reset(options) if runner
+            when 'start', 'stop', 'toggle', 'lap' then runner[method]() if runner
             when 'version' then return meta.version
             else $.error '[' + meta.name + '] Method ' +  method + ' does not exist'
         return @
+    $.fn.runner.format = formatTime
 else
     throw '[' + meta.name + '] jQuery library is required for this plugin to work'
diff --git a/lib/runner.coffee b/lib/runner.coffee
@@ -18,6 +18,7 @@ class Runner
 
     running: false
     updating: false
+    finished: false
     interval: null
     total: 0
     lastTime: 0
@@ -43,8 +44,8 @@ class Runner
 
     format: (value) ->
         format = @settings.format
-        if $.isFunction(format) then format(value, formatTime, @settings.milliseconds)
-        else formatTime(value, @settings)
+        if $.isFunction(format) then format else formatTime
+        format(value, @settings)
 
     update: ->
         if not @updating
@@ -58,7 +59,9 @@ class Runner
             if countdown then @total -= delta else @total += delta
             if stopAt isnt null and (countdown and @total <= stopAt) or (not countdown and @total >= stopAt)
                 @total = stopAt
+                @finished = true
                 @stop()
+                @fire 'runnerFinish'
 
             @value @total
             @updating = false
@@ -71,23 +74,23 @@ class Runner
     start: ->
         if not @running
             @running = true
-            if not @startTime
+            if not @startTime or @finished
                 @reset()
             @lastTime = $.now()
             @interval = setInterval(=>
                 @update()
                 return
             , @settings.interval)
 
-            @fire 'runnerStarted'
+            @fire 'runnerStart'
         return
 
     stop: ->
         if @running
             @running = false
             clearInterval @interval
             @update()
-            @fire 'runnerStopped'
+            @fire 'runnerStop'
         return
 
     toggle: ->
@@ -104,20 +107,24 @@ class Runner
         @fire 'runnerLap'
         return last
 
-    reset: ->
+    reset: (stop) ->
+        if stop then @stop()
         @startTime = @lapTime = @lastTime = $.now()
         @total = @settings.startAt
         @value @total
+        @finished = false
+        @fire 'runnerReset'
         return
 
     info: ->
         lap = @lastLap or 0
         {
             running: @running
-            time: @total,
-            formattedTime: @format(@total),
-            startTime: @startTime,
-            lapTime: lap,
-            formattedLapTime: @format(lap),
+            finished: @finished
+            time: @total
+            formattedTime: @format(@total)
+            startTime: @startTime
+            lapTime: lap
+            formattedLapTime: @format(lap)
             settings: @settings
         }
diff --git a/lib/utils.coffee b/lib/utils.coffee
@@ -3,6 +3,7 @@ runners = {}
 _uid = 1
 uid = () -> 'runner' + _uid++
 formatTime = (time, settings) ->
+    settings = settings or {}
     steps = [3600000, 60000, 1000, 10]
     separator = ['', ':', ':', '.']
     prefix = ''

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "jquery.runner",
   "title": "jQuery-runner",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A simple runner/stopwatch jQuery plugin for counting time up and down.",
   "homepage": "https://github.com/jylauril/jquery-runner",
   "main": "build/jquery.runner.js",

diff --git a/runner.jquery.json b/runner.jquery.json
@@ -1,7 +1,7 @@
 {
   "name": "runner",
   "title": "jQuery-runner",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A simple runner/stopwatch jQuery plugin for counting time up and down.",
   "homepage": "https://github.com/jylauril/jquery-runner",
   "docs": "https://github.com/jylauril/jquery-runner",