BASIC INFORMATION Name: Extropia's WebChat Version: 2.0 Last Modified: 04-02-98 COPYRIGHT You may use this code according to the terms specified in the "Artistic Licnse" included with this distribution. The license can be found in the "Documentation" subdirectory as a file named README.LICENSE. If for some reason the license is not included, you may also find it at www.extropia.com. Though you are not obligated to do so, please let us know if you have successfully installed this application. Not only do we appreciate seeing the wonderful things you've done with it, but we will then be able to contact you in the case of bug reports or security announcements. To register yourself, simply send an email to register@extropia.com. Finally, if you have done some cool modifications to the scripts, please consider submitting your code back to the public domain and getting some community recognition by submitting your modifications to the Extropia Cool Hacks page. To do so, send email to hacks@extropia.com DESCRIPTION WebChat is a useful CGI program that allows a number of people on the World Wide Web to talk to one another simultaneously. It differs from a BBS (bulletin board system), in which the messages are typically read hours or days after they are posted. The ability to chat on the Web can be a quick way to hold a "virtual meeting" . Although both WebChat and WebBBS store messages for other people to read, there is a major difference in how the user sees and posts messages. The BBS emphasizes long-term storage of messages, including sta tistical data such as the date and time the message is posted. The BBS also encourages users to branch out into different topics in "threads" of replies. On the other hand, WebChat emphasizes the quick posting of small messages much like a conversation among a group of people. Dialogue is designed to flow swiftly in small, easily digested chunks. Additionally, because the topic is being discussed by eve ryone at the same time, there is little room for different people discussing many different things in the same chat session. Thus, there is no reason to keep track of different threads of conversation. Because people are discussing things simultaneously in real time, another feature of WebChat is the ability to refresh or display new messages as quickly as desired. This is done using the META HTML tag to force refreshes within a cert ain time frame. WebChat includes many features designed to facilitate this kind of dialogue. In WebChat, users can refresh messages using a button that is displayed in plain view. In addition, if the user is using a browser such as Netscape, that supports the META REFRESH HTML tag, the user can choose to have the chat messages refresh or redisplay themselves automatically at a user-defined interval. Messages are displayed in chronological order of posting from most recent to oldest so that users can quickly look through a list of statements. In addition, users can specify whether to see only new messages each time they refresh the screen or to inc lude a user-defined number of previous messages. Viewing several of the previous posts along with new ones tends to provide the user with greater continuity. By default, messages are posted to everyone, and the user's information is embedded as part of a posted message. This arrangement facilitates quick posting. By default, posted messages are seen by everyone. However, the user has a choice of entering a different username to specify whom the message should go to; the message is then entered as a private message from one person to another. This is option analogous to someone whispering a comment to someone else in the middle of a larger meeting. Additionally, Netscape-style frames are supported; messages are refreshed in one frame while the user types messages in another frame. This feature allows a user to set a relatively high refresh rate for seeing new messages, while leaving the message s ubmission form intact while the user is typing a message. WebChat also has configurable options such as the automatic announcement of a user's entry into the chat area, allowing people to keep track of who is currently in the system. Also, when a person leaves, he or she is encouraged to announce the departure by pressing the Log Off button. Nothing is more disturbing than to find out the person you were chatting with has left the room! In addition, WebChat can be customized to remove old messages by age and by number of messages. For example, if WebChat is used for real-time conversations, it is generally not useful to keep the conversation messages for more than an hour. Additional ly, you may want to make sure that not more than 10 or 20 messages stay around at any given point, because messages older than the first 10 may be irrelevant to the current course of conversation. On the other hand, on other chat areas, you may want to keep the messages around for a long time to keep a full transcript of the discussion or meeting. BASIC INSTALLATION (UNARCHIVING THE APPLICATION) Once you have downloaded the TAR file (a single file containing all associated files in their relative positions under the root directory), transfer the TAR file to an executable directory on your web server and untar them. On UNIX systems, you may type the following at the command line: tar xvfp filename.tar (If you are using a non-UNIX Operating System, you may download a TAR/UNTAR program by pointing your Web browser to http://www.shareware.com). BASIC INSTALLATION (SETTING PERMISSIONS) Your Web server must have permission to read, write or execute as needed. Each sub-directory and file in the application has its own correct permissions level associated with it. Once you have unarchived (UNTAR) the application, you must then set the correct permissions. On UNIX systems, you will use the "chmod" command. The following table is a quick guide to setting permissions for UNIX servers. PERMISSION COMMAND rwxrwxrwx chmod 777 filename rwxrwxr-x chmod 775 filename rwxr-xr-x chmod 755 filename rw-rw-r-- chmod 664 filename rw-r--r-- chmod 644 filename Note: Not setting your permissions correctly is the NUMBER 1 reason why installations fail. Take time to get this right. The actual permissions required for the subdirectories and files used by this application are listed in the next section. BASIC INSTALLATION (FILES, DIRECTORIES, AND PERMISSIONS) The TAR file will then expand into a root directory called Chat. Chat will contain several sub-directories and several files. The diagram below depicts the directory structure as well as the permissions which must be applied to the files and subdirectories used by the application. Chat Root Directory (drwxr-xr-x) |____Chat_CGI Sub-directory (drwxrwxrwx) |____Chat_Open Sub-directory (drwxrwxrwx) |____Documentation Sub-directory (dr-xr-xr-x) | |____All files in this dir (-r--r--r--) |____Sessions Sub-directory (drwxrwxrwx) |____cgi-lib.pl (-r--r--r--) |____chat-html.pl (-r--r--r--) |____chat.cgi (-r-xr-xr-x) |____chat.setup (-r--r--r--) |____index.html (-r--r--r--) BASIC INSTALLATION (CHANGING SITE-SPECIFIC VARIABLES IN CHAT.SETUP) Change the site-specific variables in chat.setup acccording to the following logic: @chat_rooms is a list of chat names. There must be a directory for each chat room. Ala, for "open" we need Chat_Open directory @chat_directories is a list of directories relative to the current one where the chat_directories reside @chat_variable is a list of chat id's that are used to reference the forum names. For example, if @chat_variable = ("cgi") and @chat_rooms=("CGI Programming") then calling the script as "chat.cgi?chat_room=cgi" will reference the "CGI Programming" room. $chat_script allows you to change the name reference of the script. The default is "chat.cgi". For servers such as NT Netscape v1.12 that really requires the program to be encapsulated in anther one such as a .bat file, this is where you would change the references to the CGI program. You may want to disallow HTML Images or HTML code Set the $no_html or $no_html_images to "on" if you want to disallow either html code or just html images from being placed in your chat $chat_session_dir is the directory relative to the chat script where the session files are stored $chat_session_length is the time in days that session files stay active. $chat_who_length is the time in days that the who files stay active to show who is an occupant in the chat room $chat_announce_entry = "on" if we want a message to automatically post announcing someone's logging into the chat room $prune_how_many_days > 0 means delete messages older than this many days. $prune_how_many_sequences > 0 means delete old messages if there are more than this many sequence numbers in the directory. RUNNING THE SCRIPT Make sure that you are using Perl 5.0 or better and that the first line of the executable points to the location of perl on your server. For example, if your Perl interpreter is located in the "/usr/local/sbin" directory, you should change the first line to read: #!/usr/local/sbin/perl -T When you want to view the chat from the web, simply reference it as you would an HTML document. For, instance, something like... http://www.foobar.com/cgi-bin/Chat/chat.cgi TECHNICAL SUPPORT Further technical support can be found at www.extropia.com