Jitbit AspNetForum README

Thank you for choosing Asp.Net Forum from Jitbit Software. This README will guide through the basics of installation and operation of Asp.Net Forum. Please read it carefully. Thank you.

IMPORTANT: before installing and using Jitbit AspNetForum read the License Agreement located in "!!!license.txt" file.

Contents:

1. INSTALLING ASPNETFORUM
1.1. Distribution package
1.2. Installing AspNetForum as a standalone web app
1.3. Installing AspNetForum under an existing web site (no separate web application or virtual directory)
2. DATABASE SETUP
2.1. Database Setup
2.2. Database connection
2.3. Pre-created forum users
3. UPGRADING FROM PREVIOUS VERSIONS
4. CONFIGURING ASPNETFORUM
4.1. ADMIN PASSWORD
4.2. FORUM TITLE BAR
4.3. EMAIL NOTIFICATIONS
4.4. LANGUAGE
4.5. LOOK AND FEEL
4.6. INTEGRATING INTO YOUR WEBSITE'S DESIGN
4.7. FREE FOR ALL FORUM
4.8. SEO-Friendly URLs
4.9. OTHER Web.Config options
4.10. Windows authentication or SINGLE SIGN ON with the parent website

1. INSTALLING ASPNETFORUM

1.1. Distribution package

The ASP.NET forum software is distributed in a ZIP-archive, which contains:

1.2. Installing the Forum as a standalone ASP.NET application:

1.3. Installing this Forum as a sub-part of an existing ASP.NET application (a website or a folder) without configuring as a standalone web-application:

2. DATABASE SETUP

2.1. Database Setup

This ASP.NET forum contains the "/App_Data" folder, which contains:
  1. setup scripts for MS SQL Server ("/SQL scripts" subfolder)
  2. setup scripts for MySQL ("/MySQL scripts" subfolder)
  3. MS Access initial database ("forum.mdb" file)
  4. SQL Server Express initial database ("forum.mdf" file)

This forum's web.config file has several sample connection strings in it (see the "connectionStrings" section of the file). One for MS Access, one for for MS SQL, one for MySQL etc. By default, the MS-Access connection string is uncommented, others are commented out.

2.2. Database connection

When you edit the connection strings in the "web.config" file please note that apart from editing the connection string itself (in the connectionString attribute), you have to specify a value of the providerName attribute. This will tell ASP.NET (and AspNetForum) what database driver to use.

For example:

As you can see, this allows Jitbit AspNetForum using not only MS Access or MS SQL database, but, theoretically, any database engine, which has a .NET provider.

Note for MySQL users: To use the Forum with MySQL you have to download and install the free "MySQL Connector .NET" on your server. The download is available here - http://dev.mysql.com/downloads/connector/net/. Please ask your hosting provider if they have this driver installed. If they do not - simply place the "MySql.Data.dll" from the downloaded package into the "/bin" folder. Contact your hosting provider for more info. More information on "MySQL Connector .NET" is available at http://www.mysql.com/products/connector/net/

2.3. Pre-created forum users

Both MS Access and MSSQL/MySQL default databases come with a pre-created user "admin". The user's password is "admin". Log in under these credentials to start using the forum. But remember to change the default password afterwards!

3. UPGRADING FROM PREVIOUS VERSIONS

VERY IMPORTANT, read carefully

Sometimes a new version uses an updated database format. These database changes are usually light and simple, so there should be no problem to upgrade your existing copy.

3.1. MS SQL and MySQL users:

The installation package can contain one or more files named "upgrade_from_XXX.sql" in the App_Data folder, where "XXX" is a forum version. Depending on your existing version, execute the appropriate file. The file contains text comments, describing the changes made. Read these comments carefully.

The upgrade scripts are not cumulative. This means that, for example, if you are upgrading from the oldest version, you have to apply all the scripts one by one.

3.2. MS Access users:

The installation package contains the "forum.mdb" database file. This file is the new updated database format. Open two copies of MS Access: one with your existing "forum.mdb", and one with the new downloaded "forum.mdb".

You can always look at the "upgrade_from_XXX.sql" files, which contain text comments, describing the changes, made to the database format (see the above paragraph for SQL users), to know WHAT columns and tables have been added or removed.

