Jabber Web SDK

How to use the Jabber IM UI Components

The Cisco Jabber IM and Presence (CAXL) library offers a set of core classes for initiating and managing IM sessions. The library also offers a set of User Interface components that can be used to rapidly create an IM and Presence interface.
This sample code walks through the basics steps of creating an IM and Presence application using some of the User Interface components provided by the library.

The main controls used in this example are:

These important classes are also used:

In this example, we will create these views and controls and then bind to the necessary events to manage a chat session.

Prerequisites

Before you begin, you need the following:

  • Download the code for this sample.

  • Access to a Cisco Unified Presence Server.

  • The username and password for two accounts on the Cisco Unified Presence Server.

    • If you are using the Sandbox, a username/password set will be emailed to you.

  • The domain name for the Cisco Unified Presence server.

    • For the Jabber shared sandbox, the domain is psdtemea.cisco.com.
    • For your own server, the domain can be determined by examining the administration screens on the CUP server.
      • Cisco Unified Presence Administration > System > Cluster Topology, select Settings in the right pane, and verify the Domain Name value.

  • The BOSH URL for the Cisco Unified Presence server.

    • For the Jabber shared sandbox, the BOSH URL is http://cup02:7335/httpbinding.

Installation and Setup

  1. Download the code for this sample.

  2. Unzip the code onto your local machine.

  3. In the jabberUIDemo.zip file, you will find the following:

    • caxl directory – this is the directory containing the Cisco Jabber IM and Presence Library. You can always find the latest version of this SDK here.
    • *assets directory *– contains stylesheets used by this example.
    • jabberUIDemo.html – this is the file that uses the Jabber libraries and User Interface components to connect and manage a chat session.

  4. To run the sample,

    • Connect to the Jabber shared sandbox VPN or to the network that is connected to your CUP server.
    • Open the jabberUIDemo.html file in your browser.
    • Login with one set of user credentials for your Cisco Unified Presence Server.

How does it work?

The jabberUIDemo.html file is the file that demonstrates how to use the Jabber IM and Presence libraries. We are going to walk through the main sections of the code.

Configuration

The first section of code specifies the values for some of the configuration details we will use.

  • Domain – the domain of your CUP server.
  • httpBindingURL – the BOSH url for your CUP server
  • *unsecureAllowed *– true if plaintext authentication is allowed over unencrypted or unsecured HTTP channels, or false otherwise.
    If you are using the Jabber Shared Sandbox, you can leave these settings unchanged.
    If you are using your own CUP server, please change these settings to match your server.
Code Snippet
Copyvar demo_config = {
    domain: "psdtemea.cisco.com",
    unsecureAllowed: true,
    httpBindingURL: "http://cup02:7335/httpbinding"
}

jabberwerx._config.unsecureAllowed = demo_config.unsecureAllowed;
jabberwerx._config.httpBindingURL = demo_config.httpBindingURL;

Create Object to Hold Tabbed View

The following piece of code creates a tabbed view that displays a welcome message when the user logs in. We will use the sample.IntroView later in the event handlers.

Code Snippet
Copy//create an object to hold our tabbed view
    sample = {};

    //setup up our view
    sample.IntroView = jabberwerx.ui.JWView.extend({
        init: function() {
            this._super();
        },
        destroy: function() {
            this._super();
        },

        createDOM: function(doc) {
            var data = $("<div/>", doc).addClass("jabberwerx intro");

            $("<h2/>").appendTo(data).
                    text("Welcome to Cisco Jabber IM and Presence!");

            return data;
        },

        setTabControl: function(tab) {
            this._super(tab);

            if (tab) {
                tab.label("Welcome");
            }
        }
    }, "sample.IntroView");

    sample.IntroView.mixin(jabberwerx.ui.Tabbable);

document.ready()

Most Cisco Jabber IM & Presence Library applications manipulate the DOM in event callbacks. To ensure these callbacks are done after the DOM is ready, we need to ensure the connect call is performed after the DOM is ready.
So we place the code to create the connection and handle the events in the document.ready event handler.

