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 the forum
1.2.1 Installing AspNetForum as a standalone web app
1.2.1 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. Free for all forums
4.7. SEO-friendly urls and tags
4.8. Ratings and reputation system
4.9. Default avatars
4.10. Twitter and Facebook integration
4.11. List of all forum settings
5. INTEGRATING WITH PARENT WEBSITES
5.1. Integrating into your website's design
5.2. SINGLE SIGN ON with the parent websites and Windows authentication

1. INSTALLING ASP.NET FORUM

1.1. Distribution package

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

1.2 Installing the forum software

It is highly recommended to watch the forum installation video before you proceed with this manual.

You have two options to install the forum:

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

This is the recommended way to install the forum. Actually, this is the way the forum works on our website.

Please refer to a short video-tutorial on our website.

  1. Create an IIS virtual directory (e.g. "forum") and copy all the files and folders to it
  2. Configure this virtual directory as an application in IIS-manager
  3. Ensure this virtual directory runs ASP.NET 4.0 since Jitbit AspNetForum requires ASP.NET 4.0
  4. Grant write permissions on the "App_Data" folder to the user-account, that ASP.NET runs under. The user account name is either "ASPNET" for Windows XP, "NETWORK SERVICE" for Windows 2003/2008 Server or "IIS AppPool\DefaultAppPool" for Vista/2008 R2/Win7. Right click the folder, select the Security tab, click "Add", find the "ASPNET" / "NETWORK SERVICE" / "IIS AppPool\DefaultAppPool" accounts and add them with "full control" permissions to the folder.
  5. If you want the "SEO-friendly" URLs feature enabled, please see this section

1.2.2. Installing this Forum as a sub-part of an existing ASP.NET application (a website or a folder):

Choose this option if you want you want the forum to integrate with your existing ASP.NET authentication engine, or if you're installing the forum into a shared hosting where you can't create an application (like described above), or you have some other reasons for the forum to be just a subfolder of a bigger ASP.NET application.

  1. Create a subfolder in your website's directory (e.g. "c:\mywebsite\forum")
  2. DO NOT configure the forum subfolder as an "application" in IIS manager. But note that the parent website (or virtual directory) HAS to be configured as an application.
  3. Extract all the files and folders except the "/bin" and "/App_Data" folders into this "forum" subfolder including the "/images" subdir (contains forum images) and "/App_LocalResources" subdir (contains page resources for other languages)
  4. Extract the contents of the "/bin" and "/App_Data" folders into the parent website's "/bin" and "/App_Data" folders (e.g. "c:\mywebsite\bin").
  5. Please see the picture.

  6. Ensure that your website runs ASP.NET 4.0 since Jitbit AspNetForum requires ASP.NET 4.0
  7. Remove the entire "system.web" section from the forum's web.config file
  8. If you want the "SEO-friendly" URLs feature enabled, please see this section
  9. Grant write permissions on the "App_Data" folder to the user-account, that your website runs under. The user name is either "ASPNET" for Windows XP, "NETWORK SERVICE" for Windows 2003/2008 Server or "IIS AppPool\DefaultAppPool" for Vista/2008 R2/Win7. Right click the folder, select the Security tab, click "Add", find the "ASPNET" / "NETWORK SERVICE" / "IIS AppPool\DefaultAppPool" accounts and add them with "full control" permissions.

2. DATABASE SETUP

2.1. Database Setup