4. CONFIGURING ASPNETFORUM

4.1. ADMIN PASSWORD

!!!IMPORTANT NOTE!!! Please note, that default database comes with a pre-created user "admin". The default password is "admin". CHANGE THAT!!!

4.2. FORUM TITLE BAR.

By default AspNetForum comes with an "Acme Web Site" title. This title is used in forum notification emails, and in forum pages title. You can change this to whatever you like by editing the "web.config" file. Find and edit this lines: 

<add key="ForumTitle" value="Acme Web Site" />
<add key="TitleLink" value="http://www.jitbit.com/" />

4.3. EMAIL NOTIFICATIONS.

AspNetForum can be configured to send email notifications to subscribers when topic and forums are updated. Emails are sent asynchronously, without affecting the forum performance. To enable email notifications you should edit the web.config and specify your smtp-server's address, specify the smtp-server login/password (if your server does not require authentication simply leave the username field blank) etc.

INPORTANT NOTE: the Forum also has the "Email Verification" feature which also requires you to specify smtp-credentials in web.config.

4.4. LANGUAGE

AspNetForum is a multi-language forum application. It is "globalized" using resource strings, which is a standard ASP.NET technique.

The application comes with a number of predefined languages. You can switch between these languages editing the web.config.

If you are a little familiar with ASP.NET you can easily add more languages by adding the required .resx-files to the "App_LocalResources" folder, using the existing files as templates. Please contact us to get a discount for you translation.

4.5. LOOK AND FEEL

To modify the html-code of any forum page edit the appropriate ".aspx" file. Be careful when editing .NET-controls code (tags like "<asp:textbox>"). Backup the files before editing.

You can also edit the "aspnetforum.css" file and modify images.

4.6. INTEGRATING INTO YOUR WEBSITE'S DESIGN

The Forum utilizes ASP.NET 2.0 "MasterPages" functionality. All AspNetForum pages use one masterpage called "AspNetForumMaster.Master". All you have to do to visully integrate the Forum software into your website - is edit this one file only ("AspNetForumMaster.Master"), and configure it to use your parent website's masterpage. This trick is called "nested masterpages". To make it work properly you should also edit "AspNetForumMaster.Master" and remove the "<form>", "<html>", "<body>" and the "<head>" tags, and replace them with the "<asp:Content>" instead.

If you plan to use the "nested masterpage" trick, please make sure that your parent masterpage DOES NOT disable the ViewState, since the forum software requires it for some features (polls, for instance)

4.7. FREE FOR ALL FORUM

You can allow unregistered guest-users to post messages. To do this edit the forum's Web.config and set the "AllowGuestPosts" flag to "true".

You can also mark some "forums" inside the application as "members only", so Guests will not be able to read messages there.

4.8. SEO-FRIENDLY URLs

This forum application can generate topic/forum urls in a search-engine-friendly manner. Instead of "messages.asp?TopicID=1000" it provides "topic100-this is-the-topic-title.aspx"

Here is the .web.config section responsible for this:

<httpModules>
   <add type="aspnetforum.ForumSEOHttpModule, aspnetforum" name="ForumSEOHttpModule"/>
</httpModules>

PLEASE NOTE: if you are installing the forum under an existing application, then move this whole "httpModules" section to your parent application's web.config!!! (inside the "system.web" section)

You can also comment-out this entire section to disable this funtionality

4.9. OTHER Web.Config options

4.10 Windows authentication and SINGLE SIGN ON

