Developing server side applications

(Comments about this page to: bard?)

When user "connects" a web page to a conversation with a contact, messages to and from that contact will be forwarded to the web page.

For example, user Alice (alice@server.org) is chatting with contact Bob (bob@server.org). Both load a remote notetaking application in their browsers and "connect" it to the conversation. From this point on, messages generated within the notetaking application in Alice's browser will travel through Alice's XMPP session up to Bob and will be received by the notetaking application in Bob's browser. The reverse is also true.

1. Events upon connection
2. Implementation notes
3. Development notes

Events upon connection

Some of all of the following events are received when the web page is connected. (See the implementation notes below for ways in which they are useful.)

• Last known <presence> of the user, including any <show>, <status>, <priority> etc. child it might have. Example:

<presence>
  <show>away</show>
  <status>back soon!</status>
</presence>

• If connected contact is a multi-user chat, the <presence> stanza used to enter the chat. Example:

<presence to="room@server.org/mynick">
  <x xmlns="http://jabber.org/protocol/muc"/>
</presence>

• An <iq> roster fragment containing information about the contact. Example:

<iq from="alice@server.org/Resource" to="alice@server.org/Resource">
  <query xmlns="jabber:iq:roster">
    <item jid="bob@server.org" name="Bobby"/>
  </query>
</iq>

If the contact is not in the user's roster, the <query> element is empty. Example:

<iq to="alice@server.org/Resource">
  <query xmlns="jabber:iq:roster"/>
</iq>

• Contact's presences, if available (i.e. if user is subscribed to contact's presence). Example:

<presence from="bob@server.org/Resource1"/>

<presence from="bob@server.org/Resource2">
  <show>away</away>
</presence>

If the contact is a multi-user chat, presences are those from the room participants. Example:

<presence from="room@server.org/bob">
  <x xmlns="http://jabber.org/protocol/muc#user"/>
</presence>

<presence from="room@server.org/alice">
  <x xmlns="http://jabber.org/protocol/muc#user"/>
</presence>

Implementation notes

The application running in user's browser receives in <div id="xmpp-incoming"> XMPP traffic coming from contact. In order to be notified when this happens, register a DOMNodeInserted event listener (and optionally send the stanza, already converted to XML, to a handler function). Example:

document.getElementById('xmpp-incoming').addEventListener(
    'DOMNodeInserted', function(event) {
        receivedStanza(new XML(event.target.textContent));
    }, false);

Upon connection, user's presence can be discerned from contact's presence because it lacks a from attribute. Do not rely on temporal sequence to discern between the two.

To know the user's JID, read the from attribute on the initial roster <iq>. Roster <iq> is always sent.

To know the user's nick in a multi-user chat, watch for a <presence> stanza with no from attribute and a <x xmlns="http://jabber.org/procotol/muc">: this is the stanza the user used to enter the multi-user chat. The resource part in the to attribute is the user's nick. Example:

<presence to="room@server.org/usernick">
  <x xmlns="http://jabber.org/protocol/muc"/>
</presence>

When connected to a MUC, what is written in <div id="xmpp-outgoing"> is sent out, then comes back into <div id="xmpp-incoming"> from server as a result of the normal multi-user chat mechanism. When connected to a single contact, what is written in <div id="xmpp-outgoing"> is immediately copied by xmpp4moz into <div id="xmpp-incoming">. Thus, you can use a single model of "send output, react on input" to address both single- and multi-user settings.

XXX describe more techniques to make an application work both in one-on-one conversations and in MUC.

Development notes

To work on remote applications, you will probably need two independent Firefox sessions to simulate at least a user and a contact.

Normally, starting Firefox a second time only opens a new window for the already running Firefox instance. To really start a new instance, first of all create another profile from the profile manager. Start Firefox from the command line with:

$ firefox -ProfileManager

Launch a Firefox instance. Then, from the command line, set the environment variable MOZ_NO_REMOTE to 1 and launch Firefox with another profile. Example below for Linux shell (XXX add one for Windows):

$ export MOZ_NO_REMOTE=1
$ firefox -P other_profile

More information at MozillaZine.