YaBBChatSP1 mod, v. 1.98

  1. Chatroom Features
  2. Using the Chatroom
  3. The Chatroom Control Center
  4. Quick Installation Instructions
  5. Detailed Installation Instructions
  6. Using the Add More Smilies mod in the Chatroom
  7. Showing chatroom info on other web pages (SSI)
  8. Version History
  9. Credits

 

Please read this entire file before installing the YaBBChatSP1 mod and backup your forum before installing.



Chatroom Features:


!NOTE! This mod doesn't work with NETFIRMS or other webhosts
that insert banners on every page or in every window.  !NOTE!



Using the Chatroom:

To access the chatroom users may need to be logged into the YaBB forum.  On some forums, the Administrator may have elected to open the forum to guests.  In either case, in the forum Info Center click on the "Join Chat" link to enter the chatroom.  A window should open showing the chatroom information screen.  This welcome screen may display chat rules, or other information the forum Admin wants chat users to know. The chatroom information screen will be replaced by the chatroom screen.  If enabled by the Admin, a alert window will pop up when a new user enters the chatroom.
 


Chatroom functions:

Online List (upper right):  The names of users in the chatroom are listed here.  Clicking on a user's name will display that user's YaBB Profile.

Reload:  Refreshs the message area of the chatroom.

Online List (lower right):  Refreshs the Online List above.  This is useful when another user leaves the chatroom without logging out properly.

Reload Target:  Refreshs the list of users on the Target list.  Again, this is useful when a user leaves the room without logging out properly.

Info:  Displays the Chatroom Information Page.

Wipe Chat:  Clears the message area of the chatroom.  Only users granted Levels Two or Three status will see this control.

Kick User:  This opens the kick user screen.  Only users granted Level Three status will see this control.  The kick user screen lists users currently in the chatroom with a radio button next to each name.  Level Three users can not be kicked from the chatroom so no button appears next to these users.  To kick a user out of the chatroom click the button next to the name and then click "Kick".  Kicking a user out of the chatroom prevents the user from viewing or posting messages for the duration of time set by the Admin with the Kick Time setting.  Note that once a user is kicked there is no way to "un-kick" them before the Kick Time has passed.  Not even an Admin can "un-kick" a user.
 


Kick User Screen

Kick User screen showing that user dan2 has been kicked


Logout:  This control properly logs the user out of the chatroom and closes the chat window.  Simply closing the window to leave the chatroom will leave the user being shown as still logged in.

Message Box:  This is where the user types messages.  To post a message type it in the box and press enter.  The message should appear in the message area.  YaBBC tags are allowed.

Color:  Sets the text color for chat messages.

Type & Target:  Selecting Private on the Type control allows users to send messages to individual users (selected from the Target list) instead of everybody in the chatroom.  To send a private message to a single user both the "Private" setting and the user name must be selected otherwise the message will go to all users.
Note: some users have reported that there is a bug in this function and that all messages are public regardless of settings here.  I have not been able to reproduce the problem but I will continue testing.

Chat Shortcuts:  Chat shortcuts are keywords that expand to longer phrases or YaBBC tags when typed in the Message Box.  All chat shortcuts begin with a forward slash such as /shortcut.  The Forum Administrator sets the shortcuts available in the chatroom.  To see a list of shortcuts available in the chatroom type /chatshortcuts in the Message Box.  A list of shortcuts and their associated phrases will appear.  Chat shortcuts are case sensitive.  The shortcut /Poe is not the same as /poe.  If a chat shortcut is used in a message, the entire message will be replaced.  For example, typing Here is my /shortcut will yield only the shortcut message and the Here is my part of your message will be discarded.

Smilies:  Smilies may be added to messages by clicking the smilie buttons at the bottom of the chatroom window or, when the Add More Smilies mod is loaded, by picking smilies from the smilie block or popup window.

Getting Help:  Type /help in the Message Box and press the enter key.  The Chatroom Help link to the help file will appear in the message area.  Click the link to view the YaBBChat Help file (this file).



Chatroom Control Center:

The Chatroom Control Center is found in the Admin Center.  It can also be accessed by typing /chatcontrol while in the chatroom and then clicking on the Chatroom Control Center link that appears in the message area (this only works for Admins).

Color Settings:  Chatroom colors are set here.  Colors are entered as Red-Blue-Green hexidecimal numbers preceded by a # pound sign.

Examples:
Chatroom:  If checked the chatroom will be open to all users.  If unchecked, the chatroom will be open to Admins and the members of the member groups specified in the Chat Group setting.  To restrict the chat to just Admins, enter a non-existant member group in the Chat Group setting and uncheck the Chatroom box.