Now this is a tricky part, so read carefully:

  1. Windows authenticaton and NO parent website

    If you want to install the forum as a standalone ASP.NET application (with no parent application) and you want the forum to authenticate your users with their windows-accounts, you have to:

    1. Configure the IIS-server to use Windows-integrated authentication (with "anonymous access" disabled)
    2. Uncomment this line to the forum's web.config: 
      <authentication mode="Windows"></authentication>
  2. ASP.NET authentication via parent website.

    If you run a website where users already have an account and you don't want them to create another account for the forum, AspNetForum offers an option of "single sign-on" for your users. First of all, install the Forum so that the Forum and your website share the same ASP.NET Session. To share the same Session, DO NOT configure the "/forum" folder as a virtual directory/application. Instead, make it a part of your website-application, as described above (section 1.2). Now you have two options:

    1. If your website uses ASP.NET Forms Authentication (for example, in conjunction with ASP.NET membership provider) or ASP.NET Windows authentication, then AspNetForum can be configured to recognize your authenticated users, and automatically register them as forum users (and login automatically). To enable this feature simply edit this line in the web.config:
      <add key="IntegratedAuthentication" value="false"/>
      and change "false" to "true".

    2. Custom  authentication model. If your website uses some custom authentication procedure, AspNetForum still has the ability to pass credentials to it. The first IMPORTANT thing to do is - when a new user is registered on your website, you should add a record to aspnetforum's "Users" table. Also you should transfer your existing users to this table.

      Next steps are simple. The Forum uses ASP.NET "Session" object to store the current logged on user. There are two variables: Session["aspnetforumUserID"] (the user's ID in forum database) and Session["aspnetforumUserName"] (the user's name in forum). You can assign these variables in your website code and aspnetforum will authenticate the current user.

      This will work only when your website and AspNetForum are configured to share the Session. Which means that the Forum should be installed under the existing website (web-application) and is NOT configured to be a separate web-application.

      Code example 1 - adding a new user (this sample code if for AspNetForum using MS Access):

          //Code sample - ADDING A NEW USER TO THE FORUM'S DATABASE.
    //This sample assumes you use MS Access DB. It wont work with SQL Server or MySQL!!!
    System.Data.OleDb.OleDbConnection cn;
    System.Data.OleDb.OleDbCommand cmd;
    
    //Creating a connection to the forum database (remember to
    //edit the connection string)
    cn = new System.Data.OleDb.OleDbConnection(
        "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Inetpub\wwwroot\db\forum.mdb;Jet OLEDB:Database Password=DB_PASSWORD;");
    cmd = new System.Data.OleDb.OleDbCommand();
    cmd.Connection = cn;
    
    //Inserting a new user
    cmd.CommandText = "INSERT INTO ForumUsers (UserName, Email, Password, Homepage, Interests, RegistrationDate, Disabled, ActivationCode) " +
        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
    cmd.Parameters.AddWithValue("@UserName", username);
    cmd.Parameters.AddWithValue("@Email", email);
    cmd.Parameters.AddWithValue("@Password", password);
    cmd.Parameters.AddWithValue("@Homepage", homepage);
    cmd.Parameters.AddWithValue("@Interests", interests);
    cmd.Parameters.AddWithValue("@RegDate", DateTime.Now);
    cmd.Parameters.AddWithValue("@Disabled", false);
    cmd.Parameters.AddWithValue("@ActivationCode", "");
    cn.Open();
    cmd.ExecuteNonQuery();
    cn.Close();

      Code example 2 - authenticating a user:

          //code sample - Pre-authenticate a user for the forum
    //This sample assumes you use MS Access DB. It wont work with SQL Server or MySQL!!!
    System.Data.OleDb.OleDbConnection cn;
    System.Data.OleDb.OleDbCommand cmd;
    
    //Creating a connection to the forum database (remember to
    // edit the connection string)
    cn = new System.Data.OleDb.OleDbConnection(
        "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Inetpub\wwwroot\db\forum.mdb;Jet OLEDB:Database Password=DB_PASSWORD;");
    cmd = new System.Data.OleDb.OleDbCommand();
    cmd.Connection = cn;
    
    //Get the user's ID from the forum database
    cmd.CommandText = "SELECT UserID, UserName FROM ForumUsers WHERE UserName=? AND Disabled=?";
    cmd.Parameters.AddWithValue("@UserName", username);
    cmd.Parameters.AddWithValue("@Disabled", false);
    cn.Open();
    System.Data.OleDb.OleDbDataReader dr = cmd.ExecuteReader();
    if(dr.Read())
    {
        //Assign two session variables - and the user will be treated
        // as authenticated by the forum
        Session["aspnetforumUserID"] = (int)dr[0];
        Session["aspnetforumUserName"] = dr[1].ToString();
    }
    dr.Close();
    cn.Close();
© Jitbit 2005-2010 Asp.Net Forum