How I Built the Theme Playground bbPress Theme


bbPress logo

WordPress logo

I’ll be the first to admit that not every website needs a forum, not by a long shot. Not many blog communities are very conducive to a full blown discussion board. Most of the time a comment section works just fine.

But if you decide a forum is appropriate, as I have decided, and you happen to run your website on WordPress, as I do, then you should absolutely consider using bbPress to run your forum. I did that last one also.

For those who don’t know, bbPress is open source forum software built by Automattic, the same people responsible for the continued development of WordPress. The bbPress template system is comparable to the WordPress system, but there are slight differences here and there that I’ll talk about as I walk you through how I built the Theme Playground bbPress theme.

Forum screenshot

The bbPress template structure

With WordPress all theme files are located in /wp-content/themes/. By default bbPress themes are found in /bb-templates/.

The one thing I know I wanted to accomplish by adding a forum to Theme Playground was complete integration into Theme Playground’s current design. So for the forum theme the header, footer, sidebar, styles — they’re all coming along for the ride.

I started with Kakumei, the default theme that comes packaged along with a new download of bbPress. I wouldn’t exactly call it a Sandbox theme by any means, but it’s as good a starting point as anything.

In Kakumei, and in any decent bbPress theme, your theme folder is going to look something like this:

  • screenshot.png
  • /images
  • style.css
  • edit-form.php
  • edit-post.php
  • favorites.php
  • footer.php
  • forum.php
  • front-page.php
  • header.php
  • logged-in.php
  • login-form.php
  • login.php
  • password-reset.php
  • post-form.php
  • post.php
  • profile-base.php
  • profile-edit.php
  • profile.php
  • register-success.php
  • register.php
  • rss2.php
  • search-form.php
  • search.php
  • stats.php
  • style-rtl.css
  • tag-form.php
  • tag-single.php
  • tags.php
  • topic-tags.php
  • topic.php
  • view.php

Most of these files should either look very familiar to you (since they follow the basic WordPress theme format) and the rest shouldn’t seem too foreign, as their names basically describe what they do. The one thing you might notice missing, as you should, is that there is no sidebar.php file listed. This is because bbPress doesn’t support dynamic sidebar widgets (yet). So instead I’ll drop my site’s sidebar HTML output into the bbPress footer.php file.

Template tags

So first I copied the HTML from the header.php of the theme I’m using for Theme Playground (WordPress). Remember, I want everything to fit seamlessly into my current site, like it’s just another section of the site rather than a whole different one. But there are differences between template tags. When going from WordPress to bbPress there are changes that need to be made.

To give you an idea, here’s a quick table, a sort of conversion table, of template tags across bbPress and WordPress.

body table td { padding-right: 10px; width: auto; }
body table th.num, body table td.num { width: auto; }

What it does WordPress template tag bbPress template tag
Site name bloginfo('name'); bb_title();
Site description bloginfo('description'); bb_option('description');
Site URL bloginfo(‘url’); bb_option(‘uri’);
Page title the_title(); view_name();

So you can already see how certain things will translate without a problem. Any titles, home links, and titles will all convert over. But there are certain aspects what won’t be able to smoothly carry over. Pages, for example, are natively supported in bbPress, though there are Plugins available. But what I wanted to link to where pages already existing on my WordPress install. So, in this case, I chose to link to the pages directly in my bbPress theme.

I followed suit with the footer file, copying over the HTML, this time including my WordPress theme’s sidebar.php.

Regarding the stylesheet

Instead of copying over style.css from WordPress to bbPress, I linked directly to my main theme’s stylesheet. By doing this instead of copying over the file I won’t have to manage two CSS files, one will work for both. I can also leave the images folder in place, since all of the same files will be used.

The most prominent HTML element in a bbPress forum is the <table>. For those of us creating websites the right way (which I’m happy to say should be most of the readers here) this may bring about a slight twitch. After all, <table>s hardly ever have their place in our website content.

Of course, they do have a place. Though I’m not sure yet that I want to call a forum listing (see, key word there) tabular data, I can at least see that there is an argument to be made.

All of that to say: you’re going to need decent table styles. In an effort to give you a head start, here are the table styles that work for me:

table {
	margin-bottom: 40px;
	margin-top: 20px;
table tr {
table tr:hover {
	background: #efefef;
} table tr:hover {
	background: #fff;
table td {
	border-bottom: 1px solid #eee;
	font-size: 0.8em;
	line-height: 1.8em;
	padding: 5px 0 5px 5px;
	width: 270px;
	vertical-align: middle;
table td.num {
	border-left: 1px solid #eee;
	padding-left: 0;
	text-align: center;
	width: auto;
table th {
	background: #eee;
	font-weight: bold;
	border-bottom: 2px solid #ccc;
	border-top: 1px solid #ccc;
	line-height: 1.8em;
	padding-left: 5px;
	vertical-align: middle;
	width: auto;
table th.num {
	padding: 0 22px;
	text-align: center;

The default theme also contains some nasty techniques like placing <form> elements inside of <table>s, which is frustrating. I’ve yet to go through and change out all of that HTML, rest assured I will post a corrected theme once it’s ready. Until then, just keep in mind that you may need to add in some styles to undo the table effects on those forms, for the time being at least.

Areas of interest

One thing I really enjoyed about working up the bbPress theme was finding alternative uses for what would end up being empty in the bbPress theme. The two I’m speaking of are the top and bottom areas of the content area of the design. Currently the top area houses only top level categories while the bottom holds any page navigation, if necessary.

Categories aren’t really a part of bbPress in any way. There are tags, but the nature of tags means there would be far too many to list in that small of an area. Since the reason for including top level categories on the blog is because they are relevant and useful, I added some similarly useful links on the forum side:

Top area on the blog

Top area on the forum

Then for the bottom area, in a similar manner I’m displaying the page navigation on the blog, but the recently active members on the forum. Displaying member information is something that you’ll need a Plugin for. Speaking of which, let’s talk about bbPress Plugins.

bbPress/WordPress integration

It’s not enough, really, to only have a forum that lookslike it’s a part of this blog. I really need the two to work together.

The bbPress install directions give you straightforward instructions for WordPress and bbPress sharing user tables, which is the beginning of the integration process. One extra step that you will probably want to take is to make sure that your members’ login states are maintained between the blog and the forum. If your members log in on your blog they should be logged in when they visit the forum, and vice versa.

To manage the cookies between the two, you’ll want to grab the bbPress Integration Plugin (for WordPress) by Michael Adams and Sam Bauers. In most cases this should be all you need to work with to get the login states to match.

Login and user links

There are a few Plugins that exist for WordPress that will allow you to display a login form and related links for your users. After exploring each of these (worth reviewing for a future post, I imagine) I settled on a more manual method.

You can use a built in WordPress function to determine whether or not a user is logged in. You can see my use of this on the upper-most right portion of the site. This is the HTML and PHP I’m using in my WordPress theme:

    <?php if ( !is_user_logged_in() ) { ?> <?php } ?> <?php if ( is_user_logged_in() ) { ?> <?php if ( current_user_can('edit_users') ) { ?> <?php } ?> <?php } ?>

That covers the WordPress end of things. But how do we get the same functionality for bbPress? This is how:

    <?php if ( !bb_is_user_logged_in() ) { ?> <?php } ?> <?php if ( bb_is_user_logged_in() ) { ?> <?php if ( bb_current_user_can('write_posts') ) { ?> <?php } ?> <?php } ?>

There are slight differences, but both are pretty much doing the same thing. By creating your member navigation in this way you have more control over what shows up than if you used a Plugin. You will still need to, however, set up your Register and Login pages to fit in with the site.

I’m actually probably a bad example of pulling this off. Rather than use any particular Plugin, I edited WordPress core files to seamlessly integrate those pages. Same for bbPress. So while I won’t go into them here, for the sake of not encouraging others to go down that same road which could cause problems. If there is interest I’ll set aside a separate post for that and go through the safest way to go about it.

bbPress Plugins

One of the other things to adjust to is how bbPress handles Plugins, which is only a tiny bit different than how WordPress does.

You can find bbPress Plugins at For the most part you’ll find answers to common problems, since there are definitely people using this platform. In my case, I’m also trying to rethink how exactly forums should function, so stripping down the functionality and slowly adding back to it was how I approached the Plugins.

Actually I would suggest anyone wanting to use bbPress do exactly what I did. Take some time and browse through the list of available Plugins and check out those that sound helpful. Don’t worry, there are far fewer bbPress Plugins than there are WordPress Plugins (for now), so it won’t take you that long. I actually discovered quite a few Plugins, some extra functionality, that fit perfectly with Theme Playground which I wouldn’t have even thought of wanting before.

Now, the Plugins that I’m using on the Theme Playground Forum:

  • bbSocialize by F.Thion — Allows you to add social URLs to member’s profiles. Seems pretty flexible, too.
  • Members Online by _ck_ — Will give you a list of members currently online (right this second) and online throughout the day. It’s what I’m using for the bottom-most part of the content area on the forum right now.
  • bbPress Attachments, by _ck_ — Gives members the ability to attach files to their forum posts.
  • Related Topics by _ck_ — Works the way you would expect, the way the WordPress Plugin with the same name works.
  • bbPress Signatures by _ck_ — Members can add signatures to their posts.
  • Comment Quicktags by Stefano Aglietti — Gives everyone a toolbar of quicktags (basic HTML elements) for posting.
  • Hidden Forum by _ck_ — Mark certain forums as hidden, restricted to only certain members.
  • User Directory by Paul Hawke — Gives a list of members on the forum. Very flexible, uses a template file.
  • bbVideo by Naden Badalgogtapeh — I’m still on the fence about whether this one will stick around or not. It turns any link to a video into the actual embedded video.
  • PollDaddy for bbPress by Sam Bauers — Allows the posting of PollDaddy polls using a quicktag.
  • Admin add users by Thomas Klaiber — Allows admin users to add new members on their own. Note that if you have bbPress and WordPress sharing the users table, this may be superfluous.
  • Display name by Michael D Adams — Probably my favorite Plugin I’ve found so far: displays member names as their display names (regular First Last format) rather than their technical username (firstlast).

Final thoughts

I am aware that there is a method of bbPress/WordPress integration that involves loading WordPress functions on every page load of bbPress, and vice versa. I didn’t go down this road for two reasons: it’s not necessary for what I need, and Those Much Smarter Than ITM strongly recommend against it. Do a search for “bbPress” on the WordPress Plugin repository, though. You’ll find a few that will help you display forum content on the blog side of things.

And I’m not going to offer up a version of the Theme Playground Forum theme for you to download, since the customizations are a bit too heavy to be very useful for you. But I will tell you I’m working on a bbPress theme that should make it a bit easier to build themes from. More on that later, be sure to subscribe so you don’t miss out.

The blog:

Blog screenshot

The forum:

Forum screenshot

I’m sure you’re thinking exactly what I’m thinking now: it’s going to take a hell of a lot longer to redesign the site next time.

Technical questions?

This will be the first of probably many times I say this: any comments on this post (a nice “Thanks!” is always appreciated) or references to other related materials are welcome in the comment section below. Any technical questions, though, or in general questions for me that you have about bbPress in general, should be directed to the new forum. That’s what it’s there for — actual back and forth conversation. Thanks!

→ On the forum: All about this bbPress theme

11 thoughts on “How I Built the Theme Playground bbPress Theme

  1. Wow, really great job on the overall forum integration and writing the post as well!

    While I haven’t messed around much with bbPress (yet) this post will definitely help me once I do get around to working with it. Thanks for the list of plugins 🙂

  2. Thanks for sharing your experience with bbPress. I keep meaning to write something this in depth on what I’ve done but can never find the time.

    For your sidebar, you can actually use a sidebar.php file. bbPress has a template function for this. Here’s how you’d do it:

    require_once( bb_get_template( 'sidebar.php' ) );

    And, I would definitely argue that a forum listing is tabular data. I think we’ve all got to this point where we think all tables are bad and want to find ways to not use them even when it’s a perfectly logical time to put them to use.

  3. Pingback: links for 2009-06-04 — Chroniques du web

  4. Thanks for the overview Ryan. I played around with bbPress a few months ago, though admittedly never got very far with it. I’ve been meaning to get back to it so it’s nice to have some direction when I do.

  5. Who are “Those Much Smarter Than I”. The way you mention them makes them seem like real people with a real website. So far, I have not found them. Because of the nature of my site, I want to have the forum and the blog linked up. Is it going to be hell?

  6. I’m trying to build a custom theme for my forum ( that matches the design of my blog ( When I place the theme in /bb-templates/ it sort of works, but I understand I’m not supposed to do this for reasons that seem ill-defined. However, when I place the theme (bookclub-10) in /my-templates/ it refuses to locate the CSS file, though I’ve tried to lead it to its exact location.

    Any suggestions? Thanks for your time!

  7. I reason I don’t use bbpress is the Register and Login pages can’t be themed. Most of us do not have the knowledge to modify the necessary files.

Comments are closed.