Code Snippet
Copy$(document).bind("ready", function() {
               ….code to create client and respond to chat events
}

Create the Client, Roster, and Chat Controllers

The following piece of code creates the jabberwerx.Client object, and the jabberwerx.RosterController, and the jabberwerx.ChatController. We pass our client object to the constructors for RosterController and ChatController.

Code Snippet
Copy//create new client
client = new jabberwerx.Client('sampleclient');

//creates roster controller
var roster = client.controllers.roster || new jabberwerx.RosterController(client);

//creates chat controller
var chat = client.controllers.chat || new jabberwerx.ChatController(client);

Create the SelfPresenceView

The next view that we create is the jabberwerx.ui.SelfPresenceView. This view allows the user to set his current presence status. The following piece of code creates the view and then uses jabberwerx.ui.SelfPresenceView.setStatusChoices() to set the list of status choices for each type of status. The .render method is used to render the view and append it to the specified div.

Code Snippet
Copy//create view of your own presence
        var prsView = new jabberwerx.ui.SelfPresenceView(client);

        //set presence choices
        prsView.allowUnavailable = true;
        prsView.setStatusChoices(
                "available",
                prsView.getStatusChoices("available"));

        prsView.setStatusChoices(
                "away",
                prsView.getStatusChoices("away"));

        prsView.setStatusChoices(
                "xa",
                [].
                        concat(jabberwerx._("Extended Away")).
                        concat("PTO"));

        prsView.setStatusChoices(
                "dnd",
                prsView.getStatusChoices("dnd"));

        //append to container div for my presence
        prsView.render().appendTo(".my_presence");
        prsView.update();

Next, we create the jabberwerx.ui.RosterView. The RosterView displays a contact list. We pass the client.entitySet (roster) to the RosterView along with the mode. The mode controls how groups are displayed within the roster. The types of mode are:

jabberwerx.ui.RosterView.groupmode_collapsed
jabberwerx.ui.RosterView.groupmode_expanded
jabberwerx.ui.RosterView.groupmode_single

The RosterView is then rendered and added to the div.my_roster element.

Code Snippet
Copy//create roster view
var rosterView = new jabberwerx.ui.RosterView(client.entitySet,jabberwerx.ui.RosterView.groupmode_expanded );
rosterView.setDefaultGroupingName("default");
rosterView.render().prependTo("div.my_roster");
rosterView.height(400);


//create tabbed view
var tabbedView = new jabberwerx.ui.TabbedView();
tabbedView.render().appendTo("div.my_tabs");
tabbedView.dimensions({width: 525, height: 525});
tabbedView.addTab("introview", new sample.IntroView());

Create the Tabbed View and Display Welcome Message

Next we create the TabbedView and add our sample.IntroView that we created earlier as the first tab.

Code Snippet
Copy       //create tabbed view
var tabbedView = new jabberwerx.ui.TabbedView();
tabbedView.render().appendTo("div.my_tabs");
tabbedView.dimensions({width: 525, height: 525});
tabbedView.addTab("introview", new sample.IntroView());

Show the views when the user logs in

The clientStatusChanged event fires whenever the status of the client changes. In this example, we hide the authentication view and show our tabbedView and other controls when the status changes to jabberwerx.Client.status_connected. When the status changes to jabberwerx.Client.status_disconnected, we hide the tabbedview and display the authenticateView.

Code Snippet
Copyclient.event("clientStatusChanged").bind(function(evt) {
            if (evt.data.next == jabberwerx.Client.status_connected) {
                auth.hide();
                $(".my_client").show();
                tabbedView.show();

                prsView.update();
                rosterView.update();
                tabbedView.update();
            } else if (evt.data.next == jabberwerx.Client.status_disconnected) {
                jQuery.each(tabbedView.getAllTabs(), function() {
                    if (this.id != "introview") {
                        this.destroy();
                    } else {
                        this.activate();
                    }
                });
                tabbedView.hide();
                auth.show();
                $(".my_client").hide();
            }
        });

Respond to the RosterItemSelected event

The following piece of code will run when the user selects a roster item. In this handler, we get the selected contact's id, and then use jabberwerx.ChatController.openSession to open a chat session with the selected contact.

Code Snippet
Copy rosterView.event("rosterItemSelected").bind(function(evt) {
            var item = evt.data.item;
            var entity = item.entity;
            if (entity instanceof jabberwerx.Contact) {
                var id = "chat11:" + entity.jid.getBareJIDString();
                //jabberwerx.ChatController.openSession opens a new session or returns existing session for the passed contact
                var session = chat.openSession(entity.jid);
                var tab = tabbedView.getTab(id);

                if (tab) {
                    tab.activate();
                }
            }
            else {
                alert("selected via " + evt.data.type + ": " + evt.data.item.entity);
                return;
            }

        });

When the chat session is opened, the chatSessionOpened event will fire. In the handler for this event, we add a new tab containing at jabberwerx.ui.ChatView for the new session.

Respond to the tabActivated event

Last event handler in this section is the handler for the tabActivated event. In this handler, we add the code that sets up the Remove contact button to remove the currently selected contact.

Code Snippet
Copy//bind to event that is triggered when a tab is activated
        //set up the remove contact button to remove the currently selected contact
        tabbedView.event("tabActivated").bind(function(evt) {
            var id = evt.data.id;
            $("input.remove_contact_btn").
                    unbind("click").
                    attr("disabled", "true").
                    val("Remove Contact");


            var session = evt.data.content.session;
            if (session) {
                if (session.getEntity() instanceof jabberwerx.Contact) {
                    //activate the remove contact button, add username (remove everything after the @ in the displayname)
                    $("input.remove_contact_btn").
                            removeAttr("disabled").
                            val("Remove " + session.getEntity().getDisplayName().split('@')[0]).
                            unbind("click").
                            click(function() {
                                //remove the contact
                                session.getEntity().remove();
                                chat.closeSession(session.jid);
                                $("input.remove_contact_btn").
                                        unbind("click").
                                        attr("disabled", "true").
                                        val("Remove Contact");
                                tabbedView.removeTab(id);
                            });

                }
            }
        });

Add a Contact

The last section of code in this file handles the click event for the Add Contact button. When the button is clicked, the user is prompted to enter the contact and then we use roster.addContact to add the contact to the roster. The very last line of code initially hides the controls so that only the authentication view is displayed until after the user logs in.

Code Snippet
Copy//when add input button is clicked add contact to roster
        $("input.add_contact_btn").click(function() {
            var contact = prompt("Enter new contact jid: ", "");
            if (contact) {
                var entity = client.entitySet.entity(contact);

                try {
                    roster.addContact(contact);
                } catch(e) {
                    alert("A problem occurred while trying to add the contact " + contact +
                            ".\n Details: " + e.message);
                }
            }
        });


        //hide the chat window initially
        $("div.my_client").hide();

Next Steps

Take a look at the Jabber IM & Presence FAQs.

Next