Locked[FAQ]Theme and Template Customization

The following is a tutorial on the Forum Theme system we use in this version of the software.

Introduction

First of all, to make any customization, you need to open the software in Visual Studio as a Web Site. See the screens below for details. This forum is a standalone app which reads its bin folder and web.config, and must be installed in a folder marked as Web Application in IIS.

 

Once the process finishes, you will see the tree list in the solution explorer:



To prevent any possible configuration interference problem with your parent site this forum may be installed under, see this article for workaround.

Once you have successfully opened the software, you are ready to customize the software.

In the following tutorial, when I refer to a Forum Theme, I mean a specially named folder reside in both the App_Themes and App_Templates folders:

• ~/App_Themes: This folder holds the CSS / Images / Skins files for a Forum Theme.
• ~/App_Templates: This folder holds the User Controls and MasterPages for a Forum Theme.

A Forum Theme consists of both of the above elements. This Forum Theme system allows you to change the forum user interface completely, outside the ASPX files, using native ASP.NET knowledge.

Currently there are 2 forum themes available, Classic and Original, as you will see 2 folders named Classic and Original in each of the folder above.

There are 2 additional themes you will find which you should ignore for now:

1. The AdminCP forum theme is designed for the admin control panel only, and is not part of the front end forum interface;
2. The Setup forum theme is only used for the setup program. Both Setup and AdminCP won't appear in the theme selection drop down list in the forum user profile interface.

If you want to create your own Forum Theme, you will need to create a folder under both ~/App_Themes and ~/App_Templates with the same name (e.g. MyTheme) first.

The best way to create a custom theme is to copy what we have in the Classic theme. Duplicate the Classic folder in both Forum Theme folders, and then rename the folders to "MyTheme". And then you make the necessary modifications in the MyTheme folders.

Specific Forum Theme information

The App_Themes Folder

The ~/App_Themes/Your_Forum_Theme/ folder is part of the ASP.NET's Themes and Skins system. Make sure you read the link to understand how it works.

You should be customizing the CSS files inside this folder (and sub folder) when you want to tweak the look of an element on a page. Use Firefox's Firebug add-on to locate the CSS definitions to change.

Other than the CSS and image files in this folder, there are a few Skin files:

• Rad.skin - control settings for the Telerik Editor (the WYSIWYG editor) server control
• Prom.skin - control settings for other Telerik server controls (Menu, Popup window, Photo scrollers)
• ASPNET.skin - control settings for standard ASP.NET server controls (label)
• ASPPG.skin - control settings for our own custom server controls (page-able repeater, wrapper header/footer, etc.)

The one that you will be particularly interested in is ASPPG.skin. This skin defines the way wrappers look (the actual HTML code) in our software.

See the pic below to understand the wrapper I refer to (pink color represents the wrapper's coverage):



The wrapper is structured using simple custom controls called ForumHeaderSC (thick wrapper head), and ThemeableLiteral (thin wrapper top and wrapper bottom).

The HTML code for the wrappers are defined directly inside the skin file, so that we don't have to put them on the page directly every time we need them.

You will find 4 skin definitions you will want to look into for these 2 controls inside ASPPG.skin:

1. ForumHeaderSC
   • The thick header that does not have Text inside (the wrapper for upcoming events and birthdays on the default page)
2. ForumHeaderSC skinid="ForumMessageHeader"
   
   • The thick header w/ texts or link (forum, message, or announcement wrapper)
3. ThemeableLiteral skinid="WrapperStart"
   • The thin header (personal PM & Contacts wrapper)
4. ThemeableLiteral skinid="WrapperEnd"
   • The footer for both the thick and thin headers

You can change the HTML inside these wrapper controls to change the look for the wrapper entirely. You can see how different you can change them by comparing the Classic and Original themes:

The App_Templates folder

The ~/App_Templates/Your_Forum_Theme/ folder holds the following Master Pages files:

• Regular.master - the main master page for the forum, holding the main navigation system as well as other core display elements (error message panel, breadcrumb etc).
• popup.master - the master page designed for pages in the popup (basically nothing here)
• UserCP.master - the sub master page for the User Control Panel pages, holding the common navigation tabs for the user CP.

One thing that you will note when you open the ~/App_Templates/Classic/Regular.master file is that it also has a parent MasterPage which points to a file named ~/MasterPage.master  (~/App_Templates/MasterPage.master in v3.9) in the forum root.

Here is an overview of this master page hierarchy:

1. If every forum theme you create will have a common header / footer / logo, you just need to modify the ~/MasterPage.master (~/App_Templates/MasterPage.master in v3.9) file to put your header and footer in (e.g. our Classic theme).
2. If you want each forum theme to have its own header / footer / logo (so that every theme looks entirely different, you will change the Regular.master file in the following manner:

• Add HTML/HEAD/BODY/FORM tags to the Regular.master file for each forum theme you create;
• Remove the MasterPage directive which points to the ~/MasterPage.master (~/App_Templates/MasterPage.master in v3.9) file in the forum root. You don't need it because your Regular.master will now become the top level master page.
• See our Original theme master page (~/App_Templates/Original/Regular.master) to find out how to do this exactly. Our Original theme does not use the ~/MasterPage.master (~/App_Templates/MasterPage.master in v3.9), while the Classic theme does.

The ~/App_Templates/YourForumTheme/ folder also holds User Controls under the UC folder:

• a few ASCX files - these are the User Controls for some UI elements you can modify
• a list of folders - the User Controls under these folders are used as "template" for the PageableRepeater control (spiced up Repeater that supports paging). The PageableRepeater inherits the Repeater control, and we name the User Control files to correspond to their respective template functions.

Let's take a look at the User Controls in the MessageList (the template for the table that lists topics on the individual forum page) folder:

• HeaderTemplate.ascx - the start tag of a HTML table, plus the first TH row that holds the headers for each table column.
• ItemTemplate.ascx - a HTML table row. This row will be repeated again and again for each message topic that shows on the page.
• FooterTemplate.ascx - the end tag of a HTML table, plus some Javascript which you won't want to change.
• NoDataTemplate.ascx - a HTML table row that shows when there is no message topic to show on the page.

The key here for this particular template are the HeaderTemplate.ascx and the ItemTemplate.ascx files. You will modify the HeaderTemplate.ascx file if you want to change the columns (like remove a column), and modify the ItemTemplate.ascx file when you want to change the actual message list item.

These files are simple, and the logic behind the templates are all in their corresponding .vb files.

Of course, if you plan to add / remove a column, you will need to modify both template files, plus the NoDataTemplate.ascx file to set the correct colspan.

Selecting default theme

You can select the default theme in the web.config file. Look for the key under appSettings

<add key="DefaultTheme" value="Classic" /> 

Change the value to your own theme name to change the default theme.

Conclusion

A forum theme consists of User Control / Master Page and Skin/CSS/Image files, and you will need to create both sets (App_Templates and App_Themes) if you wish to create your own Forum Theme.

You should familiarize yourself with the info above in order to make the theme creating process as simple as possible.