This ASP.NET forum comes with the "/App_Data" folder, which contains:
  1. MS Access initial database ("forum.mdb" file)
  2. SQL Server Express initial database ("forum.mdf" file) for installing using the "personal-instance" mode
  3. Database creation script for MS SQL Server ("aspnetforum_MSsql.sql" file)
  4. Database creation script for MySQL ("aspnetforum_mysql.sql" 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 MS SQL Express "user-instance", one for for MS SQL, and one for MySQL. 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

First, download the upgrade. To upgrade to the next version simply overwrite all the files in the forum folder EXCEPT:

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.

The ASP.NET forum comes with a built-in database upgrade engine. Open this URL to get to the engine: http://My-Server.com/forum/dbupgrade.aspx and follow the instructions.

Please note: this upgrade engine is compatible with MySQL, MS SQL and MS Access only. Also the upgrade requires that the database user-account has all the required permissions to create/alter tables.

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 in the admin area.

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 settings in the admin area 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 the settings.

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.

IMPORTANT: to save performance it is highly recommended to delete unused languages from the "App_LocalResources" folder.

4.5. LOOK AND FEEL

You might want to check the "integrating with your website design" section first (section 5.0).

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.

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.6. FREE FOR ALL FORUM

You can allow unregistered guest-users to post messages. To do this edit the forum's settings and set the "AllowGuestPosts" and (optionally) "AllowGuestThreads" flags 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.7. SEO-FRIENDLY URLS AND HTML-TAGS

This forum software is Search-Engine-friendly (SEO-friendly):

4.7.1. 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 under IIS 6:

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

Here is the .web.config section responsible for this under IIS 7:

<system.webServer>
  <modules>
    <add type="aspnetforum.ForumSEOHttpModule, aspnetforum" name="ForumSEOHttpModule" />
  </modules>
</system.webServer>

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

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

If you are using any version of ASP.NET MVC for your parent website, you need to add this line to your Global.asax RegisterRoutes function:

routes.IgnoreRoute("Forum/{resource}.aspx/");

SEO-friendly URLs will work fine assuming the Forum is in the directory called forum off the root of the parent website .

4.7.2. SEO-Friendly "meta" tags

The forum automatically generates the "meta" tags - <meta name="keywords"> and <meta name="description"> that are essential for search engines. The content of these tags is generated from forum and topic names and descriptions. On pages that are not topics and forums these tags are equal to the forum global "title" setting you set in the settings. If you want to override these tags, simply place this code:

<asp:Content ContentPlaceHolderID="ContentPlaceHolderHEAD" ID="AspNetForumHead" runat="server">
	 <meta name="keywords" content="test" />
	</asp:Content>
on a page and the forum won't put any auto-generated meta-tags on the page.

4.8. Ratings and reputation system

The forum software has a built-in reputation system (that can optionally be disabled in the settings). Every registered user can vote a message "up" or "down" by pressing the "thumbs up" or "thumb down" icons next to it. Every topic has a "show rated posts only" link that hides unrated answers and shows rated posts only, sorted by their rating (top-rated messages first). This handy feature makes finding useful posts really easy - when searching for an answer. Rating a message also adds (or subtracts) points to the author's "reputation" that is shown on his profile page.

4.9. Default avatars

The forum comes with some pre-installed avatars for your users to chose from, if they don't to upload their own. If you want to add some custom pictures to the predefined avatar list, simply put the files into the "images" folder, naming it "AspNetForumAvatarXXX.EXT" where "XXX" is any number, and "EXT is one of the "gif", "jpg", "png" extensions.

4.10. Twitter and Facebook integration

The forum software supports the "sign in with Twitter" and "login with Facebook" features. To enable it, you have to specify the following settings in the admin area:

4.10.1. Twitter

TwitterConsumerKey and TwitterConsumerSecret - these two settings are required for Twitter login integration. If you want the "Sign in with Twitter" feature available for your forum, obtain API keys from Twitter here (by entering your forum URL), and put into these two fields.

4.10.2. Facebook

FacebookAppID and FacebookAppSecret - these two settings are required for Facebook login integration. If you want the "Log in with Facebook" feature available for your forum, obtain API keys from Facebook here (by entering your forum URL), and put into these two fields.

4.11. List of all forum settings

All these settings are configured in the admin panel "Administrator - Configuration"

Resetting settings to default

If you messed with the settings in the admin panel and want to revert all changes, reset the setting to default values - edit this key in the "web.config" and set it to "true":

<add key="ResetSettingsToDefault" value="true"/>

5. INTEGRATING WITH PARENT WEBSITES

5.1. Integrating the look and feel into your website's design

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

If your website has a masterpage of its own, follow these steps:

  1. Assign your website's masterpage to the "AspNetForumMaster.Master" like this: 
    <%@ Master MasterPageFile="~/Parent.master" ..... %>
  2. remove the "<DOCTYPE>" tag from "AspNetForumMaster.Master".
  3. remove the "<html>" tag from "AspNetForumMaster.Master".
  4. remove the "<head>" tag from "AspNetForumMaster.Master", and move its contents to your parent website's masterpage. Move the "asp:contentplaceholder" which is inside to "body".
  5. remove the "<body>" tags from "AspNetForumMaster.Master".
  6. remove all the closing tags accordingly
  7. enclose all the remaining code in this file inside a "asp:content" tag like this:
    <asp:Content ContentPlaceHolderID="ParentPlaceHolder" runat="server">
	<asp:contentplaceholder id="ContentPlaceHolderHEAD" runat="server"></asp:contentplaceholder>
	<div class="topheader">
		<table cellspacing="0" cellpadding="0">
	.......
	.......
</asp:Content>

Once again, when removing code from the "AspNetForumMaster.Master" file don't remove the "ContentPlaceHolderHEAD" placeholder that looks like this: 

<asp:contentplaceholder id="ContentPlaceHolderHEAD" runat="server" >
</asp:contentplaceholder>
.

5.2 SINGLE SIGN ON (and Windows authentication)

This is a tricky part, please read this section carefully. You have three options:

  1. The forum controls the authentication itself

    - this is the easiest option, you don't have to configure anything. This is how the forum on our website works.

  2. Windows authentication (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. Edit this setting in the admin panel: IntegratedAuthentication and change "NO" to "YES".
    3. Edit this setting in the admin panel: AdminUserName and set it to your username (including the domain - "DOMAIN\username").
    4. Uncomment this line in the forum's web.config: 
      <authentication mode="Windows"></authentication>

    Please note that the forum will try to query your Active Directory for the user's email and first/last names.

  3. Authentication via parent website.

    If you run a website where users already have accounts and you don't want them to create another account for the forum, AspNetForum offers different options of "single sign-on" for your users. Choose one of the following:

    1. ASP.NET Forms/Windows Authentication. Jitbit Forum can share ASP.NET authentication with your parent website. If your website uses ASP.NET Forms Authentication (for example, in conjunction with ASP.NET membership provider), then AspNetForum can be configured to recognize your authenticated users, and automatically add them to the forum database. Follow these steps:

      • Install the Forum in a way that the Forum and your website share the same ASP.NET Session. In other words, DO NOT configure the "/forum" folder as a virtual directory/application. Instead, make it a part of your website-application, like described above (section 1.2).
      • Set IntegratedAuthentication setting in the admin panel to "YES"
      • If you want to pass user's First/Last names and email to the forum application, you can do this via ASP.NET Session var, or via ASP.NET Profile like this: 
        	HttpContext.Current.Session["Email"] = "user@email.server.com";
	HttpContext.Current.Session["FirstName"] = "John";
	HttpContext.Current.Session["LastName"] = "Smith";
        or like this 
        	HttpContext.Current.Profile.SetPropertyValue("Email") = "user@email.server.com";
	HttpContext.Current.Profile.SetPropertyValue("FirstName") = "John";
	HttpContext.Current.Profile.SetPropertyValue("LastName") = "Smith";

      That's it. The forum will try to recognize your users and add the missing ones to its database automatically.

      PLEASE NOTE: if the "IntegratedAuthentication" flag is enabled AND the "IntegratedMembership" flag is also enabled, the forum will try to access the ASP.NET membership provider to extract the user's email from it. Also, the forum will try to access the ASP.NET "profile" object and extract the user's email and first/last names from it, so you might want to store the user's data there. More info at this msdn artciel. The forum searches for the "Email", "FirstName" and "LastName" properties.

    2. Authentication API - the forum offers an authentication API that allows you to remotely authenticate your users even if you run the forum and your website on separate servers. To authenticate a user you simply have to point him to a special URL. Follow these steps:
      • Specify a "shared secret" setting in the admin panel ("AutoLoginSharedSecret" setting).
      • Make this shared key long enough, containing both uppercase and lowercase chars, numbers etc.
      • Redirect your authenticated users to the forum using this link format: http://MyForumUrl/AutoLogin.aspx?username=xxx&email=yyy&userHash=HASH where HASH is calculated as follows: MD5(name + email + shared-secret). Users who follow this link will be automatically authenticated by the forum (and added to it's internal database if necessary).
      You can also specify a "ReturnUrl" parameter in the query-string to tell the forum where to redirect the user after a successful login. 
      //C# MD5 hash function
public static string MD5Hash(string input)
{
  System.Security.Cryptography.MD5CryptoServiceProvider x = new System.Security.Cryptography.MD5CryptoServiceProvider();
  byte[] bs = System.Text.Encoding.UTF8.GetBytes(input);
  bs = x.ComputeHash(bs);
  System.Text.StringBuilder s = new System.Text.StringBuilder();
  foreach (byte b in bs)
  {
    s.Append(b.ToString("x2").ToLower());
  }
  return s.ToString();
}
    3. Passing credentials via session variables - if the forum is installed as a subfolder of a bigger app, you can pass credentials via the session variable.
      • 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, like described above (section 1.2).
      • IMPORTANT - 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.
      • 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-2011 Asp.Net Forum Software