SFEChat 1.1 Copyright 1999-2005, Kristina Pfaff-Harris (http://tesol.net/scriptmail.html) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Contents of this file: Program Summary Copyright & Licensing Information Legal Notice & Disclaimer Getting Started with SFEChat 1.1 What to Do About Problems Known Problems For Total Newbies Only Other Scripts =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Program Summary: SFEChat is a single-room, real-time chat program for your website. Users can register, choose a color to type in, and chat with others. Based on Chat-N-Time, SFEChat offers all the features of Chat-N-Time plus the following: /kick - Admin can kick users out of the chatroom. If you /kick a username, if closes the user's chat window such that they cannot log in until a full screen of text has gone by. e.g. /kick jojo /kick rudebobby /ban - Admin can ban users by username and/or IP address from the chat. If the user is logged on, it will also kick him out of the chat. e.g. /ban jojo /ban 192.168.1.1 /unban - Admin can un-ban users. Typing "/unban" with no arguments gives you a list of what users and IP's are banned. You can then do /unban and it will un-ban them. /addicon - Admin can add emoticons (smiley images) by using something like: /addicon :-) http://www.some_domain.com/images/happy.gif /addicon :-( http://www.some_domain.com/images/sad.gif (All images must be reachable on the web at those addresses. Sorry, images not included.) /removeicon - Admin can remove an emoticon just by referencing the text. e.g: /removeicon :-) /removicon :-( /badword - Admin can add to the list of "bad words" that the chat attempts to censor. e.g: /badword phooey /badword shucky darn /unbadword - Admin can remove a bad word from the list of words to be censored. e.g: /unbadword phooey /unbadword shucky darn /topic - Admin can change the topic, or set it so that all users can change the topic. e.g: /topic This is the new topic /topic World of Warcraft Discussion The chat room also supports /yell (puts the message in all caps), /msg (private messages), /me (user actions), and logging to a chat transcript. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Licensing & Copyright Information: The Licensing terms and conditions are listed within the sfechat.cgi program itself. This program is Copyright Kristina L. Pfaff-Harris. All rights reserved. You may use this program free of charge provided you agree to the License agreement contained within the program. Credit to the author must be maintained wherever it appears in the script or the html pages. However, the credits may be in HTML comments so that they don't show up on your pages. For example: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Legal Notice & Disclaimer: This program is offered as-is and no warranty is given, either express or implied. By downloading, modifying, copying, viewing, or using this program, you agree that neither the author of this program nor the owners or administrators of the site from which you downloaded this program are liable for any breach of security, damage or loss caused directly or indirectly by the use of this program, and that any such breach, damage or loss is the sole responsibility of the person who downloads, modifies, copies, views, or uses this program. The author has attempted to make this program as bug-free and secure as possible, but there is always the possibility of something being overlooked, hence the author disclaims any responsibility for problems incurred in the use of this program. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Getting Started with SFEChat: This assumes that you have permission to execute cgi programs on your server, and that you know where the programs have to go. Sometimes, a web server is set up so that all cgi programs must be in a single directory (usually /cgi-bin). If you don't know whether or not you have permission to do this, or if you don't know where the programs must go, ask your system administrator. You may also want to check out "What should I ask my web hosting provider before setting up a CGI script" from the FAQ at http://www.tesol.net/scripts/FAQ/ . This will give you a lot of information about your website that will make any CGI script easier to set up. These instructions are focused towards Unix systems. If you have a Windows system, the directions may change slightly. I have tried to note Windows-specific differences in the script itself, so please read them carefully. You'll need to modify each of these files slightly for use on your own site. sfechat.cgi This is the actual program that runs the chat and keeps track of users online, etc. There are several places in this file you will need to modify for use on your server. All of these are marked **CHANGE** and are accompanied by an explanation of what to do so that you can easily find them. Please read all instructions very carefully and you should not have problems. This file must be chmod 755 (world read/execute) in order to work. It may need to be in a special "cgi-bin" directory, or you may just need to make sure it ends in ".cgi" (or sometimes, ".pl" on Windows servers). Check with your web hosting provider if you're not sure where CGI scripts and their associated files should go. lang-en.txt Other than sfechat.cgi, this is the MOST important file for this program! The language file contains all the messages, button text, and so forth for all the messages printed out by the script. If you do not have this file, the script will not run. Make sure that when you configure sfechat.cgi, you put the correct path to this file in there. You may translate this file into another language without modifying the script itself. It must be chmod 644. sfechatwindow.html This file should be empty when you start out, and must be writeable by your web server. This may mean that you should chmod the file 766 (world writeable). NOTE: Sometimes, you cannot have any html files in your cgi-bin directory. If you're getting "Internal server error" when the chat window refreshes, that could indicate that you need to move this file out into the place where the rest of your HTML pages are. chatters.txt This file should also be empty when you start out, and must also be writeable by the web server. (Possibly chmod 766) This is the file where the program keeps track of users online. banned-ip.txt This is a file where you should put a list of IP addresses to block from your chatroom. It must be chmod 766, or otherwise set so that the program can write to it. The SFEChat admin can ban or unban people or IP's by using /ban or /unban. badwords.txt This file is where you should place a list of "bad words" that you want the program to censor out of your chat room. It is a plain text file, and should contain one bad word or phrase per line. For example: blank blankety blank blank you It should be chmod 766 or otherwise set so the program can write to it. The SFEChat admin can add or remove words from this file by using /badword or /unbadword. sfechatmain.html This is just a simple HTML file that you may modify in any way you wish, but please pay close attention to the one line that says as you'll need to make sure that the iframe source points to your sfechat.cgi program. This page should probably also contain brief instructions on how to log into the chatroom or register, and a welcome message of some sort. This file must be chmod 644 in order to work, and may need to be in with your regular HTML files. If you get "Internal Server Error" when trying to pull up this file, take it out of your cgi-bin directory. Here's how I recommend you install this script. 1. Make a directory on your website called "sfechat." 2. Open sfechatmain.html with a plain text editor such as Notepad or BBEdit (NOT FrontPage, DreamWeaver, etc!), and make sure that the "iframe src" is changed to the URL of where you're going to put sfechat.cgi. There are instructions on what to do that you will see when you open the file in a text editor. 3. The file sfechatbanner.html is just a very small HTML file containing a welcome message to be displayed in the top frame of the chat. You can modify this if you want, but it's not necessary. 4. Upload the sfechatbanner.html and sfechatwindow.html files to the sfechat directory. Chmod sfechatwindow.html 766 or otherwise set it so that your web server can write to it. Chmod sfechatgoodbye.html and sfechatbanner.html to 644. If you're not sure what I mean by "chmod," there is information about this in the FAQ at http://tesol.net/scripts/FAQ/ and if you have a Windows server, you probably don't need to chmod anyway. 5. Upload all .txt files to your cgi-bin directory. You should have badwords.txt, chatters.txt, registered_users.txt, topic_file.txt, banned-ip.txt, lang-en.txt and sfeicons.txt. Chmod all the .txt files to 766 or otherwise so that your web server can write to them. 6. Make the appropriate changes to sfechat.cgi using a plain text editor such as vi, pico, BBedit, Notepad, or even Wordpad (as long as you save it as plain text.) You'll need to tell sfechat.cgi where all the .html and .txt files are. If you get these wrong, then the script should tell you when you try to pull it up. There are quite a few things to change, so just be patient and read all the instructions. :-) If you're honestly not sure what the paths should be, please feel free to email me, tell me what you put in for the paths and what the script tells you when you try to pull it up, and I'll try to give you pointers. 7. Upload sfechat.cgi to your cgi-bin directory. Chmod sfechat.cgi 755. 8. Pull up sfechatmain.html in your browser. You should see a login screen. If so, log in with the admin username and password you put in the script and you should be good to go! If, instead, you see error messages ... well, skip to the "What to do about problems" section. We're going to assume it will work. :-) Once you've modified these files according to the instructions, you should be able to pull up "sfechatmain.html" in your browser and log in to your chat room -- that's pretty much all there is to it. If you wish to log all your chats to a transcript file, you will probably need to create a directory for your chat logs. See the sfechat.cgi file for details about permissions and so forth. Once you've made these changes, that should be all you need to do! =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= What to Do About Problems: IMPORTANT: If you contact me with a problem about this program, you MUST give me as much information as possible. Please include: The name of this program and its version (This is shown at the top of the sfechat.cgi file.) The information you got when you turned debugging on. (See $debugging in sfechat.cgi for details.) The operating system of your web server (e.g. NT, Solaris, Ultrix, BSD, Linux etc) Your web server software (e.g. Apache, Netscape Commerce, NCSA, IIS, etc) The error message you got. The error message in the server log file. (ask your systems admin where the error logs are.) The location of your website (http://www.yoursite.com etc) so I can look at it. This is really important: I'm generally really happy to try to help with problems! I will not just come and do it for you, but most of the time, if you drop me a quick email, any problems can be solved pretty easily. I really enjoy helping people get these scripts set up. However, I do ask that you help me to help you: I can help ONLY IF you give me as many details as possible about the error(s). If you email me and say "Your script doesn't work," I won't have the faintest idea what you're talking about. (I have a lot of scripts here, and yes, people do that.) :-) However, if you email me and say, "SFEChat doesn't work," AND you send me all the text of the error messages AND you send me an explanation of what you were trying to do when you got the error, what you expected it to do, and what it did instead, and especially if you have turned $debugging on in the script and send me that output, well. You will be my favorite person ever, even if just for that one day. :-) The more detail you give me, the more willing I will be to bend over backwards to help. If you got an "Internal Server Error", "Premature end of script headers", or "CGI script error," then please check the following *before* you email me, since, chances are, you did one of the following things: 1) You uploaded the script to your website using "binary" mode in your FTP program. To fix this, re-upload the script, but choose "ascii" or "text" mode. 2) When you edited the script to configure it for your site, you added a blank line above the #!/usr/bin/perl line. To fix this, edit the script again, and make sure that #!/usr/bin/perl (or whatever the path to Perl is on your server) is on the *very* first line of the script, save it, and re-upload it to your website. 3) When you edited the script, you used a program such as Microsoft Word, WordPerfect, or other fancy editor, and you did not save the script as plain text when you were done. To fix this, re-save the script as plain text, and upload it to your website again. 4) When you edited the script, you did not put a \ (backslash) in front of a ", @, or other symbol when you were configuring it. To fix this, go double check all the configurations that you did when setting it up. A final word: Please check the FAQ at http://tesol.net/scripts/FAQ/ to see if your problem has been found before. Many times, there is information there which can help you. If you email me with detailed information about your problem, I will try to help, but -- fair warning -- if it's in the FAQ, then rather than type out the FAQ answer again, I'll have to point you to it. :-) If you have read the FAQ and didn't understand it, that's okay too! I'll be happy to try and clarify anything you're not sure about. As long as you're willing to try to figure this stuff out, I'm willing to try to help you over some of the "bumps." :-) =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Known Problems or Issues: Private messaging is handled through JavaScript, and so is not really necessarily private. Top secret discussions of national security should not be made via the /msg command. :-) Most people aren't going to be able to read your private messages, but they're pretty easy to "crack" for someone who knows what they're doing. I haven't added all messages to lang-en.txt. Multi-language support will need to wait a bit. This is NOT supported under anything lower than Internet Explorer 6 or Netscape 7/Mozilla 1.7.4. Please don't report problems if the browser being used is lower than this version. Censoring the chatroom via the use of "badwords.txt" will not stop a truly determined disruptive person, since they could use misspellings, and other variations of the bad word to bypass the censorship. It does help a little, but things like "badword" can be entered as "b a d w o r d" and "badw0rd" etc, so keep that in mind. If you have open registration, and you /ban some username, there's nothing to stop them from re-registering and coming back. If they're on AOL or something, they may even have a different IP address. Keep that in mind. The program does not support multiple rooms. Please email any bug reports to me (http://tesol.net/scriptmail.html) so that I can try to get them fixed. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= For Total Newbies Only A few words on uploading and downloading of Perl CGI programs: When you get the program from my website to your computer, it is usually referred to as "downloading" the program. When you get the program from your computer to your website, it is usually referred to as "uploading." Most people use a program called an "FTP client" or simply "FTP" to upload things to their websites. If you are using FTP to upload to your website, then your FTP program will usually give you an option of whether to upload in "binary" or "ascii" (sometimes known as "text" or "text-only") mode. Simply put, you MUST use ascii mode to upload a Perl cgi program to your website, or it will not work. If you cannot figure out how to do this, then please either call your website's Technical Support staff, or read the manual or other documentation for your FTP program. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Other Scripts: If you like this program, try some of the other CGI scripts available at Kristina's Scripts for Educators: http://www.tesol.net/scripts/ Currently available are: AddrBook: A simple web-based address book AffordaBilly: Loan affordability calculator: how big a loan can you afford? AutoCGIMail: Create your own custom email forms and scripts online! CGI-Subscribe: An email mailing list manager Chat-N-Time: Real-time web-based chat CrosswordMaker: A tool to create and grade HTML crossword puzzles GradeORama: Online gradebook server MakeBook: A guestbook/ongoing story program. MetaboCalc: A metabolism/calorie burning calculator. PayBackTime: Calculator for how long it will take to pay off a debt. QAMaker: Online FAQ/Question & Answer list generator Quadratic-O-Matic: A simple quadratic equation solver QuizTest: Offer multiple-choice/true-false quizzes RandomQuiz: Generates quizzes with randomly selected questions RemindMe: An email auto-reminder service SFEBanner: Simple banner, quote, image rotator. SFEChat: A more functional chat room similar to Chat-N-Time. SFEBlackJack: Simple online video BlackJack game SFEBMICalc: A body mass index calculator. SFEHangMan: Online, multi-language Hangman game. SFEPoker: Simple online video Poker game SFESurvey: Another survey/quiz generator. SFEWordSearch: Generate printable wordsearch puzzles SillySearch: Let people search for pages on your website SillyCount: Let's you create a web-page counter. SillySite: A simple web-page creation program VeryInteresting: Loan Interest calculator and amortization table generator VocabSearch: Create and search a list of vocabulary words Votesie: Online voting booth/Poll generator Web-B-Mail: Private, web-only email-like system with pictures. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Thanks for using SFEChat v1.1 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=