Cisco AJAX XMPP Library :: Cisco-Specific Add-ons

Web 2.0 library for XMPP-based Instant Messaging, Availability and Roster Management

Introduction

This module provides a number of Cisco-specific extensions to the Cisco AJAX XMPP Library.

Installation

To install this module, copy the "jabberwerx.cisco.js" file into the same directory that contains "jabberwerx.js" and "jabberwerx.ui.js". Then modify your HTML pages to load "jabberwerx.cisco.js" after "jabberwerx.js" or "jabberwerx.ui.js".

Quick Contacts

Introduction

The quick contacts feature provides support for managing temporary subscriptions to other contacts. This support is provided via a controller (jabberwerx.cisco.QuickContactController) and a model (jabberwerx.cisco.QuickContact). The controller provides methods for subscribing to, and unsubscribing from quick contacts. The model provides a Contact-based reprenstation of a QuickContact, allowing most other features of the Cisco AJAX XMPP Library to operate on QuickContacts as if it were another person in the roster.

Usage

To use QuickContacts, create a QuickContactController:

    var quickCtrl = client.controller.quickContact ||
                    new jabberwerx.cisco.QuickContactController(client);

Once the client is connected, to add a quick contact, call QuickContactController's subscribe(jid) method:

    quickCtrl.subscribe("user-a@example.com");
    var contact = client.entitySet.entity("user-a@example.com");

There should now be an entity for "user-a@example.com" in the client's entitySet. Usually this will be an instance of "jabberwerx.cisco.QuickContact". Now all presence changes for that contact are evented through the standard "resourcePresenceChanged" and "primaryPresenceChanged" events.

To remove a quick contact, call the entity's remove() method:

    contact.remove();

Alternatively, a quick contact can be removed by JID via the QuickContactController's unsubscribe(jid) method:

    quickCtrl.unsubscribe("user-a@example.com");

Once the client disconnects, all quick contacts are removed from the client's entitySet.

Interaction with Roster

The quick contacts feature is meant to supplement the core roster features. As such, certain methods may behave slightly differently to accomodate roster-based contacts:

QuickContactController.subscribe may not always create QuickContact entities. If subscribing to an "observer" roster contact (e.g. a contact that the user does not receive presence for, but that contact receives the user's presence), the existing contact entity is updated to indicate there is also a temporary presence subscription.
QuickContactController.unsubscribe may not always destroy QuickContact entities. If unsubscribing from an "observer" roster contact (e.g. a contact that the user does not receive presence for, but that contact receives the user's presence), the existing contact entity is updated to indicate there is no longer a temporary presence subscription.
Any attempts to subscribe to a durable roster contact (e.g. a contact which the user already has a persistent presence subscription to) are denied with an exception. The reason for the exception is to explicitly inform the user that a QuickContact subscription could not be made. It is up to the developer using the library to check for a roster contact that isn't a 'to' or 'both' subscription before attempting a QuickContactController.subscribe.
Quick contacts can be promoted to roster contacts by adding the quick contact to the user's roster. All temporary subscription data is maintained until the roster contact's persistent subscriptions are established.