bbPress requires theme templates to display the forums content. Currently, bbPress needs total of 16 theme templates for all content types and taxonomies.

bbPress has 3 content types: Forums, Topics and Replies and it has one taxonomy: Topic Tags. On top of that, there are additional elements like user profiles and topic views. For all of that, theme needs to have templates to load all that content. Forums need 3 templates, Topics need 6 templates, Replies need 3 templates, Topic Tags need 2 templates… And, these templates must be made to load the special bbPress related content. But, the problem is that most themes (99% of the themes) don’t have these templates at all. So, how the bbPress works?

There are two ways bbPress can load the content on the front end: theme has all the required templates (highly unlikely, but there are some themes that have these templates included), or the theme compatibility system (bbPress specialized loading system that works with any theme).

Themes with own bbPress templates

For themes to have the required templates, bbPress comes with the example templates that are located in bbPress plugin directory under templates/default/extras. These templates are not used directly, and it is not advised to use them directly. They have the basic structure of the theme templates with bbPress specific code in the middle. So, theme authors can use these example templates, copy them to the theme, and modify the layout to include bbPress specific code, but replace everything else to match the layout of the theme used by other theme templates.

This is not very complicated to do, and some themes do have all these templates. They can style them differently, change layout if needed. These templates rarely change, so they will not require any significant maintenance time when future bbPress versions are released. But, it is hard to motivate a lot of WordPress themes creators to do so, especially when the bbPress already has a way to work without the explicit need for these templates.

Theme Compatibility System

And, now we come to the way that bbPress actually works: Theme Compatibility. This system was developed for both bbPress and BuddyPress. Both have a lot of theme templates they need, and since it is unrealistic that most themes will directly support any of these plugins, the system was created to load required content without the theme templates to match. Compatibility system uses standard theme page.php template as a wrapper for own content.

Templates Loading

bbPress hooks into the WordPress templates loading. There WordPress determines which templates to load based on the URL request. For each request WordPress generates list of potential templates, and it always includes fallback templates in case main templates are missing. For instance, for the post type archive main template is archive-{post-type}.php. But, if the theme is missing that template, loading would fail. So, the list will contain also: archive.php and index.php. So, templates loading attempts to load one of the listed templates that include main and fallback templates. So, that will always result in successful load, because all themes are required to have at least index.php. Problem is that end result doesn’t look good, but, at least something is loaded.

bbPress monitors the templates loading. If the theme has a main template for the bbPress related content, great, it will load that template. But, if that main template is missing (and it is missing for most themes), bbPress steps in and prevents WordPress to load fallback templates.

Templates Fallbacks

Now, bbPress knows what type of content is needed, and it knows that template for it is missing. bbPress then changes the fallback templates to following list: plugin-bbpress.php, bbpress.php, forums.php, forum.php, generic.php, page.php, single.php, singular.php and index.php. First four templates are usually (in themes that have them) copies of the page.php templates with few changes. But, most themes will not have them either. So, the loading fallbacks to page.php, single.php or index.php. These are basic templates that usually display the title and content for post or page, and nothing more. Yes, these templates might load comments and some other stuff, and bbPress will try to prevent that.

Templates Rendering

Now that the fallback templates list is changed, we still don’t have our content rendered, because these fallback templates can’t do that. Before bbPress gives control back to WordPress to load the template, bbPress creates a backup of the WordPress query object. This object contains the prepared content for the template to display. bbPress make a backup of that object and then it changes the main instance of that object. It switched the object to page, disables comments for that page and does few more things.

But, the main thing is now to provide the title and content to match the forum related content that needs to be displayed. For that, bbPress uses a long switch statement that checks which forum content needs to be displayed (forum archive, single topic, user profile…), and generates the title and finally uses shortcodes to generate the content. Title and content are inserted into modified query object, and control is given back to WordPress.

WordPress now using the modified query thinks that it has to display single page, loads the fallback template (page.php or index.php in most cases), and when it comes to the part to show title and content, it will use what bbPress inserted into query object.

To see in detail how the bbPress theme compatibility works, you can check out the BBP_Theme_Compat class in bbpress/includes/core/theme-compat.php file.

Hybrid Solution

It is unrealistic to expect that each theme has bbPress templates. Some, specialized themes do have all the templates. But, more theme have special fallback templates we mentioned before: plugin-bbpress.php, bbpress.php, forums.php, forum.php. Only one of these is needed. So, theme has bbpress.php template, it is based on the page.php, but it is better solution because it gives theme author a chance to make changes to the forums layout compared to other pages. This way that single template can load different sidebar, or have layout without sidebars, it can have own CSS or something else. This is a hybrid solution: bbPress still uses theme compatibility to load all content, but theme has at least one template that is made specifically for bbPress and the forums.


Please, take a few seconds and rate this post
Rating: 5.0/5. From 2 votes. Votes Distribution.
Please wait...

About the author

Milan Petrovic

Programmer since the age of 12 and now WordPress developer with more than 8 years of WordPress experience, author of more than 100 plugins and more than 20 themes.

GD bbPress Toolbox Pro - Enhancing WordPress forums powered by bbPress

The Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

Namecheap - Your dream domain awaits