Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

jQuery wrapper for postal.js

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 demo
Octocat-spinner-32 src
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README.md
Octocat-spinner-32 license.md
README.md

postaljs-jquery

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

Contents

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

Usage

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()

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

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

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.

$('#new-friend').pub({
  '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).

.sub()

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

$().sub({
  '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.

$('#friends').sub({
  'friend.save': function (data) {
    var $ul = $(this);
    var $li = $ul.find('li[data-id="' + data.id + '"]');
    if ($li.length) {
      $li.text(data.name);
    } else {
      $('<li></li>')
        .attr('data-id', data.id)
        .text(data.name)
        .appendTo($(this));
    }
  }
});

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

.unsub()

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.

$('#some-lorem').sub({
  'friend.save': function (data) {
    $(this).toggle('slow')
      //only execute this once
      .unsub('friend.save');
  }
});
Something went wrong with that request. Please try again.