Chat Group:  The members of the member groups* specified in this box will be granted exclusive access to the calendar when the Chatroom box is un-checked.  Tip: Unchecking box below and entering a nonexistent member group name makes calendar visible to Admin only (handy for hiding calendar during major updates).

* The member groups discussed here are the member groups defined in YaBB and created and modified through the Edit Member Groups function in the Admin Center.  Members are added to these member groups through individual member Profile pages.  Members are added to the Chat Group only through member groups, not as individuals.

Member group names should be entered in the boxes with a comma between each group name and no spaces between group names:

GroupOne,Group Two,Global Moderators   ==> Correct
GroupOne, Group Two, Global Moderators ==> NO! Use no spaces between group names!
GroupOne|Group Two|Global Moderators   ==> NO! Commas are the only separator used!


Show Timestamp?  This setting controls whether or not timestamps are shown in the chat window.


Show Top Info Frame?  Allows the Admin to choose whether or not to show the top frame showing the date, login time, IP address, chat level and position.

Pop-up Alert when User Enters Chatroom?  The pop-up alert setting controls whether a pop-up window alerts users in the chatroom that a new user has entered the room.  This is handy for users who are hanging out in the chatroom waiting for other users to arrive.


Max Message Length:  This setting controls the maximum length of a single message. The maximum value is 200 characters.

Chat Refresh:  This setting allows the Admin to control the length of time between chat window refreshs.  Shorter times equal higher cpu/bandwidth usage.

Maximum Number of Chat Messages: This setting controls how many messages appear in the chat window.  If your users post a lot of images in the chat window or use large smilies, this setting can be decreased to reduce window scrolling and to reduce bandwidth and refresh time.

Kick Time:  The length of time to prevent users from posting and viewing messages when kicked out of the chatroom (in seconds).  Note that once a user is kicked there is no way to "un-kick" them before the Kick Time has passed.  Not even an Admin can "un-kick" a user.

Add More Smilies for Chatroom:  On forums using the Add More Smilies mod, version 2.1, these settings control the appearance of the smilie features in the chatroom.  See the Add More Smilies mod documentation for an explanation of their use.  To use the Add More Smilies features, the forum must have the Add More Smilies 2.1 mod loaded and the version of Chat.pl file designed for this mod.   These settings will have no effect on forums not using the Add More Smilies mod.

Show Line of Smilies below Message Box?  Check this box to display the standard smilie set beneath the Message Box.  This control applies to forums with/without the Add More Smilies mod.

Enter Chat Info Screen Text Here:  This text box is used to set the contents of the Chat Info Screen users see when they first enter the chatroom and when they click the Info button.  HTML code is allowed here but YABBC (board code) is not supported.  Carriage returns (end of line characters) will be converted to HTML line breaks automatically.  Don't use any double quote " characters here.  Use single quote ' characters instead.


Set Chat Shortcuts: Chat shortcuts are key words that are replaced by longer phrases, YaBBC tags, or a combination of both when typed in the chatroom.  To set chat shortcuts enter key word - expanded phrase pairs in the text box separated by the | character, one pair to a line, such as keyword|This is the phrase that appears.  If the line wraps, that's okay.  This is similar to entering word pairs in the YaBB censor list.

Chat shortcuts are case sensitive.  The word "Poe" is not the same as "poe".

The key words "help", "chatcontrol", and "chatshortcuts" are reserved (these are edited in the language file, settings $chadmtxt{'53'}), $chadmtxt{'40'}, and $chadmtxt{'87'}.

Don't use words that are already used in YaBBC tags to create keywords.  For example, creating a shortcut like url|Some phrase would prevent the [url][/url] YaBBC tag from working in your chatroom because the closing [/url] tag would be converted to your shortcut phrase.  Also, avoid using the same prefix for multiple keywords as the results may be unpredictable.

To add line breaks to the associated phrases use *chatbreak* where you want the line break to appear, keyword|This is the first line*chatbreak*This is the second line.


Chat Levels:  The Admin may choose to grant users the ability to wipe the message area (Wipe Chat) or to kick other users out of the chatroom.  These abilities are assigned to member groups* through the Chat Levels table.

Level One:  Members of the member groups assigned to Level One have all basic chatroom functions.  All member groups are assigned to this level by default so there isn't really any reason to assign a member group to Level One.  This setting may go away in future version in order to simplify things.

