Introduction
The SwirlChat Module for DotNetNuke is designed to offer a comprehensive chat experience for your website visitors and members. It includes many features found on popular chat environments, and utilizes the latest Ajax technologies to offer the fastest and most robust chat module currently available for DotNetNuke.
This module requires ASP.NET 2.0 or higher, running DotNetNuke 4.4.1 or higher. For more information about compatibility with your environment, please visit our website: http://www.swirlhost.com/chatroom.
Features
The latest version of SwirlChat for DotNetNuke includes the following features:
Multiple Rooms – you can create many different rooms easily accessible from within the module. Permissions – you can create custom permissions to allow different roles to have differing capabilities.
Moderation – allows you to kick users, ban users, and ban ip addresses.
Emoticons – are small emotion based images which chat participants can use to express their moods and impressions.
Custom Themes – includes 4 different visually appealing themes to choose from. More themes are to be added in future releases, and new themes can be customized by administrators.
Conversation Boxes – chat messages are grouped in conversation boxes similar to other popular chat and instant message applications.
Private Messaging – Users can now engage in private messages with each other in a very easy to use tabbed format similar to IRC and other popular chat applications.
Host Installation
In order to get the SwirlChat Module up and running there are a few steps in which the DotNetNuke host user must perform to enable the AjaxPro provider, and install the license information. The following instructions must be performed ONCE during the initial setup of the chatroom.
- Upload the module using the Host > Module Definitions > Install New Module menu. This will install two modules: SwirlChat and SwirlChat Users.
- After installing the module, add the module to a page on your site to continue with the first time installation procedures. (Make sure you are logged in as “Host” in order to complete the remainder of these steps).
- After you have added the module to a page on your site, you will need to open the module’s “Host Settings” menu as shown:
- On the module’s “Host Settings” page, first you will need to enable AjaxPro on your site in order for the high speed Ajax functions to operate within the chatroom module. To do this, simply click on the “Enable AjaxPro” option in the top portion of the screen (NOTE: you will need to do this even if you have already enabled Microsoft Ajax.NET, or prior versions of AjaxPro for previous chatroom installations!):
- Once you have enabled AjaxPro on your site, the message at the top should now read: “Congratulations! Successfully updated AjaxPro!”:
IMPORTANT NOTE!
If you EVER decide to remove the SwirlChat module from your website completely, you MUST FIRST DISABLE AJAXPRO using the “Disable AjaxPro” button on this screen BEFORE you uninstall the module. Failure to do so may cause your DotNetNuke installation to become unresponsive and may require manual administration of your Web.Config file. Please remember to Disable AjaxPro if you ever decide to remove this module from your website!
- Now, you will need to fill in the remainder of the Host Settings for the SwirlChat Module. These settings are host-wide and affect all portals on this DotNetNuke installation. This is also where you can apply your license information that you have obtained from Swirlhost. See the legend below the following image for more information about each option:
- Poll Frequency: This is the frequency in which clients will poll the server to look for new messages. A higher value means slower polling, but less strain on the server. A lower value means faster polling, but more strain on the server.
- User Cleanup Frequency: This is the frequency in which the chatroom will perform “user cleanup” to remove users from rooms after the client user has left a room (no longer polling for messages). A higher value means slower cleanup, but less strain on the server. A lower value means faster cleanup, but more strain on the server.
- Number of Previous Messages: This is the number of previous messages in room conversation which will be visible when a user joins the room. This allows newly joined users to see the previous conversation in the room. You can use “0” to show NO previous messages.
- Filtered Words: This is a comma-separated list of words that will be filtered (replaced) with asterisks (*****). You can use this to keep your room free of filthy words and comments. Do not put a trailing comma at the end.
- License Keys: You will need to enter your license keys obtained from Swirlhost in order to use the chatroom on a production (Internet Facing) server.
- Once you have entered all the options and your license keys, you can click on “Update” to return to the chatroom. By default, a new room called “Default Room” will automatically be created for you. You can change the name of this room, or create new rooms. You have finished the Host Installation for the chatroom!
Module Settings
In the module settings, you can choose from one of the four included chatroom templates, you can specify a default room to show for this instance, and you can specify whether you want to “lock” this instance to the default room. If you lock the instance to a specific room, users will not be able to change to other rooms from this particular instance of the chatroom on the page.
A. Skin – you can select one of the four included skins/templates for the chatroom for this instance.
B. Default Room – you can select which of the portal rooms you want to show by default when someone comes to this page.
C. Lock Room – check this box if you want to “lock” this instance of the chatroom to ONLY show the default selected room. If checked, users will not be able to change rooms from this particular instance.
Room Managers
Room Managers are the groups of website users whom you want to grant special privileges to manage the rooms on your site. By default all HOST users and all ADMINISTATORS are automatically defined as Room Managers and can manage all aspects of all rooms on the given site. You can add more roles to the Room Managers by following the instructions below:
1. First, you must login as either Host or an Administrator to perform these procedures. Please login to your site if you have not already done so.
2. Find a page which has an instance of the chatroom module installed, and open the “Room Managers” module menu as shown:
3. This will open the role selection screen for defining additional Room Manager roles on your website. Choose the additional roles in which you want to add, and then click on “Update” at the bottom of the screen:
4. Now that you have defined your Room Managers, you can begin to setup your rooms and room permissions.
Room Setup
In SwirlChat, rooms are defined across the entire website (portal). These rooms can be accessed from any instance of the chatroom, allowing you to place the chatroom on any page of your website and allow your members and visitors to participate in various discussions. Each chatroom has many options and features which can be configured to suit your needs. Please refer to the following instructions and illustrations to see all of the features of the rooms.
Room Managers (which were defined above) will each now have access to the “Room Manager” button from within the chatroom:
Clicking on this button will open the Room Manager dialog to manage all aspects of the rooms on the website. The following illustrations will explain each of the functions for managing the rooms.
General Tab
A. Room List– This lists the rooms currently created on your website. You may select a room on the left to define the options on the right.
B. Room Name– Enter a name for the selected room.
C. Operator Mode– Check this option if you want the room to run in “operator mode”. This will cause room operators to be notified when someone enters this room. (see Room Users below for how to define room operators)
D. Operator Wait Message– Type a message which will be displayed to users when they enter the room if it is running in “operator mode”. This only applies if the Operator Mode selection is checked for this room.
E. New Room Button– This button will allow you to create a new room on your site.
F. Delete Room Button– Use this button to delete the currently selected room. All messages, user settings, and other definitions for this room will be removed.
G. Save Room Button– Use this button to save changes you have made to the selected room.
H. Close Button– This will close the Room Manager dialog. You must save your changes before closing the dialog.
Permissions Tab
Select the “Permissions” tab for the selected room to define role based permissions for interactively managing the room. The following definitions describe each of the permissions available when selected (checked):
A. Post Chat– Users in this role may post messages in the room. If this is not selected for a given role, then users in the role will not be able to post messages in the chat.
B. View Chat– Users in this role may view the messages in the room. If this is not selected for a given role, then users in the role will not be able to even view the messages.
C. View Log– Users in this role will be able to view the log for the room. The log contains all messages in the room, but not any private messages between users.
D. Kick User– Users in this role will be able to temporarily kick users out of the room. When users are kicked, they are not able to view or post chat for 20 seconds and receive a warning on their screen.
E. Ban User– Users in this role will be able to ban other users from the room. If a user is banned from a room they cannot participate in the room in any way. Please be careful when assigning this permission. Never ban the Host user or Admin user from any room.
F. Ban IP– Users in this role can ban user’s IP address. This ensures that the user cannot come back to the room under any other assumed names. Please be careful when assigning this permission.
Room Users Tab
This tab allows you to manage the users who have ever accessed this room. Each column is described below:
A. Nick– This is the current nickname last chosen by the user. Remember, each user can define a nickname for each room.
B. Last Active – This column shows the date when this user last entered the chatroom.
C. Logged In – Shows if the user is currently logged into the room at this moment.
D. Banned – This is a selection column which allows you to ban the user. Once selected and saved, the user is immediately banned from the room, even if they are currently logged in.
E. Operator– This is where you can define a user as an “Operator”. If a user is defined as an operator, and the room is running in “Operator Mode”, then this user will receive an email notification when a “non-operator” joins the room. (useful for help/sales desk environments). ONLY DotNetNuke users may be defined as operators.
Banned IPs Tab
The Banned IPs tab allows you to see and specify the IP addresses which have been banned for this room. You can ban a specific IP address, or you can ban a complete subnet.
To ban a specific IP address, click on the “New Address” button, and a new box will be added for you to type the IP address.
To ban an complete IP subnet, click on the “New Address” button, and enter the partial IP address followed by a “percent sign”. For example to ban ALL IP addresses in the “192.168.1” subnet, you would type: “192.168.1.%” in the IP address cell.
To remove a ban, simply clear the cell by deleting the contents.
Viewing the Chat Log
Users who have been granted the ability to view the log for any given room will see a button titled “Log” (or equivalent for your language) on the chatroom menu bar:
Clicking on this button will open the Chat Log Dialog to view the log for the chatroom:
When first opened the log will show the current day’s log. However, you can specify explicit date ranges by selecting the “from” date in the first date selection box, and the “to” date in the second selection box and click on “Display”.
You will notice that the log shows the following columns in the display:
A. Timestamp
B. IP Address
C. From (Nick)
D. Message Text
The IP address is also a hyperlink to www.dnsstuff.com, and performs a “whois” lookup on the IP Address to see who owns the IP address.
Quick Add Room
Room Managers will also have a button to quickly add a room to the site. Clicking on this button will open a dialog to enter a room name. The room will immediately be added to the site with Administrator-Only access:
Once the room is created, the Room Manager can visit the “Room Manager” dialog to assign any specific permissions if needed.
User Context Menu
When you click on another user in the “Room Users” area, you will be presented with a context menu based on your permissions in the room. The illustration below shows all of the possible user context menu options.
Popout Chat
All users will see a popout button on the menu bar. This button allows the user to popout the chatroom in a smaller window so that they may continue browsing the website and still participate in the chat discussion:
Clicking on this button will force a new window to pop up with a smaller version of the chatroom similar to the following illustration.
My Settings
Each user has a number of options which can be changed for their own preferences. These options can be selected from the “My Settings” menu bar option within the chatroom. Each of these options is saved for the user within the DotNetNuke system and are automatically retrieved each time the user re-visits the room.
A. Play sound on New Message – checking this option will cause a notification sound to play when a new message appears in the room.
B. Focus Window on New Message – checking this option will cause the browser window (Firefox and IE only) to come forward to bring attention when a new message appears in the room.
C. Scroll Screen on New Message– checking this option will cause the message area to scroll to the bottom each time a new message appears.
D. Change Nick– allows the user to specify a new nickname for this room.
E. My Status– allows the user to change their status. The icon next to the persons nickname in the “Room Users” area will change according to the selected status.
SwirlChat Users Module
The SwirlChat Users module is an additional module installed during the install process. This module allows you to optionally add a room/users list to any page on your website to show which rooms are available and how many users are participating in the chat within each room. This module is similar to the DotNetNuke core module “Who’s Online”.
Each room defined in your site is included, and you can configure the module to hyperlink the rooms directly to a page on your site with the chatroom module installed.
After you place an instance of this module on your site, you’ll need to configure the TABID where you want your visitors to be directed when they click on a room link. To do this, select the “Settings” menu option from the Module Menu:
On the Settings screen, expand the SwirlChat Users Settings area, and enter the TABID where your chatroom module is installed. You can find your TABID by visiting the page where the module is installed, and note the Tab ID in the address bar.
Frequently Asked Questions
Q. How do I setup a room to run in Operator Mode?
A. Refer to the section above titled: “Room Setup”. The options you’ll need to configure are on the “General” tab and the “Room Users” tab. Remember, only DNN users can be set as “operators”, and you must make sure you have properly setup your SMTP information in the DNN Host Settings configuration in order for email notifications to work.
Q. I installed the SwirlChat module, and later decided to uninstall the module from the Module Definitions. Now my website just displays an error. What went wrong?
A. When you install the SwirlChat module, you must enable AjaxPro in order for the chatroom to work properly. However, before you can uninstall the module, you must first disable AjaxPro. Refer to the section “Host Installation” above, specifically the “Important NOTE”. If you are experiencing this problem, you can contact the Swirlhost Support desk by sending email to: support@swirlhost.com.
Q. On the Chat Log dialog, why can’t I see the private messages between users?
A. Based on feedback from many differing users and many differing environments, it was decided that it is best to only display the messages posted into the room itself and not the private messages. If you are a host and have access to the “SQL” screen on your DotNetNuke website, our support team can provide a custom SQL query to view the private messages. For more information, please open a ticket with our support desk by sending email to: support@swirlhost.com.
If you have other questions or comments, please visit our website: