CoolCaf V1.2
Copyright 2001 Pierre Dupuis
-----------------------------

*********************
***** IMPORTANT *****
**************************************************************************************************

If you are using version 1.1b of CoolCaf, you need to get the file upgrade12.zip instead of
CoolCafe12.zip. If you proceed with the installation of 1.2 over 1.1b, you will LOSE all your user
informations.

upgrade12.zip provides an utility to migrate the 1.1b database to the new 1.2 database.

**************************************************************************************************

--------------------------
First, some legal stuff...
--------------------------
Pierre Dupuis assumes no responsabilities from you using CoolCaf on your web site. If you
cannot assume full responsability from the use of my code then don't use it.

CoolCaf is free to use and you can do whatever you want with it except redistribute it at a
cost. The only thing I ask is that the CoolCaf button appear somewhere on your site.

Example:
<a href="http://www.coolcafe.ca" target="_blank"><img src="images/slogoCafe.gif" border="0" alt="The Coolest ASP Chat Application!"></a>

-------------------------
Step by step installation
-------------------------
0-	Take a backup copy of your web site!

1-	Unzip the file coolcafe12.zip in the root of your web site
	2 directories will be created (coolcafe and coolDB) and 3 files will be copied to your
	root (readme.txt, adovbs.inc and Global1.asa)

2-	Create your Global.asa file
	If your site don't already use a Global.asa file, just rename the file Global1.asa
	created in step 1 to global.asa.
	If you already have a global.asa file, cut and paste the code between
	'Sub Application_OnStart' and 'End Sub' from global1.asa to your global.asa file at
	the the beginning of your 'Sub Application_OnStart' section. If your global.asa don't
	have a 'Sub Application_OnStart'section, then cut and paste the whole section from
	global1.asa to your global.asa file.

3-	Edit your global.asa file
	Edit your newly created global.asa file as following:

	Modification 1
	--------------
	Find the line showing: Dim roomData(6,3)
	The first argument, 6, have to be set to the maximum number of rooms your chat will
	support. This number can be change at any time if you want to increase or decrease that
	number.	We suggest that you put a number higher then the actual	number of rooms you will
	start with. It will then be possible for you to dynamically add	new rooms later. But don't
	put this number too high for nothing as it will waste memory.

	Modification 2
	--------------
	Find the line showing : Dim userData(6,5,30)
	The first argument, 6, must be set to the same number you have put in modification 1.
	The third argument, 30, must be set to the maximum number of users allowed per room.
	The more user you will allow per room, the more memory will be needed. Also, too many
	users in a chat	room makes it impossible to have a nice conversations going on.
	If you plan on serving many users, it would be better to open new rooms then to put this
	number to high.
	These numbers can be modified anytime if you want to support more or less users.

	Modification 3
	--------------
	Find the line showing:
	Application("DBString") = "DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=" & Server.MapPath("/coolDB/chat12.mdb") & ";"
	This string must be set to your database string to access the chat database. In this
	example, the string assumes that the database will be kept in a directory called coolDB.
	You need to change this string only if yo move the database location.

	IMPORTANT:	The chat12.mdb database must be in a directory with write permission.
			If your site is	hosted, you may have to move the database in your
			cgi-bin directory and modify the database string to reflect his new 
			location. Often Hosting services only allows the cgi-bin directory to 
			have write access.

4-	Now this is a big difference between version 1.1b and 1.2. You are now ready to run
	CoolCaf! All customization is done online using the Online Manager Interface (OMI).

	CoolCaf looks better if it is started in his own window. We provided a simple HTML page
	to show	how to do this. Look at go.asp in the coolcafe directory. To continue the
	installation, just execute this page (type http://www.yoursite.com/coolcafe/go.asp where
	you replace yoursite.com by your site name in your favorite browser) and click on the
	CoolCaf link. You can later integrate the code in go.asp in you site.

5-	Login to CoolCaf

	You will then be presented the login screen to CoolCaf. CoolCaf use a membership
	system to help you build a better relationship between your site and your user. By 
	default, one account is available. It is the admin account with administration
	privilege. CoolCaf supports more then one admin account and it is possible from the OMI
	to assign admin privilege to any users (remember that these privilege are powerfull and
	should only be given to trusted people).

	All text and graphics can be customized to your look and feel. But for now, we will be
	using the default interface.

	Login to CoolCaf by typing admin in the nickname field and admin in the password field.
	Click Enter. You will then be presented the select room page.

6-	Select a room
	
	For the installation in does'nt matter what room to select. And yes, you will be able to
	change the rooms name :)
	Click on any radio button and click on Enter.

	If you get this message:

	[Microsoft][ODBC Microsoft Access Driver] Cannot update. Database or object is read-only.

	This is because your database is not in a write enable directory. Close the windows and get back to step
	3, modification 3.

7-	Your are in! Update your profile.

	The screen is composed of 5 areas: header at the top, the main chat, text input at the
	bottom,	user list top right and text formatting lower right.

	The first thing you must do is change your admin profile. Click on the name admin that
	appears in the user list. (With admin privilege, you can access	all user profiles.
	"Normal" users can only access their profile). This will bring up the user profile panel.
	All user have a unique profile. So all options available from this panel are unique
	to each users for a more personal chat experience.
	
	Change the email address, sex (if required) and the password for the admin nickname (very
	important to change it).

	You can also change some personal preferences. Refresh rate is the chat refresh rate for
	this account (every users can specify their prefered refresh rate). Scroll is the
	direction for scrolling text in the chat window. Down means that new text appears at the
	top of the chat window. Up will make it appears at the bottom.

	With CoolCaf 1.2, each user can select a color for their nickname. Click on the red
	color to change yours if desired.

	When a user enters or leaves a room, a message is posted to all to signal it. When this
	option is selected, the user will see these messages. Un-select it to hide them.

	For Internet Explorer user there is an option to get beeped when a new user enters a
	room (usefull if you are the first on in a room, waiting for others to join). Select
	this option if you want to get beeped.

	You can also change your picture. If you don't like the rabbit (hey! I like it!) just
	click on it and select a new picture.

	Now that you modifid your profile, you need to confirm the modification by clicking on
	update. You should then receive a message confirming the update. Click now on quit to
	get back to the chat.
	 
8-	Customize you chat

	There are two level of customization. First, there are some internal customization that
	change are your chat operates and change all the text. Second, you can externaly
	customize the graphics to integrate the look of CoolCaf to your site. We will now
	look at the internal customization.

	The admin privilege offers you a button that normal users can't see. It is the Manager
	button. Click on it to access the Online Manager Interface (I like the name!).

	First, click on Chat Options
	----------------------------
	Here you have some options that change the way CoolCaf works. We will look at them
	one by one.

	A- Number of line displayed in a chat room : This is the maximum number of lines that
	will be displayed. The higher this number, the more lines a user can scroll back in
	the chat conversation and the more memory will be required. You must also know that
	all private messages and system messages count as one line. So, one user could see less
	then this maximum number of lines.

	B- Do we translate smileys to graphic : Select this option if you want the system
	to automatically transalte :) type of text to graphic equivalent.

	C- Number of seconds before user is kicked for time out : Well, this is a limitation
	of the pull technology (the client is pulling the information from the server). If
	a user doesn't click on quit (and many don't) to leave the chat, we need to be able to
	kick this user out after a while. Don't set this number too low and kick users that are
	just "listening" to a discussion and don't put it too high if you don't want to have too
	many "ghost" users.

	D- Do we clear chatroom when all users are gone : Select this option if you want to 
	clear all messages in a room when it gets empty.

	E- Check for invisible admin : By popular demand, we introduced this new feature that
	will make invisible too users all user with admin privilege. If you just want to check
	your chat without being noticed, this option is for you!

	F- Check to never kick admin out : Select this option and the system will never kick
	a user with admin privilege out of a chat room. Use this option with option E and you can
	now stay as long as you want watching your chat rooms.

	G- Your site home page : URL of your site home page, including http://

	H- Your administrator email address : Email address that will be used as reply address
	for the confirmation e-mail sent to users.

	I- Your site sender name to appear on email : Name that will be used in all email to
	users.

	J- User list refresh rate (seconds) : Every users control their refresh rate for the
	main chat window. This refresh rate is for the userlist window and it is the same for
	all users.

	K- Your mail server name : Mail server to be use for all email from CoolCaf.

	L- Directory for log files (needs write access) : All chat messages can be logged to
	a text file (one per room). This is the directory for these files. IMPORTANT: This
	directory must have write access.	

	M- Do we log all chat messages to text file : Select to have all messages log to text
	file. This may have some performance impact if you have many users.

	N- Select to set default scroll direction to up : This will be the defautl scroll
	direction when a user first gets in CoolCaf. Users can change this to their own
	preference.

	O- Does your server can send/receive email through ASP : If your server has the JMAIL
	component install. Select this option. If you have other email component installed you
	will need to modify the code or get specific add-on modules from us before you can
	select this option. Selecting this option allows the system to send a confirmation
	email to users after they registered and allows users to request their lost
	userid/password via email.

	P- Do we integrate with an external user database : If you already have a user
	database manage by your site, you may want to integrate CoolCaf to this database.
	Before continuing, you will need to first read our document named "Integrating CoolCaf
	with an external user database". Once the integration is done, select this option to
	let the external database manage the user information.

	Q- Time offset (hours) if your server is in another time zone : By popular demand, we
	added an option that let you specify a time offset to be applied to your server local
	time. This is usefull if your server is in a different time zone then your site is.

	Once the changes are made, click on Submit to update the configuration. You will then
	receive a message confirming the update. Now click Manager to get back to the OMI.

	
	Now, click on Chat Room Management
	----------------------------------
	From this panel, you can modify chat rooms name and add/delete rooms. Deleted rooms
	will only be removed when you will restart your server (or make any modification in the
	global.asa file).

	Make the appropriate changes. 

	To add a chat room:
	Select add a room from the select input box called select room.
	Type the room's name in the next input box.
	Click on update.

	To change the name of a room name:
	Select the room to modify in the select room input box.
	Type the new room's name in the next input box.
	Click on update.

	To delete a room:
	Select the room to delete in the select input box.
	Click on delete.
	
	Note: If you enter a password in the password field and submit your changes, this
	password will be needed to enter the selected room. Very usefull to create more private
	rooms.

	New with release 1.2, new rooms will be available as soon as they are created.
	
	When you are happy with your rooms setup, click Manager to get back to the OMI.


	Now, click on modify messages
	-----------------------------
	All messages in every available languages can be modified from this screen. Just type a
	new text and click on submit.

	Note: Message number 1000 is a special message that is presented to all users when they
	log in. This is usefull if you want to signal something special. You can make this
	message empty to bypass this feature.

	When you are pleased with the messages, click on Manager to get back to the OMI.

	
	Now, click on modify memos
	--------------------------
	Memos are messages that are more then one line long and that can include HTML tags.
	This is the place where you can customize some text like the introduction text in the
	login screen.

	Make the appropriate changes and type submit. When this is done, click on Manager to get
	back to the OMI.

	
	Now, click on Set active languages
	----------------------------------
	If you don't want to offer to your users a specific language, just unselect it from
	this screen.

9- 	You are now ready to go.

	If you want to add a new language, you must first read our document called "Adding
	a new language in CoolCaf".

	In the OMI, you have an option called User management. This option lets you get any
	user profile based on its email or nickname. This is where you can modify the security
	level for a user. To give a user admin privilege, set the security level parameter to 2.
	Remember that doing so will give that user full access to the OMI.

	To kick/ban an user
	-------------------
	With version 1.2 you can now kick/ban a user immediatelly, giving you more control on
	your chat room. To kick/ban a user, set its security level to 0. The user will be kicked
	at its next chat refresh.

	You can modify the look of CoolCaf by replacing graphics by your own. All graphics are
	kept in the coolcafe/images directory. You will see that different graphics can be use
	for each languages. Note that if you do not provide a graphic for a language other
	then english, the english version will be use.

	We are writing a user guide for CoolCaf and we still have to complete the help
	documentation. These documents will be available in at our web site.
	

10-	Information on the "confirmed" field that you will find in the user profile

	When a user register to your chat, he will receive a confirmation mail asking him to
	confirm	his membership.

	When you receive its confirmation, you can then manually set the confirmed field for
	that user. That will help you find who did and who did not confirmed their
	membership and eventually you may decide to delete the users that didn't confirm their
	membership.	


-------------
Thanks!
-------------
I would like to thank Peter Theill for the public release of its ConquerChat application that
gave me the idea for creating CoolCaf.

I would also like to thank Uffe for its help with testing the application.

Thanks also goes to Edwin Giefeldt for its Danish translation and its help debugging CoolCaf.