Documentation

POP Forums v9 attempts to not get in the way of your application, by designating its views inside of an MVC area. It does, however, rely on MVC’s dependency injection resolver, and sets Ninject as the default resolver. Beyond that, you can choose whether or not you want the forum’s authorization to work everywhere, or just in controllers and actions for the forum. You can find more details in the integration section below.

How to use The Scoring Game in your own MVC application.

Upgrading?

If you're upgrading from v9.0 or v9.1 to v9.2, simply replace the existing files. You'll also have to run the PopForums4.xto4.2.sql SQL script against your existing database. That script can be found in the database project.

Installation

POP Forums tries to make installation as low-friction as possible. Here’s how to do it:

• Download the latest source code from CodePlex. Build it, if necessary.
• The PopForums.Web project has various folders that you’d expect in an MVC project:
  
  Also keep in mind that the /bin folder will contain several assemblies, including PopForums.dll, PopForums.Data.SqlSingleWebServer.dll, Ninject.dll and whatever the name of the Web project is. In our case, it’s PopForums.Web.dll.
• Web.config will require a section declaration for popForums, as well as a connection string. The default looks like this:
  
  The main purpose of the popForums section is to choose a connection string.
• Also in web.config, set a new base page type for Razor views:

<system.web.webPages.razor>
  <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
    <pages pageBaseType="PopForums.Web.PopForumsRazorViewPage">
      <namespaces> ...

•  Attempt to run the app either locally, or in IIS, and go to the URL /Forums to see an error page. It will fail either because the database isn’t set up, or because it can’t connect to it.
• Point the browser to /Forums/Setup now, and if your connection string is correct, you should see this page:
  
  Here’s what each field does:
  
  • Forum title: This is what your forum will be called at the root, in an h1 tag. You can edit this (and everything else) later.
  • SMTP Server: The host name of the server you’ll connect to for sending e-mail. Enabling this functionality on your server is beyond the scope of this document.
  • Port: Typically 25, though some services (like Gmail) use others.
  • From e-mail address: When a user receives e-mail from the forum, it will be “from” this address.
  • Use SSL: Check if your server uses or requires SSL.
  • Use ESMTP for credentials: Check this box if you have to authenticate with your server. Checking this makes the two boxes below it editable.
  • SMTP User: User name (often the e-mail address) to authenticate with. Not editable unless the “Use ESMTP” box is checked.
  • SMTP Password: Password to authenticate with. Not editable unless the “Use ESMTP” box is checked.
  • Time zone and Use daylight saving: Determines how your forum should handle time. This will also be the time adjustment your admin account will use. Both can be changed later.
  • Display name: How you want your name to appear in the forum.
  • E-mail: The e-mail address you’ll use to login with.
  • Password: The password you’ll use to login with.
• If you typed everything you need correctly, you should see a happy result, otherwise you’ll see a stack trace and exception. Here’s the happy face:
  
• From here, you can follow the link to the admin home page and add categories and forums. You’ll be logged in as the user you created, and that account will be part of the Admin and Moderator roles. Once you’ve added some forums, you can go to /Forums to start posting.
• If you want to test your e-mail setup, go to /Forums/Account/Forgot and enter your e-mail address. Failures are also logged in the error log, which is found in the admin area.

Integration

Aside from the entry in web.config, POP Forums requires only a few lines of code to get it working in your app. These can be found in global.asax.cs:

The comments in this file generally explain what’s going on. The first designates the Ninject module to set up all of the data repositories. Next, you can choose to call one of two static methods on PopForums.Web.PopForumsActiviation, which will apply a global filter to MVC actions in order to set up the IPrincipal object in the request as a PopForums.Models.User. Use the second variety if you want it to apply to all of your app. Then the dependency resolver is set to use a simple implementation of the interface for use with Ninject. Finally, we call the RegisterRoutes() method that comes in the stock MVC global.asax.

So what’s going on under the covers? Take a look at PopForums.Web.PopForumsActiviation, and you’ll see that it uses the PreApplicationStartMethod attribute to call an initialization method when the app starts. This sets up the Ninject kernel (you might know it as a container in other DI frameworks) and fires up an HttpModule to host three recurring services (session management, mailer and search indexing).

The SetUserAttribute() method (and its global variation) install plumbing that in some way mimics the way we’d use an HttpModule back in the day, to set the user on the HttpContext for every request using a forum action method (or all app action methods, in the global variation). Check PopForums.Web.PopForumsUserAttribute for a deeper dive, but basically it checks for a forms authentication cookie, and if found, tries to put the user object on the HttpContext for use around the app, complete with roles. It’s also the point at which session information is maintained, updating user records with a new time stamp and making the user appear “online” on the forum home page.