Level Two:  Members of the member groups assigned to Level Two have all basic chatroom functions plus the ability to wipe the message area.

Level Three:  Members of the member groups assigned to Level Three have all basic chatroom functions, the ability to wipe the message area, plus the ability to kick users out of the chatroom temporarily.

* The member groups discussed here are the member groups defined in YaBB and created and modified through the Edit Member Groups function in the Admin Center.  Members are added to these member groups through individual member Profile pages.  Members are added to the Chat Group only through member groups, not as individuals.

Member group names should be entered in the boxes with a comma between each group name and no spaces between group names:

GroupOne,Group Two,Global Moderators   ==> Correct
GroupOne, Group Two, Global Moderators ==> NO! Use no spaces between group names!
GroupOne|Group Two|Global Moderators   ==> NO! Commas are the only separator used!

Chatroom Help:  This link opens the YaBBChat Help file (this file).

Note for Non-English Language Forum Admins:

While most of the on-screen text is in the english.lng file, there are two exceptions:

The color names for the text color drop down list are in the file ecolor.txt.
The emotion names for the emotion drop down list are in the file eaddsays.txt.

These files are found in the Variables directory.  Edit these files to suit your language.



Quick Installation Instructions:
More detailed installation directions are found here for first time mod installers, worth reading.
 
  1. Unzip the YaBBChat_v1_98.zip file.
  2. Use Boardmod or manually make the changes in the chat_v1_98.mod file (use chat_v1_98_SP_1_3.mod file for SP 1.3 forums).
  3. Upload modified files (english.lng, Admin.pl, BoardIndex.pl, template.html, and YaBB.pl or SubList.pl ) in ASCII mode.
  4. Put Chat.pl, ChatSSI, and ChatSettings.pl in your Sources directory.  Be sure to use ASCII mode.
  5. Put ChatSettings.txt, ChatCount.txt, ecolor.txt, online.txt, says.txt into your Variables directory. Be sure to use ASCII mode.
  6. Chmod ChatSettings.txt and ChatCount.txt to 666 (world read/writable).
  7. Chmod online.txt and says.txt to 777 (world read/writable/executable).
  8. Put close.htm in your images directory.  Be sure to use ASCII mode.
  9. Put all images (.gif files) in the images folder into your YaBB Images directory.  Be sure to use binary mode.
  10. Put the YaBBChatHelp.html file into your YaBB Help directory.  Be sure to use ASCII mode.
  11. Put all the images (.gif files) found in the help folder into your YaBB Help directory.  Be sure to use binary mode.
  12. Put the ubbc_for_chat_1_98.js file in your ubbc directory (the directory where your ubbc.js file resides).


!IMPORTANT!  Before trying to open the chatroom for the first time, go to the Chatroom Control Center in the Admin Center and click "Apply Changes" to write the default chatroom settings to your ChatSettings.txt file.  The first time you open the Forum Prefs/Settings page these settings may be empty.  Don't  worry, just hit the "Apply Changes" button.  The next time you open the Chatroom Control Center, the chatroom default settings will be there.

If you have a previous version of YaBBChat installed, it will need to be uninstalled before installing the new version.  Also, after uninstalling the old version and installing this version, go to the Forum Prefs/Settings section of the Admin Center and click the "Save" button.  This will remove chat settings from your Settings.pl file. This will help keep your Settings.pl file free of un-needed stuff.

Special note for YaBB.cgi users:  Change YaBB.pl to YaBB.cgi in the mod file <edit file> statement before running BoardMod.

As always, please backup your system before installing, and please feel free to report any bugs on the BoardMod forum.



Detailed Installation Directions:
(Thanks to Tgnirrep for writing this,modified slightly by Ironwing)

This chat mod includes a script, chat_v1_98.mod (use chat_v1_98_SP_1_3.mod for SP 1.3 forums), which can be used with the Boardmod program to automatically update the files needed for chat. The Boardmod program is available on the BoardMod website.  It greatly eases modification installation.  Doing it manually can lead to madness!

There are five or six files (depending on YaBB version) modified by chat_v1_98.mod and many additional files, including Chat.pl and close.htm, provided in the zip file. After completing the modifications you should have:

In the YaBB subdirectory:

Upload these files in ASCII mode.

YaBB.pl (or cgi)  ..... replace the existing YaBB.pl (or cgi) with this modified file (for YaBB SP 1 - 1.2 only).  Chmod 755.
template.html  ..... replace the existing template.html with this modified file.  Chmod 777.
english.lng ..... replace the existing english.lng file with this modified file.


In the Sources subdirectory:

