├── README.markdown ├── poll.js └── poll.min.js /README.markdown: -------------------------------------------------------------------------------- 1 | # PollJS # 2 | PollJS is a lightweight wrapper for the JavaScript Interval and Timer methods. 3 | 4 | # Features # 5 | * Lightweight (~1.5k) 6 | * Supports maximum attempt limits, fallbacks, and incremental interval times 7 | * Compatible with all major browsers (Tested on Firefox 3.6, Firefox 4.0, Firefox 5.0, Fireofox 6.0, Chrome 9, Opera 11, IE7, IE8, IE9) 8 | * Independant of all third party libraries, but plays nice with all of them 9 | 10 | # Getting Started # 11 | PollJS is simple to use. Every time you want to start an interval or timer, simply call the `Poll.start` method, and give it the appropriate configuration values: 12 | 13 | Poll.start({ 14 | name: "update_users", 15 | interval: 1500, 16 | action: function(){ 17 | alert("Updated!"); 18 | } 19 | }); 20 | 21 | To stop the interval, simply pass your defined name to the `Poll.stop` method: 22 | 23 | Poll.stop("update_users"); 24 | 25 | You can also stop an interval from within it's action by returning false: 26 | 27 | Poll.start({ 28 | name: "update_users", 29 | interval: 1500, 30 | action: function(){ 31 | alert("Updated!"); 32 | return false; // Kill this poller. 33 | } 34 | }); 35 | 36 | # Configuration Options # 37 | PollJS accepts several configuration options: 38 | 39 | name: The defined name for your poller. This is the unique ID used to stop it in the future. 40 | action: This is the method to be executed whenever you tell it to happen. 41 | interval: This is how often the action will be run. Equivalent to calling the native `setInterval` function. 42 | start: This is when the action is first run. Equivalent to calling the native `setTimeout` function. 43 | increment: This works in conjunction with the 'interval` config option. It tells PollJS to increase the time between intervals by a particular value. 44 | attempts: This is the maximum number of attempts to be made. 45 | fallback: If the maximum number of attempts is reached, PollJS will execute a fallback action if you specify one. 46 | 47 | At least one of `start` or `interval` is required to set up a poller. If both are omitted, PollJS will raise an exception. 48 | 49 | # Advanced Polling # 50 | You can use all of the PollJS configuration options at once: 51 | 52 | Poll.start({ 53 | name: "check_print_job", 54 | action: function(){ 55 | //do some code here 56 | }, 57 | start: 5000, // Start this poller 5 seconds from now 58 | interval: 500, // Re-run the poller every 0.5 seconds 59 | increment: 200, // Increase the poll interval by 200ms every time it runs 60 | attempts: 5, 61 | fallback: function(){ 62 | alert("Fallback"); 63 | } 64 | }); 65 | 66 | In the example above, all three timing options are provided, and play nicely together. Assuming the poller isn't killed, it will run the action 5 times, at increasingly longer intervals. 67 | 68 | # Next Steps # 69 | * Figure out how to test this 70 | * Add examples 71 | 72 | # Pull Requests # 73 | To make a pull request, please do the following: 74 | 75 | * Mention what specific version of PollJS you were using when you encountered the issue/added the feature. This can be accessed by doing `Poll.version` in a debugger console 76 | * Provide a [pastie](http://pastie.org/) or [gist](https://gist.github.com/) that demonstrates the bug/feature 77 | * Make sure to update the minified version of the source 78 | * Do **not** modify the `Poll.version` attribute. I will modify that manually when merging the request 79 | 80 | # Disclaimer # 81 | This code is provided with no warranty. While I strive to maintain backwards compatibility, the code is still under active development. As this is the case, some revisions may break compatibility with earlier versions of the library. Please keep this in mind when using PollJS. 82 | 83 | # Copyright and Licensing # 84 | Copyright (c) 2011 Mike Trpcic, released under the MIT license. 85 | -------------------------------------------------------------------------------- /poll.js: -------------------------------------------------------------------------------- 1 | var Poll = { 2 | "version": "0.3", 3 | "start": function(config){ 4 | action = config.action; 5 | config.internal_action = config.action; 6 | config.action = function(){ 7 | Poll.util.attempts(config.name, config.internal_action); 8 | }; 9 | if(config.start){ 10 | if(config.interval){ 11 | if(config.increment){ 12 | Poll.timers[config.name] = {"type": "timeout", "config": config, "attempts": 0, "value": setTimeout(function(){ 13 | Poll.util.timeout(config.name, config.action, config.interval); 14 | }, config.start)}; 15 | } else { 16 | Poll.timers[config.name] = {"type": "timeout", "config": config, "attempts": 0, "value": setTimeout(function(){ 17 | config.action(); 18 | Poll.timers[config.name]["value"] = setInterval(config.action, config.interval); 19 | Poll.timers[config.name]["type"] = "interval"; 20 | }, config.start)}; 21 | } 22 | } else { 23 | Poll.timers[config.name] = {"type": "timeout", "config": config, "attempts": 0, "value": setTimeout(config.action, config.start)}; 24 | } 25 | } else if(config.interval){ 26 | if(config.increment){ 27 | Poll.timers[config.name] = {"type": "interval", "config": config, "attempts": 0, "value": setTimeout(function(){ 28 | Poll.util.timeout(config.name, config.action, (config.interval + config.increment)); 29 | }, config.interval)}; 30 | } else { 31 | Poll.timers[config.name] = {"type": "interval", "config": config, "attempts": 0, "value": setInterval(config.action, config.interval)}; 32 | } 33 | } else { 34 | throw "PollJS: You need to define a start, an interval, or both."; 35 | } 36 | }, 37 | "util": { 38 | "attempts": function(name, fn){ 39 | var ret, instance = Poll.timers[name]; 40 | Poll.timers[name].attempts += 1; 41 | ret = fn(); 42 | 43 | if(ret === false){ 44 | Poll.stop(name); 45 | } 46 | 47 | if(instance.config.attempts){ 48 | if(instance.attempts == instance.config.attempts){ 49 | Poll.stop(name); 50 | instance.config.fallback(); 51 | } 52 | } 53 | }, 54 | "timeout": function(name, fn, start){ 55 | var time, config = Poll.timers[name].config; 56 | time = (start + (config.increment || 0)); 57 | Poll.timers[name].value = setTimeout(function(){ 58 | Poll.util.timeout(config.name, fn, time); 59 | }, time); 60 | Poll.timers[name].type = "timeout"; 61 | fn(); 62 | } 63 | }, 64 | "stop": function(name){ 65 | var instance = Poll.timers[name]; 66 | if(instance.type == "interval"){ 67 | clearInterval(instance.value); 68 | } else { 69 | clearTimeout(instance.value); 70 | } 71 | }, 72 | "timers":{} 73 | }; 74 | -------------------------------------------------------------------------------- /poll.min.js: -------------------------------------------------------------------------------- 1 | var Poll={version:"0.3",start:function(a){action=a.action;a.internal_action=a.action;a.action=function(){Poll.util.attempts(a.name,a.internal_action)};if(a.start){if(a.interval){if(a.increment){Poll.timers[a.name]={type:"timeout",config:a,attempts:0,value:setTimeout(function(){Poll.util.timeout(a.name,a.action,a.interval)},a.start)}}else{Poll.timers[a.name]={type:"timeout",config:a,attempts:0,value:setTimeout(function(){a.action();Poll.timers[a.name]["value"]=setInterval(a.action,a.interval);Poll.timers[a.name]["type"]="interval"},a.start)}}}else{Poll.timers[a.name]={type:"timeout",config:a,attempts:0,value:setTimeout(a.action,a.start)}}}else if(a.interval){if(a.increment){Poll.timers[a.name]={type:"interval",config:a,attempts:0,value:setTimeout(function(){Poll.util.timeout(a.name,a.action,a.interval+a.increment)},a.interval)}}else{Poll.timers[a.name]={type:"interval",config:a,attempts:0,value:setInterval(a.action,a.interval)}}}else{throw"PollJS: You need to define a start, an interval, or both."}},util:{attempts:function(a,b){var c,d=Poll.timers[a];Poll.timers[a].attempts+=1;c=b();if(c===false){Poll.stop(a)}if(d.config.attempts){if(d.attempts==d.config.attempts){Poll.stop(a);d.config.fallback()}}},timeout:function(a,b,c){var d,e=Poll.timers[a].config;d=c+(e.increment||0);Poll.timers[a].value=setTimeout(function(){Poll.util.timeout(e.name,b,d)},d);Poll.timers[a].type="timeout";b()}},stop:function(a){var b=Poll.timers[a];if(b.type=="interval"){clearInterval(b.value)}else{clearTimeout(b.value)}},timers:{}} --------------------------------------------------------------------------------