Developing server-side applications: injected applications

(Comments about this page to: dfd)

Injected applications can be inserted into an arbitrary web page through a bookmarklet, such as a CSS editor inserted into the page and used to modify the style of the page itself.

To streamline development of injected applications, you can use the Alien library. Alien handles communication between the page and xmpp4moz and avoids IDs/namespace collisions.

All the code that extends Alien resides under Alien.user.

Memoes II is the principal Alien extension. It is a window manager: it permits more injected applications to "live" in the same hosting page inside separate "windows".

Okay. Let's create our hello world injected application. These are the steps.

Drag and drop the following link in your bookmarks toolbar:

Alien Bookmarklet

Let's assume the application is called MyHelloWorld and will be contained in the file myhelloworld.js hosted on http://www.mysite.com/scripts Right click on the bookmarklet you just added -> Properties. In the location textbox, replace YOUR URL (at the end) with the http://www.mysite.com/scripts/myhelloworld.js.

This is how the myhelloworld.js file might look like:

if (!Alien.user.MyHelloWorld) { // Ensures that MyHelloWorld isn't already loaded

  Alien.user.MyHelloWorld = {
      // Here all the code you need ...
  };

 // Here the initialization code. It is inside an anonymous function to avoid
 // polluting the namespace.
 (function() {
     // Some shorthands to avoid repeating the long names.
     // Useless for this short example, but just a tip for longer ones.
     var a = Alien;
     var m = Alien.user.MemoesII;
     var myapp = Alien.user.MyHelloWorld;

     // Let's create the window for our application. The function returns
     // a DIV element where we will put the application content
     var content = m.addMemo("memoesii_MyHelloWorld");

     // Now we can add all we want inside 'content'
     content.innerHTML = "<b>Hello, world!</b>";
 })();
}

Save the file and be sure that the URL you wrote in the bookmarklet points to the file you just created. Now just click the bookmarklet and you should see a window appear inside the web page, with the message "Hello, world!".

This example is trivial, it doesn't even use any collaborative feature. Let's try something more interesting.

Like any other application that exploits xmpp4moz, injected applications can communicate each other using xmpp. Payloads sent by applications are called commands, since they are interpreted by the receiving applications. All collaborative features are based on sending commands/interpreting received commands.

The function Alien.sendCommand(name [, args]) allows you to send commands to connected applications. Example:

Alien.sendCommand("myapp-cmd1");
Alien.sendCommand("myapp-cmd2", {
   x: 77,
   foo: "this is command number two"
});

As you can see, all commands should use a prefix to avoid collisions with other applications living on the same web page. The first line just send a "myapp-cmd1" command. The second one send a command named "myapp-cmd2" with two arguments.

To handle/interpret received commands you have to register a command handler. The function Alien.addCommand(name, handler) register the handler function for the command with name name. Example:

Alien.addCommand("myapp-cmd1", function(cmd) {
   alert('Received command one');
});
Alien.addCommand("myapp-cmd2", function(cmd) {
   var x = Number(cmd.@x);
   var foo = cmd.@foo.toString();

   alert('Received command two with x=' + x + ' and foo=' + foo);
});