Upload these files in ASCII mode.

Chat.pl ..... this is a new file, put it in the sources subdirectory.
ChatSSI.pl ..... this is a new file, put it in the sources subdirectory.
ChatSettings.pl ..... this is a new file, put it in the sources subdirectory.
BoardIndex.pl .....   replace the existing file in your sources subdirectory with this modified file.
Admin.pl ..... replace the existing file in your sources subdirectory with this modified file.
SubList.pl.....replace the existing file in your sources subdirectory with this modified file (for YaBB SP 1.3 only).


In the Variables subdirectory:

Upload these files in ASCII mode.

ChatSettings.txt, ChatCount.txt, ecolor.txt, online.txt and says.txt ... These six files are new and are provided in the zip file.
Chmod ChatSettings.txt and ChatCount.txt to 666 (world read/writable).
Chmod online.txt and says.txt to 777 (world read/writable/executable).


In the YaBB Images subdirectory:

There are seven new gif image files found in the images folder. Upload them, using binary transfer, to your yabbimages subdirectory.


Also in the YaBB Images subdirectoy:

Upload this file in ASCII mode.

close.htm ... this is a  new file, upload it in ASCII mode.  Why in the yabbimages directory?  Because everybody's got one.
In the YaBB Help subdirectory:
Load the YaBBChatHelp.html, in ASCII mode.  Load the gif image files found in the help folder to the YaBB Help directory in binary mode.
In the ubbc directory:

Upload this file in ASCII mode.

Load the ubbc_for_chat_1_98.js file in your ubbc directory (the directory where your ubbc.js file resides).


!IMPORTANT!  Before trying to open the chatroom for the first time, go to the Chatroom Control Center in the Admin Center and click "Apply Changes" to write the default chatroom settings to your ChatSettings.txt file.  The first time you open the Forum Prefs/Settings page these settings may be empty.  Don't  worry, just hit the "Apply Changes" button.  The next time you open the Chatroom Control Center, the chatroom default settings will be there.



Using the Add More Smilies mod in the Chatroom:

A special version of the Chat.pl file is included with this mod to enable the features of the Add More Smilies mod (version 2.x) inside the chatroom.  To use, load the file Chat_add_more_smilies.pl to your /Sources directory in ASCII mode and rename it to Chat.pl.  The Add More Smilies mod, version 2.x, must also be working on the forum in order to use this special version of the chatroom.



Showing Users in the Chatroom on Other Web Pages (SSI):

The following server side include statements will display the names of users and the number of guests currently in the chatroom.

For guests:
<!--#include virtual="/cgi-bin/yabb/YaBB.pl?action=printguestsonchat"-->

For users:
<!--#include virtual="/cgi-bin/yabb/YaBB.pl?action=printusersonchat"-->
 

The following server side include statement will display the latest public chatroom messages.

<!--#include virtual="/cgi-bin/yabb/YaBB.pl?action=chatssi"-->

Correct the tags to reflect the path to your yabb forum from your root web directory.  Note that many servers require that an HTML page carrying an include statement like the one above have an .shtml extension instead of an .html or .htm extension.



Version History:
 (for SP1 version)

Version 1.98 (this version):

Version 1.97: Version 1.96: Version 1.95:    Sparkiegeek's release: Version 1.94: Version 1.93: Version 1.92: Version 1.91: Version 1.9: Version 1.8:    Fixed bug in displaying who is on chat.
Version 1.7:    Fixed minor bug with Guest chatting.
Version 1.6:    Put more colors in Prefs/Setting.  Moved all? english text to english.lng.  Fixed color setting bug.
Version 1.4:    Fixed path to close.htm again after many complaints about 1.3.  close.htm now goes in the images directory!
Version 1.3:    Fixed path to close.htm (didn't work for some folks so onto version 1.4!)
Version 1.2:    Changed Chat.pl code to use either YaBB.pl or YaBB.cgi.
Version 1.1:    Fixed another Boardmod tag for the Admin.pl file.
Version 1.0b:    Fixed minor formatting, updated default colors to better match SP1 defaults.
Version 1.0a:    Fixed Boardmod tags.



Credits:

Samm, Omario (Shoeb Omar), and _Max. wrote the original YaBBChat mod for YaBB version Gold -  Release.

Ironwing converted the mod to YaBB Gold SP1 and currently maintains and develops the mod.

Sparkiegeek made much needed improvements to the mod in version 1.95.

Smilies code converted from Add More Smilies mod by Shoeb Omar.

Please post any questions or report any bugs on the BoardMod forum.