Skip to content

Commit ce0532e

Browse files
jylauriljylauril
committed
Changed the API a bit and fixed some small bugs
1 parent 46651e3 commit ce0532e

File tree

8 files changed

+95
-37
lines changed

8 files changed

+95
-37
lines changed

‎README.md

Lines changed: 41 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -49,15 +49,15 @@ $('#runner').runner();
4949

5050

5151

52-
`start` - Start the runner. If runner is not already initialized, it will first initialize and then start itself. Fires `runnerStarted` event.
52+
`start` - Start the runner. If runner is not already initialized, it will first initialize and then start itself. Fires `runnerStart` event.
5353

5454
```javascript
5555
$('#runner').runner('start');
5656
```
5757

5858

5959

60-
`stop` - Stop the runner. Fires `runnerStopped` event.
60+
`stop` - Stop the runner. Fires `runnerStop` event.
6161

6262
```javascript
6363
$('#runner').runner('stop');
@@ -81,12 +81,26 @@ $('#runner').runner('toggle');
8181

8282

8383

84-
`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.**
84+
`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.**
8585

8686
```javascript
8787
$('#runner').runner('reset');
8888
```
8989

90+
To stop the runner along with the reset, you can provide an additional boolean true parameter for the command.
91+
92+
```javascript
93+
$('#runner').runner('reset', true);
94+
```
95+
96+
97+
98+
`version` - Returns the current version string of the runner plugin
99+
100+
```javascript
101+
$('#runner').runner('version');
102+
```
103+
90104

91105

92106
`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.
108122

109123
* `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.
110124

111-
* `stopAt` - (integer) Time in milliseconds at which the runner should stop running and invoke the `runnerStopped` event. Default is null (don't stop).
125+
* `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).
112126

113127
* `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.**
114128

@@ -119,14 +133,17 @@ You can alter the behavior by passing options object to the initialization.
119133

120134
## Events
121135

122-
#### There are currently 3 events that gets fired:
136+
#### There are currently 5 events that gets fired:
123137

124-
* `runnerStarted` - This event gets fired when the `start` method is invoked.
138+
* `runnerStart` - This event gets fired when the `start` method is invoked.
125139

126-
* `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.
140+
* `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.
127141

128142
* `runnerLap` - This event gets fired when the `lap` method is invoked.
129143

144+
* `runnerReset` - This event gets fired when the `reset` method is invoked.
145+
146+
* `runnerFinish` - This event gets fired when the runner reaches the `stopAt` value.
130147

131148
Each of these events will pass the result of the `info` method as an argument in the event call. See examples for usage.
132149

@@ -184,16 +201,28 @@ $('#runner').runner({
184201
countdown: true,
185202
startAt: 12 * 60 * 1000,
186203
stopAt: 0
187-
}).bind('runnerStopped', function(ev, info) {
188-
// check if we have reached the finish, or if the runner was just paused
189-
if (info.time == 0) {
190-
alert('The eggs are now hard-boiled!');
191-
}
204+
}).on('runnerFinish', function(eventObject, info) {
205+
alert('The eggs are now hard-boiled!');
192206
});
193207
```
194208

195209
## Changelog
196210

