Using Caucus Chat

Using Caucus Chat
(Last revised 5 November 2004.)

I. Introduction
The Caucus Chat Tool is an optional "add-on" product for the basic Caucus collaboration package. Follow the link for more information, including how to download a copy.
This document describes how to install the Chat Tool, and how to invoke it from within Caucus. If users have any difficulties getting the chat tool to start, see Diagnosing Chat Problems.
II. Installation
Follow the steps below to install the chat tool module:

Make sure Java is installed. The chat tool requires that your Caucus server has a Java virtual machine (aka "run-time-environment") installed, version 1.3 or higher. No special location is required, Caucus just needs to know where Java can be found.
You can download Java (for Linux and Solaris servers) from java.sun.com -- or more directly from java.sun.com/j2se/1.4.1/download.html. For other platforms (e.g. HP-UX, AIX, BSD) see the platform vendor pages for information.

Choose a port number. The chat tool requires its own TCP/IP port number. The default value is 12468, but you can use any (unused) port.
More importantly, if your server lives behind a firewall, and you have "outside" users who will want to use the chat tool, then you will need to have your network administrator open up that port. So you should involve him or her in picking an appropriate port number.
If you have more than one installation of Caucus running on the same server (e.g. multiple Caucus virtual hosts), and you want to run chat in each, you will need to give each one a different port number.

Install the software. CaucusCare will send you a file mod_chat.tar that contains the chat software. Place it in the home directory where Caucus is already installed -- make it owned by the same unix userid that owns the Caucus files.
Then, logged in as that unix userid, at the shell prompt, type:

./addmodules
and follow the prompts.

Restart Caucus. The chat tool has its own "daemon" process that "serves" the individual users' chat clients. You will need to stop and restart Caucus in order to (automatically) start the chat daemon.
A full Caucus manager can stop Caucus from the manager page ("operations") section. Then follow your normal Caucus server daemon start-up procedure (see Starting the Caucus Daemon for more information).
If you ever need to change the port number, or the location of java, edit SWEB/swebd.conf, and look for the relevant "Config" and "Script" parameters. Change them as needed, stop any running Babylon processes, and then restart Caucus.

III. Invoking Chat from within Caucus
The chat tool is invoked from a new set of Caucus "macros", which you can place anywhere within Caucus. There is no default link to the chat tool, you must specifically link to it with a macro.
There are only three chat macros. The first invokes the chat client, which appears on the user's screen as a java applet. The other two provide access to the logs (the history) of the chat sessions.

%chattool() -- invoke the chat client
%chatlogs() -- show a list (a history) of chat logs
%chatlog() -- link to a specific chat log.

All Caucus chat sessions are automatically logged, and stored as text files in the CHATLOGS directory. (If you need to purge old chat logs, you can just delete the relevant files.)
You can have as many different chat "rooms" as you like. Each use of the %chattool() macro links to a particular room. Users may not hop from one room to another from within the chat tool; they must be able to click on the relevant %chattool() macro to get into that room.
You can place the chat macros anywhere (that you can place any macros), including responses, items, conference home pages (in the conference 'introduction' text), the Caucus Center page, or your custom CML pages.
The rest of this document describes the chat macros in detail. Once a user is "in" chat, they should click on the Help button for further information.

%chattool (room options linktext)
Displays the Caucus chat tool ("Babylon"), automatically connected to chatroom room. Room is one of the following:

0 -- connects to a chatroom with the name of the current conference.
N > 0 -- connects to a chatroom with the name of conference number N (usually only used by CML page or macro writers).
name -- connects to chatroom name.

Linktext is the usual text of the link. Can be anything -- ordinary text, an image, even another Caucus macro. The linktext is ignored if type=embed, see below.
Options is a set of comma-separated (no blanks) options that control exactly how the chat tool operates. It can include any of the following:

type=float The chat tool floats in a resizeable applet window. (A small pop-under window also appears.) The Caucus user can continue to navigate through different Caucus pages while leaving the chat tool running. This is the default.
type=popup The chat tool appears in a pop-up browser window. The tool is %b(not) resizeable. The Caucus user can continue to navigate as above.
type=embed The chat tool appears embedded in the Caucus page, wherever the macro was placed. The Caucus user may not leave the page -- or else they will disconnect from the chatroom. See the note about embedded chats below.
width=nnn Specify the width, in pixels, of the chat tool.
height=nnn Specify the height, in pixels, of the chat tool.
whiteboard=0 Turn off (do not display) the whiteboard. The default value is 1, display the whiteboard.
pageuser=0 Turn off (do not display) the "Page user(s)" button. The default value is 1, show the button.
im=0 Turn off (do not display) the "Instant Messaging" button. The default value is 1, show the button.
help=0 Turn off (do not display) the "Help" button. The default value is 1, show the button.
ignore=0 Turn off (do not display) the "Ignore user(s)" button. The default value is 1, show the button.
fullnames=1 Display the users' full names, followed by their userid in parentheses, e.g. "Charles Roth (croth)". The default value is 0, show only the userids. Note: mixing fullnames=0 and fullnames=1 in different macros in the same user session will cause "incorrect password" errors. Try to choose one usage and stick with it.

Examples:

%chattool (open width=500,whiteboard=0 Open Chat)
Displays a link Open Chat to a chatroom called 'open'. When the user clicks on the link, a pop-under window appears, which in turn launches the floating java applet window, with an initial width of 500 pixels, and no whiteboard.

%chattool (0 type=embed,pageuser=0,height=300)
Displays the chat tool embedded in the page (typically an item or response), automatically connected to a chat room with the same name as the current conference. The chat tool applet is 300 pixels high, and the "Page user(s)" button does not appear. See the note about embedded chats below.

%chattool (0 x Chat)
Display a link Chat to a 'floating' chat room for the current conference. All default options are used. The "x" (or any single word with no commas) is required to act as a place-holder for the options field.

%chatlogs (room linktext)
Displays a link linktext (may be anything, including an image or a macro) to a list of the logs for chatroom room. Room has the same definition as in %chattool(), above.

%chatlog (room date time linktext)
Displays a link linktext to an individual chat log. Room has the same definition as in %chattool(), above. Date and time select a particular chat log, using exactly the same format as displayed in the list of chat logs shown by %chatlogs().
Alternately, the value "0" for both date and time selects the most recent chat log for room.

Note: When using an embedded chat in an item, you may need to "Customize Users" for the conference to allow applets to appear in an item. Uncheck the "hide" checkbox for applets, and check the "allow for organizers" box. Otherwise the Caucus security feature (that filters out unwanted tags) may filter out the very chat box you desired!

type=float	The chat tool floats in a resizeable applet window. (A small pop-under window also appears.) The Caucus user can continue to navigate through different Caucus pages while leaving the chat tool running. This is the default.
type=popup	The chat tool appears in a pop-up browser window. The tool is %b(not) resizeable. The Caucus user can continue to navigate as above.
type=embed	The chat tool appears embedded in the Caucus page, wherever the macro was placed. The Caucus user may not leave the page -- or else they will disconnect from the chatroom. See the note about embedded chats below.
width=nnn	Specify the width, in pixels, of the chat tool.
height=nnn	Specify the height, in pixels, of the chat tool.
whiteboard=0	Turn off (do not display) the whiteboard. The default value is 1, display the whiteboard.
pageuser=0	Turn off (do not display) the "Page user(s)" button. The default value is 1, show the button.
im=0	Turn off (do not display) the "Instant Messaging" button. The default value is 1, show the button.
help=0	Turn off (do not display) the "Help" button. The default value is 1, show the button.
ignore=0	Turn off (do not display) the "Ignore user(s)" button. The default value is 1, show the button.
fullnames=1	Display the users' full names, followed by their userid in parentheses, e.g. "Charles Roth (croth)". The default value is 0, show only the userids. Note: mixing fullnames=0 and fullnames=1 in different macros in the same user session will cause "incorrect password" errors. Try to choose one usage and stick with it.