Entourage MQ

Entourage MQ provides a simple to use publish/subscribe messaging system for HTML/JavaScript applications, empowering event-driven UI development in the web browser. MQ also provides facilities for wiring remote service (Ajax) requests to messages, which allows a client application to seamlessly interact with server-side services in the same message-oriented architecture.

In an Entourage MQ application, there are two primary entities you will deal with - messages and listeners. The following example shows how to use the $MQ API to create a message and a listener that will subscribe to that message. Click the button below to publish a message, and notice the JavaScript alert that appears once the message is received:

<input type="button" onclick="$MQ('l:my.message');" value="Send Message"/>
<script>
$MQL('l:my.message', function(msg) {
  alert('Got it!');
});
</script>

Messages consist of three main attributes:

• Name
• Scope
• Payload

The message name is simply a string that identifies the message. A message can also have a scope attribute, which means that only listeners that share that same scope will be able to receive that message. The message payload is a JavaScript object that contains any data associated with a message - a username and password, a set of products… anything and everything. Let's expand our last example to make use of these features:

<input type="button" onclick="sendMessage()" value="Send Message"/>
<script>
function sendMessage() {
  $MQ({
    name: 'l:example2',
    scope: 'myscope',
    payload: {
      quotation: 'Do, or do not.  There is no try.'
    }
  });
}
 
$MQL('l:example2', function(message) {
  alert("You won't see me, since I don't specify scope.");
});		
 
$MQL('l:example2', function(message) {
  alert("Yoda says: "+message.payload.quotation);
},{scope:'myscope'});
</script>

Listeners have the following primary attributes:

• A pattern, which is either a message name to listen for, or a regular expression that will match multiple message names
• A function that will be called when the listener's pattern is satisfied by a message
• A scope in which to listen for messages.

In the preceding examples, we learned how to create listeners that subscribe to a specific message, but let's see how we might listen for a group of messages using a JavaScript RegExp.

<input type="button" onclick="sendMessages()" value="Send Messages"/>
<script>
  function sendMessages() {
    $MQ('l:count.increment');
    $MQ('l:count.alsoincrement');
  }
 
  var count = 0;
  $MQL(/l:count*/, function(message) {
    count++;
    alert(count);
  });
</script>

In addition to standard message listeners, you can also create “interceptors”, which process messages before they are received by message listeners. Interceptors have the same properties as listeners, but interceptors can cancel the delivery of a message by returning true as the result of the callback function. Interceptors are executed in the order in which they were added, following a similar convention to Java Servlet filters.

Interceptors can be useful for message payload manipulation for internationalization or any other cross-cutting concern that might require filtering messages. Let's take a look at how the message interceptor works.

<input type="button" onclick="interceptDemo()" value="Send Message"/>
<script>
  function interceptDemo() {
    $MQ({
      name:'l:interceptme',
      payload: {
        foo:'bar'
      }
    });
  }
 
  $MQI('l:interceptme', function(message) {
    message.payload.foo = 'Intercepted!'
  });
 
  $MQL('l:interceptme', function(message) {
    alert(message.payload.foo);
  });
</script>

Integrating server-side data services is a common task in a Rich Internet Application like the ones you will create with Entourage, so Entourage MQ provides a number of options for interacting with back end services:

• Manual Ajax calls from an $MQL function
• Registering an Ajax URL via $MQR
• Communicating with an Appcelerator Service Broker
• Communicating with Ruby on Rails services that respond with JSON

During development or prototyping, it is sometimes advantageous to 'stub out' remote services to allow for the parallel development of UI and remote services. This is accomplished by listening for remote message calls and mocking up a response with $MQL and $MQ, respectively.

  //Listen for a request to a remote service
  //that is not yet implemented
  $MQL("r:get.foos.request", function(message) {
    //send a mock response message that contains
    //temporary test data in the format you expect
    $MQ("r:get.foos.response", {foos:[ {bar:'foobar'}, {bar:'foobar'} ]});
  });

If the real service returns data in the same format, this stub service can simply be deleted when the real data becomes available.

All this sound cool? That's because it is! For more information on using Entourage MQ, check out our JavaScript API.