Documentation

POP Forums v12 attempts to not get in the way of your application, by designating its views inside of an MVC area. As of v10, it no longer relies on MVC’s dependency injection resolver, though you may use POP Forums’ instance of Ninject, if you want. 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?

This release has data changes. Run the PopForums9.2andLaterto12.0.sql script against your database, which is found in the PopForums.Data.SqlSingleWebServer project.

Be sure to follow the MVC 5 project upgrade instructions from Microsoft.

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.
  • Seriously, you have to build the app in Visual Studio.
  • The project files require Visual Studio 2013, or 2012 with update 4.
  • This project is built on .NET 4.5.1, and MVC 5.

Folder Structure

This folder structure is intended to show you where to put stuff if you’re integrating the forum into your own app. The PopForums.Web project will actually run as-is in the download.

  • The PopForums.Web project is the template to use to include the forum in your app.
  • The PopForums.Web project has various folders that you’d expect in an MVC project:
    image
    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 your 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:
    image
    The main purpose of the popForums section is to choose a connection string. While the one included is fine for running on your local box, the commented out one is more typical for SQL Server.
  • While it’s already included, note that the web.config in /Areas/PopForums/Views sets a new base page type for Razor views:

<system.web.webPages.razor>
    <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=5.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. The biggest reason for failure is an incorrect connection string.
  • If you want to use the setup page (and you should), don’t run the SQL script. Once the POP Forums tables exist in the database, the setup page will tell you that you’re prohibited from going there.
  • Point the browser to /Forums/Setup now, and if your connection string is correct, you should see this page:
    setupscreen
    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:
    setupsuccess
  • 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 on the “Forums” admin page, 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.
    adminhome
  • For future reference, you can revisit the admin area at /Forums/Admin

 

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 and Startup.cs, which is a new convention used in apps using OWIN components:

image

image

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.

PopForumsActivation.StartServices() starts up several “backend services.” These aren’t services in the strict sense of the word, since they run in the context of your site, but they work to send queued e-mail, manage user sessions, index thread for the search engine and run calculations on scoring game points. These used to be started automatically, but now this call is required to start them. This is to facilitate a future version which allow these services to run independently of any Web context.

Starting in v10, you no longer have to use Ninject as the default dependency resolver. In the event you’d like to use this container anyway, add this to your Application_Start() (you’ll need using statements to PopForums.Configuration and PopForums.Web):

DependencyResolver.SetResolver(new NinjectDependencyResolver(PopForumsActivation.Kernel));

To use the real-time special sauce, we have to invoke SignalR’s MapSingalR() extension method. This makes the script reference to ~/signalr/hubs actually work.

Finally, we call the RegisterRoutes() method that comes in the stock MVC global.asax. It’s important that AreaRegistration.RegisterAllAreas() be called after the various activation methods, but before the routes are declared.

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.

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.

Last edited Dec 9, 2013 at 3:29 AM by jeffyjones, version 19