So I actually wrote this plugin almost six months ago, but a few weeks
ago I fleshed it out for use at work. The main external change was a
change in the order of the arguments to simplify the code. And the
main internal change was moving the structure of the timer tracking
code to more closely mimic jQuery's internal event module. There
wasn't anything wrong with the way it was written before, but this
way, the code will appear more friendly for people trying to hack it
in the future who are already familiar with hacking jQuery.
Anyways, the main point of this code is concise definitions of
interval-ed events. For a practical example:
$("input").keypress(function() {
$(this).stop("autocomplete").once(250,"autocomplete",function() {
// provide a list of values to autocomplete with
});
});
For another practical, though slightly more trivial, example:
$('p.clock').every(1000, function() {
this.innerHTML = // The time right.... now.
});
The example will "do something" after someone has typed something but
only if no keys have been pressed for 250 milliseconds. This allows
for dynamic type searching without complicated timing and clearing of
timeouts in your code. The second example is a simple clock. The
implementation may vary, but the principle is the same. One additional
feature is the concept of labels. Labels allow you to define certain
events to be in a certain namespace which can be more finely
controlled. In this way, the above autocomplete example could operate
on the same element while another timer sequence is occuring and
because they have different labels, they could be stopped and
controlled independent of each other without any complicated global
variable nonsense.
The level of control of stopping events employs labels. Calling $
(this).stop() cancels any and all interval and timeout events attached
to that element. $(this).stop('label') will stop any and all events
with the label 'label' and $(this).stop('label',fn) will only stop a
certain event if it is of that label name and calls the provided
function. This allows for both broad and fine-grained event control.
So, as per usual, I've left the documentation fairly sparse and this
post will probably have to suffice until I stop being lazy.
The functions I've added to jQuery are once, every, and stop.
once takes three arguments: timeout, label, and function. label is
optional and will become a string representation of the timeout if not
specified. It will be called once in timeout milliseconds.
every takes four arguments: timeout, label, function, and times. label
is again options and defaults to the timeout value. times is also
optional and becomes unbounded if unspecified. times is used to limit
the number of times an event occurs.
stop takes two arguments: label, and function. Both are optional and
if neither is provided, all events on that DOM element are stopped. If
the label is provided without a function all events with that label
are stopped. Conversely, if a function is provided but no label, all
the events calling that function, regardless of label, are stopped.
Finally, if both are provided, they are both used to filter down to
stop that event.
The few times I've used these methods, my timer based methods have
become invariably more readable and more compact. Enjoy, if you must.
-blair
