jQuery wrapper for postal.js
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



A jQuery plugin wrapper for the postal.js in-memory service bus.


  • demo - a small one-page demo application that demonstrates how the plugin works
  • src - the plugin source code


The general API is very straight-forward. There are three functions that can be called on a jQuery object to wire up postal.js:

$([selector]).pub();    // publish messages
$([selector]).sub();    // subscribe to messages
$([selector]).unsub();  // unsubscribe to messages


.pub() accepts an object hash in the following form:

  'message.name': function () {
    return 'data to be placed on the bus';

The jQuery object may publish as many messages as you want by adding additional properties to the object hash.

A jQuery object that publishes messages must also specify the DOM event on on which publication will be triggered. This is accomplished by calling .on() on the return value of .pub(), and specifying an event name (e.g., 'click') and an optional boolean parameter that indicates whether the even propagation should be muted after publication.

In this example, a form with id #new-friend will publish the event friend.save when it is submitted, and the submit event will cease propagation after the message is published.

  'friend.save': function () {
    var $text = $(this).find('[name="new-friend"]');
    var friendId = $text.attr('data-id') || $('#friends li').length + 1;
    return {
      id: friendId,
      name: $text.val()
}).on('submit', true);

Note that in the function that constructs the bus data for the friend.save event, the value of this is the element that actually triggered the event (in this case, the form element).


Like .pub(), .sub() also accepts an oject hash as its sole argument, in the form:

  'event.name': function (data) {
    //do something with data

The jQuery object may have any number of listeners, one per property of the object hash.

The listener functon accepts a single argument, data, which is the object placed on the message bus by the publisher.

In the following example, a ul tag with id #friends is listening for the friend.save event, and adding to (or updating) its child li elements as appropriate when the new friend data is received.

  'friend.save': function (data) {
    var $ul = $(this);
    var $li = $ul.find('li[data-id="' + data.id + '"]');
    if ($li.length) {
    } else {
        .attr('data-id', data.id)

The value of this, as in the .pub() example, is the jQuery object onto which the listener is 'attached'.


The .unsub() function accepts a single argument -- the name of the message to which a jQuery object is subscribed -- and unsubscribes that object from any additional publications of the message.

In this example, a hidden p tag with id #some-lorem subscribes to the friend.save message. When the message is handled, the paragraph is displayed, and the jQuery object immediately usubscribes from the message.

  'friend.save': function (data) {
      //only execute this once