Babble Plone chat client

Introduction

Babble is an instant messaging service for Plone. It consists of babble.client as the Plone front-end client and babble.server, a Zope2 messaging service, as the backend chat service.

The client consists of an Online contacts portlet with which you can initiate new chats. Chat sessions occur in modal dialog chatboxes which make use of JQuery and Ajax polling to provide seamless, real-time messaging. During inactive periods, the polling interval gradually becomes longer until it reaches a specific (configurable) maximum polling interval.

Communication between the client and server is achieved with JSON packets sent via XML-RPC. The XML-RPC configuration values are stored in the portal_chat tool which can be found in the root of the Plone site inside the ZMI (Zope management interface). See the Portal Chat Tool for a breakdown of its configuration values.

On the server side (backend), a Chat Service object needs to be created, which will then act as a messaging server. Refer to the Chat Service section on how to create the Chat Service.

../_images/babble_diagram.png

Features

  • Remembers open chat windows on page reload
  • Chat windows can be minimized
  • New messages automatically opens chat window
  • An ‘online users’ portlet provides a list of currently online users
  • Configurable polling intervals
  • Clickable URLs recieved via chat messages
  • Requests to the messaging service are password authenticated
  • Can be integrated with the ActionBar of actionbar.panel
  • Can run on a different server than the messaging service

Compatibility

Tested to work with Plone 3.3 and Plone 4

Configuration

Quickly setting up a demonstration

There is a demo egg available on Plone.org and pypi, with which you can quickly set up a new Babble configured Plone 4 site for demonstration purposes.

See the README of babble.demo, or the section titled Setting up a quick chat demo, in this document, for instructions on how to set it up.

If you however want to configure the system yourself, then read the next section.

Manual configuration

Chat Service

babble.client needs a running zope instance configured with the babble.server chat service.

babble.server is a pure Zope2 application and the Chat Service object that it provides, should be added in the Zope Management Interface (ZMI). It must be created in the Zope root of your Zope instance, otherwise it won’t work.

NOTE: It’s strongly recommended that you run the babble.server messaging service in a separate server or Zeo Client. Running the client and server in the same instance sometimes causes the browser (probably Zope’s ZPublisher) to become unresponsive.

../_images/Screenshot-2.png

Portal Chat Tool

The client is configured via the portal_chat tool in the ZMI:

  • Service name: This is the name of babble.server‘s ‘Chat Service’ object that you created in the Zope root of the Zope instance you will be using as your message server.
  • The chat service is on the same machine: Check this if the chat service is created on the same Zope/Plone instance and is therefore not running on a different server. This will disable XML/RPC and instead use direct method calls. Note that it’s recommended to run your Chat Service in it’s own ZODB, so if you want to run it in the same instance, consider mounting a separate ZODB.
  • Hostname or relative path: If the Chat Service is on a different server, then specify the hostname here. Otherwise, if the Chat Service is on the same server and not in the Zope root, then specify the path to it here.
  • Port: This is the port number of the server running the ‘Chat Service’. Only applicable when the Chat Service is on a different server.
  • Username: This is the username of the Zope user that you used to create the ‘Chat Service’.
  • Password: This is the password of the Zope user that you used to create the ‘Chat Service’.
  • Maximum polling interval: The time interval between polls to the <em>babble.server</em> chatservice starts off at a specified minimum value and then gradually increases to a specified maximum value during periods where there isn’t any chat activity. Specify the minimum polling interval value here.
  • Minimum polling interval: The time interval between polls to the <em>babble.server</em> chatservice starts off at a specified minimum value and then gradually increases to a specified maximum value during periods where there isn’t any chat activity. Specify the maximum polling interval value here.
../_images/Screenshot-4.png

How do I start using it?

Make sure that babble.client is installed via Plone’s control panel, or the portal_quickinstaller tool in the ZMI (Zope management interface).

In Plone, go to the portlets manage page. In the dropdown of addable portlets, there should now be a new types of portlet, Online contacts.

Add this portlet. If you have more than one person currently using the site, you should see them appear in this portlet.

Note: When you are running your portal_javascripts registry is in debug mode (or when you are running ./bin/instance fg in Plone4), then the Online contacts portlet will show all the registered users, and not just the online ones, to make debugging easier. As of version 1.3.2, to avoid confusion, this is no longer the case.

Simply click on the user in the portlet, and a chatbox will appear in the bottom right of the page.

Now start babbling!

../_images/Screenshot-1.png

Troubleshooting

1. I get a ‘connection error’ message inside the chat window

The ‘connection error’ message happens whenever the chat client (babble.client) cannot communicate with the chat server (babble.server).

This is usually because the chat server is not running (i.e when you restart the zope server).

Check that the chat server is running and that your settings in the portal_chat tool are correct.

2. Plone freezes or locks up completely and I have to restart the instance before this goes away

This happens when there is only one Zope instance that has both the chat client and the chat server running in it.

The chat client ‘polls’ the chat server to find new messages. If the server stops responding because it is overwhelmed or because it is restarted, then the browser hangs forever as it waits for a response, even after Zope was restarted.

The best solution is to run the chat server in a separate dedicated Zeo instance not being used for anything else.

Make sure to change the port in the portal_chat tool to point to this Zeo instance.

A second thing you can do, is to increase the minimum poll time in the portal_chat tool, for example from 3000 ms to 6000 ms or more.

This will of course mean that messages can take longer to appear for the conversation partners.

3. Nothing happens when I click on a contact’s name in the portlet

Check the debug output on Firebug for any clues. If you get messages that something is undefined, such as “jQuery is not defined”, then the ordering in portal_javascripts is probably wrong.

chat.js, jquery.ba-dotimeout.min.js, jquery.cookie.js and quicksearch.js must all come after jquery.js.

In Plone 3, you might have collective.js.jquery installed, in which case a newer jQuery version is installed and jquery.js is disabled. Make sure that the newer library is before the above mentioned scipts.

4. Babble doesn’t work with deliverance or collection.xdv

That is because deliverance and collective.xdv need to be told to ignore the ajax calls that Babble makes.

For collective.xdv, add the following to the Unstyled paths textbox in the @@xdv-settings configuration view (found via Site setup):

^.*/@@babblechat.*$
^.*/@@render_chat_box

For deliverance, you’ll need proxy declarations similar to the following in your rules.xml file:

<proxy path="regex:^.*/@@babblechat.*$">
    <dest href="http://localhost:8080/VirtualHostBase/http/localhost:5099/MySite/VirtualHostRoot/" />
</proxy>

<proxy path="regex:^.*/@@render_chat_box">
    <dest href="http://localhost:8080/VirtualHostBase/http/localhost:5099/MySite/VirtualHostRoot/" />
</proxy>

Where MySite is your Plone site’s name, running on 8080 and the deliverance proxy on 5099.

5. When I chat, a different user’s name appears as the message author in the chat box. When I reload the page, the problem goes away.

Babble makes use of a dynamically generated javascript file named chat.js. Make sure that this file is not cached or merged, otherwise this problem can occur. Go to the portal_javascripts tool in the Zope Management Interface (ZMI) and uncheck those two options for this file.