|
| 1 | +# jQuery Tiny Pub/Sub |
| 2 | + |
| 3 | +A really, really, REALLY tiny pub/sub implementation for jQuery. |
| 4 | + |
| 5 | +_(see the [original gist](https://gist.github.com/661855))_ |
| 6 | + |
| 7 | +## Getting Started |
| 8 | +Download the [production version][min] or the [development version][max]. |
| 9 | + |
| 10 | +[min]: https://raw.github.com/cowboy/jquery-tiny-pubsub/master/dist/tiny-pubsub.min.js |
| 11 | +[max]: https://raw.github.com/cowboy/jquery-tiny-pubsub/master/dist/tiny-pubsub.js |
| 12 | + |
| 13 | +Example usage: |
| 14 | + |
| 15 | +```html |
| 16 | +<script src="jquery.js"></script> |
| 17 | +<script src="dist/tiny-pubsub.min.js"></script> |
| 18 | +<script> |
| 19 | +// Creates a "named" logging function. |
| 20 | +function createLogger(name) { |
| 21 | + return function(_, a, b) { |
| 22 | + // Skip the first argument (event object) but log the name and other args. |
| 23 | + console.log(name, a, b); |
| 24 | + }; |
| 25 | +} |
| 26 | +
|
| 27 | +// Subscribe to the "foo" topic (bind to the "foo" event, no namespace). |
| 28 | +$.subscribe('foo', createLogger('foo')); |
| 29 | +// Subscribe to the "foo.bar" topic (bind to the "foo" event, "bar" namespace). |
| 30 | +$.subscribe('foo.bar', createLogger('foo.bar')); |
| 31 | +// Subscribe to the "foo.baz" topic (bind to the "foo" event, "baz" namespace). |
| 32 | +$.subscribe('foo.baz', createLogger('foo.baz')); |
| 33 | +
|
| 34 | +// Publish arbitrary values. |
| 35 | +$.publish('foo', [1, 2]); |
| 36 | +// logs: |
| 37 | +// foo 1 2 |
| 38 | +// foo.bar 1 2 |
| 39 | +// foo.baz 1 2 |
| 40 | +
|
| 41 | +$.publish('foo.bar', [3, 4]); |
| 42 | +// logs: |
| 43 | +// foo.bar 3 4 |
| 44 | +
|
| 45 | +$.publish('foo.baz', [5, 6]); |
| 46 | +// logs: |
| 47 | +// foo.baz 5 6 |
| 48 | +
|
| 49 | +$.unsubscribe('foo.bar'); |
| 50 | +$.publish('foo', [7, 8]); |
| 51 | +// logs: |
| 52 | +// foo 7 8 |
| 53 | +// foo.baz 7 8 |
| 54 | +</script> |
| 55 | +``` |
| 56 | + |
| 57 | +## Documentation |
| 58 | +_Note: Ignore the first argument passed to your subscribed callbacks (the jQuery event object)._ |
| 59 | + |
| 60 | +_Another Note: [Previous versions](https://gist.github.com/661855/2c518edd29b744d04bff55ec9a2a5d12afe41595) (v0.4+) were written in an attempt to remove the first argument and create a more future-proof API, but unfortunately this resulted in much less elegant, larger and slower code. The point of this plugin is to be TINY, to be used in situations where only size (not performance or usability) is the primary concern (tweets, code golf, etc).**_ |
| 61 | + |
| 62 | +I frequently see comments about how jQuery's events system has unnecessary overhead that precludes it from being used as the core of a Pub/Sub implementation. The jQuery events system is tried-and-true, having been architected to be both fast and robust, and the vast majority of users of this plugin should never encounter any kind of performance issues. |
| 63 | + |
| 64 | +Because this plugin's `$.subscribe`, `$.unsubscribe` and `$.publish` methods all use the jQuery [.on()](http://api.jquery.com/on/), [.off()](http://api.jquery.com/off/) and [.trigger()](http://api.jquery.com/trigger/) methods internally, those methods' complete signatures are available to you. |
| 65 | + |
| 66 | +You can use [namespaces](http://docs.jquery.com/Namespaced_Events) for more control over unsubscribing and publishing. |
| 67 | + |
| 68 | +Just use this handy terminology guide (jQuery events term → Pub/Sub term), and everything should make sense: |
| 69 | + |
| 70 | + * on → subscribe |
| 71 | + * off → unsubscribe |
| 72 | + * trigger → publish |
| 73 | + * type → topic |
| 74 | + |
| 75 | +In addition, should you need it, these methods are fully compatible with the [jQuery.proxy()](http://api.jquery.com/jQuery.proxy/) method, in case you not only want more control over to which context the subscribed callback is bound, but want to be able to very easily unsubscribe via callback reference. |
| 76 | + |
| 77 | +Regarding performance: If at some point, your application starts processing so many messages that performance issues start to develop, you could always write a replacement "jQuery Not-So-Tiny Pub/Sub" plugin with the same API and just drop it in as a replacement to this plugin. But keep in mind that you'll also need to add in the aforementioned features, too. |
| 78 | + |
| 79 | +## Release History |
| 80 | +2013-01-29 - v0.7.0 - First official release. |
0 commit comments