Skip to content
This repository was archived by the owner on Apr 4, 2024. It is now read-only.

Commit 9cfbe4d

Browse files
author
Søren Ernst
authored
Update README.md
1 parent 71f3ed5 commit 9cfbe4d

File tree

1 file changed

+141
-107
lines changed

1 file changed

+141
-107
lines changed

‎README.md

Lines changed: 141 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,195 @@
11
# moment-timer
22

3-
### Synopsis
3+
[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url]
4+
5+
---
6+
7+
## Synopsis
48
This is a Moment.js plugin that allows the use of timers, which offer much more control than the native JavaScript timers. It's basically a rewrite of JavaScripts own setInterval and setTimeout. For an example, see the example folder or read the Usage section below.
59

6-
<hr>
10+
---
11+
12+
## Latest changes
13+
14+
New version v1.2.1 released with better documentation and a new isStarted function.
715

8-
### Installation
16+
**Module loading was added in last version, v1.2.0 thanks to [Alxmerino.](https://github.com/Alxmerino)**
917

10-
#### Npm
18+
---
19+
20+
## Installation
21+
22+
### Npm
1123
```
1224
npm install moment-timer
1325
```
1426

15-
#### Bower
27+
### Bower
1628
```
1729
bower install moment-timer
1830
```
1931

20-
#### Browser
32+
### Browser
2133
```
2234
<script src="path/to/moment-timer.js"></script>
2335
```
2436
When using this plugin in the browser, be sure to include moment.js on your page first.
2537

26-
<hr>
38+
---
2739

28-
### Usage
40+
## Attributes
2941

30-
#### How to use moment-timer. This will create a timeout like timer that runs after five seconds.
31-
```javascript
32-
var timer = moment.duration(5, "seconds").timer(function() {
33-
// Callback
34-
});
42+
### (bool) start
43+
```js
44+
new moment.duration(1000).timer({ start: true }, callback);
3545
```
46+
Setting this attribute to true will cause the timer to start once instantiated.
3647

37-
#### In this example we will create an interval like timer. Simply set the <b>loop</b> attribute.
38-
```javascript
39-
var timer = moment.duration(5, "seconds").timer({
40-
loop: true
41-
}, function() {
42-
// Callback
43-
});
48+
---
49+
50+
### (bool) loop
51+
```js
52+
new moment.duration(1000).timer({ loop: true }, callback);
4453
```
54+
Setting this attribute to true will cause the timer to loop/restart once a duration is complete.
4555

46-
#### Prevent the timer from starting on creation, by using the <b>start</b> attribute, so we can start it later.
47-
```javascript
48-
var timer = moment.duration(5, "seconds").timer({
49-
loop: true,
50-
start: false
51-
}, function() {
52-
// Callback
53-
});
54-
timer.start();
56+
---
57+
58+
### (int | moment.duration) wait
59+
```js
60+
new moment.duration(1000).timer({ wait: 5000 }, callback);
61+
```
62+
```js
63+
new moment.duration(1000).timer({ wait: moment.duration(5, 'seconds') }, callback);
5564
```
65+
Setting this attribute will cause the timer to wait for a specified amount of time ebfore starting it's duration. This is kind of an extra first duration. Imagine a timer that runs every second. Setting the wait attribute to 5000 / 5 seconds, means it waits that long and then starts acting like a normal timer would. Notice that this attribute accepts both int and moment.duration .
5666

57-
#### Stopping a timer can be done by using the stop() function. After the timer has been stopped, the start function can be used to start it again.
58-
```javascript
59-
var timer = moment.duration(5, "seconds").timer({
60-
loop: true,
61-
start: true
62-
}, function() {
63-
// Callback
64-
});
65-
timer.stop();
66-
timer.start();
67+
---
68+
69+
### (bool) executeAfterWait
70+
```js
71+
new moment.duration(1000).timer({ wait: 5000, executeAfterWait: true }, callback);
6772
```
73+
Setting this attribute to true will cause the callback function to be called after the wait duration has ended. This is a way to make sure the callback is executed even before the timer starts.
6874

69-
#### See if a timer has been stopped.
70-
```javascript
71-
var timer = moment.duration(5, "seconds").timer({
72-
loop: true,
73-
start: true
74-
}, function() {
75-
// Callback
76-
});
77-
timer.stop();
78-
timer.isStopped(); // True
75+
---
7976

77+
## Functions
78+
### .start()
79+
```js
80+
let timer = new moment.duration(1000).timer(callback);
8081
timer.start();
81-
timer.isStopped(); // False
8282
```
83+
This function will cause the timer to start. It can be used if the start attribute has not been set or if the timer has been stopped.
84+
85+
---
8386

84-
#### Delaying a timer can be done by using the <b>wait</b> attribute. In the example below, the timer will wait for an hour and five seconds before it executes.
85-
```javascript
86-
var timer = moment.duration(5, "seconds").timer({
87-
wait: moment.duration(1, "hour"),
88-
loop: true,
89-
}, function() {
90-
// Callback
91-
});
87+
### .stop()
88+
```js
89+
let timer = new moment.duration(1000).timer({ start: true }, callback);
90+
timer.stop();
9291
```
92+
This function will cause the timer to stop. It can be used if timer has been started to halt it.
93+
94+
---
9395

94-
#### Having the timer execute after waiting, can be done by using the <b>executeAfterWait</b> attribute. In the example below, the timer will wait for an hour, then execute and do so again after another five seconds.
95-
```javascript
96-
var timer = moment.duration(5, "seconds").timer({
97-
wait: moment.duration(1, "hour"),
98-
executeAfterWait: true,
99-
loop: true,
100-
}, function() {
101-
// Callback
102-
});
96+
### .duration(int | moment.duration)
97+
```js
98+
let timer = new moment.duration(1000).timer(callback);
99+
timer.duration(5000);
100+
timer.duration(moment.duration(5, "seconds");
103101
```
102+
This function can be used to change the duration the timer was instantiated with.
104103
105-
#### Setting the duration of a timer. This will override the duration set when the timer was created.
106-
```javascript
107-
var timer = moment.duration(5, "seconds").timer({
108-
loop: true,
109-
}, function() {
110-
// Callback
111-
});
104+
---
112105
113-
timer.duration(2000);
114-
timer.duration("2", "seconds");
115-
timer.duration({seconds: 2});
106+
### .getDuration()
107+
```js
108+
let timer = new moment.duration(1000).timer(callback);
109+
timer.getDuration();
116110
```
111+
This function will return the current duration of a timer. In this case it will return 1000.
117112
118-
#### Getting the duration of a timer.
119-
```javascript
120-
var timer = moment.duration(5, "seconds").timer({
121-
loop: true,
122-
}, function() {
123-
// Callback
124-
});
113+
---
125114
126-
var duration = timer.getDuration();
115+
### .getRemainingDuration()
116+
```js
117+
let timer = new moment.duration(1000).timer(callback);
118+
timer.getRemainingDuration();
127119
```
120+
This function will return the remaining duration of a timers cycle. In this case, imagine that the timer has been running for 500ms and we call .getRemainingDuration() on it, in this example it will return 500, since half of the cycle has completed.
128121
129-
#### Getting the remaining duration of a timer. (How long until it ends or loops again)
130-
```javascript
131-
var timer = moment.duration(5, "seconds").timer({
132-
loop: true,
133-
}, function() {
134-
// Callback
135-
});
122+
---
136123
137-
var remainingDuration = timer.getRemainingDuration();
124+
### .isStopped()
125+
126+
```js
127+
let timer = new moment.duration(1000).timer(callback);
128+
timer.start();
129+
timer.isStopped(); // false
130+
timer.stop();
131+
timer.isStopped(); // true
138132
```
133+
This function can be used to see if the timer has been stopped by the .stop() function.
134+
135+
---
139136
140-
#### In this example we an see that a "timeout like timer" can be reused. If you run this example, you will notice it executing the callback twice. This is to show that even if you use the timer like a timeout, it can be reused, unlike JavaScripts native setTimeout that will only function once.
141-
```javascript
142-
var timer = moment.duration().timer({
143-
}, function() {
144-
// Callback
145-
});
137+
### .isStarted()
146138
139+
```js
140+
let timer = new moment.duration(1000).timer(callback);
147141
timer.start();
142+
timer.isStarted(); // true
143+
timer.stop();
144+
timer.isStarted(); // false
148145
```
146+
This function can be used to see if the timer has been started by the .start() function. If this function is called on a timer that has reached the end of it's duration and does not loop, it will also return false as if the timer has not yet been started.
147+
148+
---
149+
150+
Feel free to [open a new issue](https://github.com/SeverinDK/moment-timer/issues/new) or [create a pull request](https://github.com/SeverinDK/moment-timer/pulls) if you can think of other useful attributes or functions.
151+
152+
---
153+
154+
## Changelog
155+
#### v1.2.1
156+
Updated readme with better documentation and added a new isStarted function.
157+
#### v1.2.0
158+
Added module loading!
159+
#### v1.1.5
160+
Added getDuration and executeAfterWait attribute.
161+
#### v1.1.4
162+
Added isStopped function.
163+
#### v1.1.3:
164+
...
165+
#### v1.1.2:
166+
Fixed stop function. It still had an old unused paused variable instead of the new stopped variable. Fixing this will ensure that stopping and starting the timer will not cause any problems.
167+
#### v1.1.1:
168+
Cleaned up some things, fixed a remainingDuration bug and added an internal clearTimer function.
169+
#### v1.1.0:
170+
Changed setDuration to duration and added actual moment.duration support to it.
171+
Deprecated error message on setDuration will be removed in next release.
172+
#### v1.0.0:
173+
Initial Release.
174+
175+
---
176+
177+
## Contributing
178+
179+
You are always welcome to contribute to this repository. Create your own branch, make the changes you wish to see and create a pull request that we can have a look at. If the changes make sense and the quality of code is good enough, then it will be merged into the master branch so other people can use it.
180+
181+
A full list of contributers for moment-timer.js can be found [here.](https://github.com/SeverinDK/moment-timer/graphs/contributors)
149182
150-
<hr>
183+
---
151184
152-
### Motivation
153-
My motivation for making this script is to prevent any annoyance in the future when working with JavaScript timers. With these tools, I know that I will prevent a lot of the problems I have had through time.
154-
But ofc, the biggest motivation is simply making the idea come alive and enjoying the result. Every completed idea is a new lesson learned!
185+
## License
155186
156-
<hr>
187+
Moment-timer.js is freely distributable under the terms of the [MIT license](https://github.com/SeverinDK/moment-timer/blob/master/LICENSE).
157188
158-
### License
159-
MIT - Go ahead and do whatever you want! I doooon't caaare! ;-)
189+
---
160190
161-
<hr>
191+
[npm-url]: https://npmjs.org/package/moment-timer
192+
[npm-version-image]: http://img.shields.io/npm/v/moment-timer.svg?style=flat
193+
[npm-downloads-image]: http://img.shields.io/npm/dm/moment-timer.svg?style=flat
194+
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat
195+
[license-url]: LICENSE

0 commit comments

Comments
 (0)