A practical guide to jMaki Events

Events in jMaki are handled by something called Glue. jMaki Glue is a powerful mechansim for allowing JavaScript components to talk to each other. This document discusses how you can use this mechanism in your web application. There is also a more detailed and lower level article on Glue.

Glue is based on the publish and subscribe mechanism. A publish/subscribe mechanism provides asynchronous communication, decouples the producers from the consumers and it allows a dynamic number of both producers and consumer. This mechanism is used extensivily in messaging systems for example. Generally, we want to be notified when the user interacts with our web appication. In jMaki, user actions result in an event which results in a notification of that event (producer) along with some data (payload). Most of the producers are widgets though a few like dcontainer are consumers. Each widget publishes to a topic or a name that identifies the notification which subscribers may be interested in when an event occurs. One or more consumers may register to listen to each topic. Consumers are generally defined as event handlers in written in JavaScript. This means that each producer sends a notification to a topic based on some user action. The notification includes data identifying the widget, it's arguments and any data value in the widget known at the time the notification was published. Using this mechansim, we avoid tying two widgets together and instead allow any widget to talk to any consumer. Let's look at how to use Glue to receive event notifications in jMaki.

Using Glue

There are several steps to using the Glue mechasim in jMaki and note that it is really just a file with JavaScript code provided by the application developer which is loaded by the jMaki framework.

This is generally done in a file called glue.js file as this file is specified in config.json. If you want to use a different filename then you may do so but don't forget to add that information to config.json so jMaki will load your code. See Glue.html for more information on specifying the glue code.

Connecting the listener to the handler

You will declare the topic you want to listen to and the name of the listener which will handle the notification in the same step. You may declare a listener either programmically or declaritvely. We recommend you use the programtic approach using the jMaki helper API. In glue.js add the following line:

jmaki.subscribe("/jmaki/editor/onSave", "jmaki.listeners.editorListener");

In the example above the glue listener is added to the jmaki.listeners object. The jmaki.listeners object is the recommended namespace for glue listeners but it is not required. In the case of the example above the topic "/jmaki/editor/onSave" is mapped to call the function "editorListener" on the jmaki.listeners object. What this line does is map the topic name to to an event handler. Below is the glue.js file which defines the jmaki.listeners object. In the example below, the handler code simply posts an alert printing the args that were passed.

jmaki.listeners = {
    editorListener : function(args) {
        alert("editor: " + args);

Each widget publishes to a topic based on what the widget developer thinks is an interesting event. That is, what most application programmers would be interested in knowing about. For example, the Dojo editor widgets publishes to a topic when it receives an onSave event. See the widget documentation for the name of the topic a widget will publish to by default. If there are additional events which should be published submit a Request for Enhancment in Issue Tracker in the widgets project and we will do our best to add it. The topic names in the widgets are simply a default and each topic name can be over written. The widget documentation also describes the payload that is published on the topic. Generally, the widget id, widget args and current value are in the payload. We will see examples of this later in this article.

Mapping the widgets to the handlers

This is done indirectly in jMaki when you actually put the widget declaration in you page. If you are happy to use the default topic name then all you need to do to listen to a topic is to add the listener using the jmaki.subscribe call in glue.js and you are done. If you want to instead specify the topic name then you need to do that when you declare the widget on your page. This is useful if you have two or more of the same widget on the page.

If you are using JSPs and want to specify the name of the topic for the editor widget then you would do the following:

 <a:widget name=dojo.editor args="{topic : '/myeditor'}"/>

If you are using PHP and want to specify the name of the topic for the editor widget then you would do the following:

  <?php  addWidget('dojo.editor',  null, null, "Edit this data", 'myeditor'); ?>

The args parameter will pass this value to the widget and therefore over write the default topic name in the widget. The glue code will need to match the new name of the topic and so need to look like:


In the example above, you see that that the widget declaration changes based on the lanuage you choose to use to implement your web application. However, notice that the glue code for both applications is identical.

Getting data from the widget

The getwidgetdata sample is a complete example of getting data from the widget in the glue code. Let's look at part of that glue code here.

jmaki.listeners.editorListener = function(args) {
    var contentValue = args.value;
    var contentId  = args.id;
    if ( typeof contentValue != 'undefined' ) {
        // send data back to server
         jmaki.doAjax({method: "POST",
                               url: "Service.jsp",
                               content: {message: contentValue },
                               callback: function(_req) {
                                   // handle any errors

In the glue code above, args is the payload with data about the widget. All widgets publish to a topic some data about the widget. The widget id and value are the minimum published but usually the widget args are also published. The editor widget publishes to a topic each time a save operation is performed. Usually this is a result of the user clicking on the save icon. The handler gets the value of the widget, in this case the contents the user has entered, and sends that back to the server where additional processing can happen.

Debugging Glue code

Looks easy so far but what if it doesn't work? How do you know if the something was published and what topic it was published to? If a notification went out then what was published to a topic?

Luckily there is a way of seeing the topics and payloads that are published on the topic. To turn on the console simply go to the jmaki.js file (this is compressed so a little hard to read). Set the this.debugGlue and debug varialbles to true. Next time you run the application, a console will appear in the lower right corner. All debug messages will be written to this console. The Glue code writes out the nam of the topic and the contains of the payload to the debug console. It will also indicate if the it thinks there is a listener for a topic. If jMaki doesn't think there is a listener then check the topic name as that is the most common mistake when working with Glue.

You also have the option to copy in the Yahoo logger widget which is setup to display the debug messages when debuggig is turned on. Just add that widget to your page and run your application.

Loading Glue code

As mentioned, Glue code is by default located in the glue.js file. The jMaki framework loads glue.js and any glue file specified in the config.json file and makes it available to all pages in the appliation. Therefore, each handler you write is available to code in every page in your application. You may wish to limit access to some handlers or provide handlers to only a small number of pages in your application. To do this you will need to update the config.json file.

 'config': {
   'version': '.9',
   'glue' : {
        'includes': [
         {url : '/basic.jsp' , lib : '/basic-glue.js'},
         {url : '/page2.jsp' , lib : '/page2-glue.js'},
         {url : '*' , lib : '/system-glue.js'}

In the above example, the file basic-glue.js is loaded in the page /basic.jsp. The file page2-glue.js is loaded in the page /page2.jsp and all urls will include system-glue.js Glue includes are all from the web root "/"

Further Reading

The jMaki sample getwidgetdata is a complete example on how to use glue in jMaki. In that example you will see how to get data from the widget using a handler and also pass the data to the server and on to another page in the application.

The Glue mechanism is based on publish and subscribe mechanism implemented in jMaki.

Fun with jMaki: Using the Yahoo Geocoder service with the Dojo Combobox shows some of the potential of jMaki Glue to work as a controller.