211+
### v2.1.0 - *2013-01-18* - Changes to the API and bug fixes
212+
* 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()`.
213+
* 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.
214+
* Added a way to stop the runner when calling `reset` method with a boolean true parameter.
215+
* Runner now fires a `runnerFinish` event after it reaches the `stopAt` value.
216+
* We now also fire a `runnerReset` event after the `reset` method is called.
217+
* Streamlined the other events to be more consistent.
218+
* `runnerStarted` is now `runnerStart`.
219+
* `runnerStopped` is now `runnerStop`.
220+
221+
### v2.0.0 - *2013-01-17* - Rewrote the runner plugin with CoffeeScript
222+
* Backwards compatible with the 1.x release
223+
224+
### v1.0.0 - *eons ago* - First version of the runner plugin
225+
197226
## Development
198227

199228
* Source hosted at [GitHub](https://github.com/jylauril/jquery-runner)

‎build/jquery.runner-min.js

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎build/jquery.runner.js

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
/*!
2-
* jQuery-runner - v2.0.0 - 2013-01-17
2+
* jQuery-runner - v2.1.0 - 2013-01-18
33
* https://github.com/jylauril/jquery-runner/
44
* Copyright (c) 2013 Jyrki Laurila <https://github.com/jylauril>
55
*/
66

77
;(function($) {
8-
var meta = { version: "2.0.0", name: "jQuery-runner" };
8+
var meta = { version: "2.1.0", name: "jQuery-runner" };
99

1010
var formatTime, pad, runners, uid, _uid;
1111

@@ -23,6 +23,7 @@ uid = function() {
2323

2424
formatTime = function(time, settings) {
2525
var i, len, ms, output, prefix, separator, step, steps, value, _i, _len;
26+
settings = settings || {};
2627
steps = [3600000, 60000, 1000, 10];
2728
separator = ['', ':', ':', '.'];
2829
prefix = '';
@@ -73,6 +74,8 @@ Runner = (function() {
7374

7475
Runner.prototype.updating = false;
7576

77+
Runner.prototype.finished = false;
78+
7679
Runner.prototype.interval = null;
7780

7881
Runner.prototype.total = 0;
@@ -107,10 +110,13 @@ Runner = (function() {
107110
var format;
108111
format = this.settings.format;
109112
if ($.isFunction(format)) {
110-
return format(value, formatTime, this.settings.milliseconds);
113+
format;
114+
111115
} else {
112-
return formatTime(value, this.settings);
116+
formatTime;
117+
113118
}
119+
return format(value, this.settings);
114120
};
115121

116122
Runner.prototype.update = function() {
@@ -130,7 +136,9 @@ Runner = (function() {
130136
}
131137
if (stopAt !== null && (countdown && this.total <= stopAt) || (!countdown && this.total >= stopAt)) {
132138
this.total = stopAt;
139+
this.finished = true;
133140
this.stop();
141+
this.fire('runnerFinish');
134142
}
135143
this.value(this.total);
136144
this.updating = false;
@@ -145,14 +153,14 @@ Runner = (function() {
145153
var _this = this;
146154
if (!this.running) {
147155
this.running = true;
148-
if (!this.startTime) {
156+
if (!this.startTime || this.finished) {
149157
this.reset();
150158
}
151159
this.lastTime = $.now();
152160
this.interval = setInterval(function() {
153161
_this.update();
154162
}, this.settings.interval);
155-
this.fire('runnerStarted');
163+
this.fire('runnerStart');
156164
}
157165
};
158166

@@ -161,7 +169,7 @@ Runner = (function() {
161169
this.running = false;
162170
clearInterval(this.interval);
163171
this.update();
164-
this.fire('runnerStopped');
172+
this.fire('runnerStop');
165173
}
166174
};
167175

@@ -186,17 +194,23 @@ Runner = (function() {
186194
return last;
187195
};
188196

189-
Runner.prototype.reset = function() {
197+
Runner.prototype.reset = function(stop) {
198+
if (stop) {
199+
this.stop();
200+
}
190201
this.startTime = this.lapTime = this.lastTime = $.now();
191202
this.total = this.settings.startAt;
192203
this.value(this.total);
204+
this.finished = false;
205+
this.fire('runnerReset');
193206
};
194207

195208
Runner.prototype.info = function() {
196209
var lap;
197210
lap = this.lastLap || 0;
198211
return {
199212
running: this.running,
213+
finished: this.finished,
200214
time: this.total,
201215
formattedTime: this.format(this.total),
202216
startTime: this.startTime,
@@ -233,11 +247,15 @@ if ($) {
233247
return runner.info();
234248
}
235249
break;
250+
case 'reset':
251+
if (runner) {
252+
runner.reset(options);
253+
}
254+
break;
236255
case 'start':
237256
case 'stop':
238257
case 'toggle':
239258
case 'lap':
240-
case 'reset':
241259
if (runner) {
242260
runner[method]();
243261
}
@@ -249,6 +267,7 @@ if ($) {
249267
}
250268
return this;
251269
};
270+
$.fn.runner.format = formatTime;
252271
} else {
253272
throw '[' + meta.name + '] jQuery library is required for this plugin to work';
254273
}

‎lib/expose.coffee

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,11 @@ if $
1414
switch method
1515
when 'init' then Runner(@, options, start)
1616
when 'info' then return runner.info() if runner
17-
when 'start', 'stop', 'toggle', 'lap', 'reset' then runner[method]() if runner
17+
when 'reset' then runner.reset(options) if runner
18+
when 'start', 'stop', 'toggle', 'lap' then runner[method]() if runner
1819
when 'version' then return meta.version
1920
else $.error '[' + meta.name + '] Method ' + method + ' does not exist'
2021
return @
22+
$.fn.runner.format = formatTime
2123
else
2224
throw '[' + meta.name + '] jQuery library is required for this plugin to work'

‎lib/runner.coffee

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ class Runner
1818

1919
running: false
2020
updating: false
21+
finished: false
2122
interval: null
2223
total: 0
2324
lastTime: 0
@@ -43,8 +44,8 @@ class Runner
4344

4445
format: (value) ->
4546
format = @settings.format
46-
if $.isFunction(format) then format(value, formatTime, @settings.milliseconds)
47-
else formatTime(value, @settings)
47+
if $.isFunction(format) then format else formatTime
48+
format(value, @settings)
4849

4950
update: ->
5051
if not @updating
@@ -58,7 +59,9 @@ class Runner
5859
if countdown then @total -= delta else @total += delta
5960
if stopAt isnt null and (countdown and @total <= stopAt) or (not countdown and @total >= stopAt)
6061
@total = stopAt
62+
@finished = true
6163
@stop()
64+
@fire 'runnerFinish'
6265

6366
@value @total
6467
@updating = false
@@ -71,23 +74,23 @@ class Runner
7174
start: ->
7275
if not @running
7376
@running = true
74-
if not @startTime
77+
if not @startTime or @finished
7578
@reset()
7679
@lastTime = $.now()
7780
@interval = setInterval(=>
7881
@update()
7982
return
8083
, @settings.interval)
8184

82-
@fire 'runnerStarted'
85+
@fire 'runnerStart'
8386
return
8487

8588
stop: ->
8689
if @running
8790
@running = false
8891
clearInterval @interval
8992
@update()
90-
@fire 'runnerStopped'
93+
@fire 'runnerStop'
9194
return
9295

9396
toggle: ->
@@ -104,20 +107,24 @@ class Runner
104107
@fire 'runnerLap'
105108
return last
106109

107-
reset: ->
110+
reset: (stop) ->
111+
if stop then @stop()
108112
@startTime = @lapTime = @lastTime = $.now()
109113
@total = @settings.startAt
110114
@value @total
115+
@finished = false
116+
@fire 'runnerReset'
111117
return
112118

113119
info: ->
114120
lap = @lastLap or 0
115121
{
116122
running: @running
117-
time: @total,
118-
formattedTime: @format(@total),
119-
startTime: @startTime,
120-
lapTime: lap,
121-
formattedLapTime: @format(lap),
123+
finished: @finished
124+
time: @total
125+
formattedTime: @format(@total)
126+
startTime: @startTime
127+
lapTime: lap
128+
formattedLapTime: @format(lap)
122129
settings: @settings
123130
}

‎lib/utils.coffee

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ runners = {}
33
_uid = 1
44
uid = () -> 'runner' + _uid++
55
formatTime = (time, settings) ->
6+
settings = settings or {}
67
steps = [3600000, 60000, 1000, 10]
78
separator = ['', ':', ':', '.']
89
prefix = ''

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "jquery.runner",
33
"title": "jQuery-runner",
4-
"version": "2.0.0",
4+
"version": "2.1.0",
55
"description": "A simple runner/stopwatch jQuery plugin for counting time up and down.",
66
"homepage": "https://github.com/jylauril/jquery-runner",
77
"main": "build/jquery.runner.js",

‎runner.jquery.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "runner",
33
"title": "jQuery-runner",
4-
"version": "2.0.0",
4+
"version": "2.1.0",
55
"description": "A simple runner/stopwatch jQuery plugin for counting time up and down.",
66
"homepage": "https://github.com/jylauril/jquery-runner",
77
"docs": "https://github.com/jylauril/jquery-runner",

0 commit comments

Comments
 (0)