Original Article: http://www.wpmods.com/integrate-wordpress-bbpress
It’s easy to forget about bbPress, Automattics neglected son. bbPress development seems to be way down on their list. You only need to look at the design and content of the bbPress home page compared to other Automattic projects such as WordPress.com, WordPress.org,Akismet or Gravatar; to see that bbPress isn’t a priority for them.
Which I think is a bit of a shame. Sure, as far as forum software goes, bbPress is very very basic. It lacks a lot of features which are standard on most other forums plus bugs are not resolved as quickly as their flagship WordPress script. Though it does have a lot of positives
Firstly, it’s very easy to install and won’t put too much strain on your host. It’s also very easy to customise compared to other forum scripts and is currently being used for the WordPress Support Forums, BuddyPress and WP Mods.
Last but not least, it’s incredibly easy to integrate with WordPress, which you would expect since it’s developed by the same people. Today I will be showing you how easy it is to integrate a bbPress forum with your WordPress powered website.
Note, in this tutorial I will assume that you are using the latest version of WordPress (2.9.2) and bbPress (1.0.2) as integration is a little different for older versions of the script. I have tested this integration process using bbPress 1.02, WordPress 2.92 and WordPress 3.0 Beta 1.
Integrating bbPress with WordPress – Long Version
Just like WordPress, installing bbPress is very straight forward. All you need to do is download the latest version, extract the files, upload them to your host and run the installer. The installer has 3 steps.
Step 1
The first step is database configuration. This step checks that the database information you entered in your bb-config.php file is correct.
There are lots of articles on the web stating that bbPress and WordPress have to be installed into the same database in order for the two scripts to integrate correctly. This is not true (though perhaps it was in the past). Installing the scripts in the same database will make the installation quicker though as you do not need to enter your database login details again, though from a performance point of view it’s perhaps better to keep them in separate databases. It’s your call.
If you install bbPress in the same database as your blog then the database login information is exactly the same as your blogs, so you can simply copy the database info from your blogs wp-config.php file. If not, you need to change the database name to your bbPress database.
In preparation for this tutorial I installed, deleted and reinstalled bbPress several times to see if I could get it working. With every installation I placed I the bbPress script in a sub folder of my WordPress test blog. You could maybe place the forum in a parent directory if you really wanted though I haven’t tested this myself as yet. I assume it’s possible to use sub domains such as forums.website.com as well though you may run into some cookie login problems.
Before proceeding, make sure you make your bb-config.php writeable so that bbPress can update the config file at the end of the installation process.
Step 2 – Part 1: Cookies
Step 2 is WordPress integration. In this step you need to enter some information about the WordPress blog you are trying to integrate bbPress with.
In this cookies section you need to enter the location of your WordPress website (and the blog URL too if it is different). You then need to make sure you enter the WordPress “auth” cookie key, the WordPress “secure auth” cookie key and the WordPress “logged in” cookie key.
You can also enter the corresponding cookie salts. These were introduced in WordPress 3.0 so if you are using WordPress 2.6 to WordPress 2.9 you will probably only have the authentication keys in your blogs wp-config.php file. However, if you are using WordPress 3.0 beta and above you will have cookie salts too so you should copy these from your wp-config.php file and enter them in step 2.
The installer will stop you if the cookie keys have not been entered but will still let you proceed if the cookie salts are not. And if you don’t enter the cookie salt information it will flag as an installation error at the end of the installation, but don’t be too concerned about this. The salts can be updated in the bbPress WordPress integration page so if you forget to input them during the installation process you can do so later on.
You should already have entered this information into your blogs wp-config.php file so it’s just a matter of making sure the keys and salts are exactly the same, but if you haven’t, here is how you generate them.
- WP 2.6-2.9: Visit https://api.wordpress.org/secret-key/1.1/ for a randomly generated list of unique keys. Copy them to your blogs wp-config.php file and enter the info during step 2 of the bbPress installation.
- WP 3.0+: Visit https://api.wordpress.org/secret-key/1.1/salt/ for a randomly generated list of unique keys. Copy them to your blogs wp-config.php file and enter the info during step 2 of the bbPress installation.
This whole process ensures that users aren’t logged out of your blog when they log into your forum (and vice versa).
Note, if this information is incorrect in anyway you can check the details match later on. The easiest way to make sure that they are correct is simply copying and pasting the keys from your blogs wp-config.php file to forums bb-config.php file. However, you must make sure that the keys in the bb-config.php file have the prefix BB_ i.e. BB_AUTH_KEY = AUTH_KEY, BB_SECURE_AUTH_KEY=SECURE_AUTH_KEY etc.
Step 2 – Part 2 : User database
You need to enter the WordPress user database table prefix in this section so that bbPress can find the WordPress data tables. The default prefix is ‘wp_’. Though it’s worth checking your wp-config.php file incase it’s been changed. There is also an option for WordPress multi users to enter their WordPress MU primary blog ID.
Step 2 – Part 3: Separate user database settings
If you are using a separate database for bbPress and WordPress then you will need to enter your WordPress database information here. If you can’t remember your database details, simply refer to the wp-config.php file.
Step 3
In the 3rd and final step of installing bbPress you need to enter the name and location of your bbPress forum. You can also set any admin from your WordPress blog as your ‘Key Master’.
You now just need to complete the installation process. Make sure your bb-config.php file is writeable before clicking on the complete button. If you don’t, you may need to manually edit your bb-config.php file.
Setting Cookies
Your bbPress will now be live, however you still need to set the cookies correctly. This ensures that logging into your blog doesn’t log you out of your bbPress forum (and vice versa).
If you have your blog in the root of your domain with the forum in a sub folder then you simply need to add the code below to the top of your wp-config.php and bb-config.php files:
define( 'COOKIEPATH', '/' );
If you have it installed somewhere else then I recommend installing the bbPress Integration plugin into your WordPress blog.
All the bbPress Integration plugin does is tell you the path for your cookies. Once you have the code, you can uninstall the plugin.
Again, remember to make sure you set the cookie path near the top of the config files i.e. before the database information.
WordPress Integration Settings
After setting your cookies path, you should now visit your WordPress Integration Settings page. This can be found in the settings section of your bbPress admin area (i.e. bbpresslocation/bb-admin/options-wordpress.php).
In this page you can edit your wordpress prefix, location and authentication keys and salts. However, the main reason to visit this page after installation is to set your user roles. You should have already set blog administrators as forum key masters though you may wish to asign blog editors as moderators and everyone else as members.
bbPress WordPress Plugins
If you have successfully integrated the scripts together you may want to add some bbPress related plugins to your WordPress plug such as Bbpress Latest Discussion For WordPress orbbPress Live (just search for bbPress through the WordPress plugin installation section to see a list of bbPress related plugins).
Integrating bbPress with WordPress – Quick Recap
A quick recap of the above guide for those who don’t need a big explanation 
- Download bbPress, upload it to a subfolder of your WordPress installation (preferably), make the bb-config.php file writeable and then start the installer.
- Enter the authentication cookie keys and salts in step 2. Make sure they match those in your blogs wp-config.php file.
- Enter your blogs prefix. The default value is ‘wp_’ though it’s worth checking your wp-config.php file incase it has been changed.
- Enter your WordPress database details if you are not installing bbPress in the same database.
- Enter your bbPress forum name, the forum URL (which is already stated), assign a Key Master and enter the Key Masters equivalent forum name.
- Define your cookie path. If you don’t know it, install the bbPress Integration plugin to find out the exact location. Add this code near the top of your wp-config.php and bb-config.php files (i.e. before the database information) and re-upload the files. You can uninstall the bbPress Integration plugin at this point as it is no longer needed.
- Go to your WordPress Integration Settings page (i.e. bbpresslocation/bb-admin/options-wordpress.php) and assign the user roles from your blog to their corresponding roles in bbPress.
Troubleshooting & Common Integration Problems
I hope that you all install and integrate bbPress and WordPress in your first try. Though, there is a good chance that you may have done slightly wrong at one stage so I thought I would look at some of the most common problems for you.
The main problem that most people face with integration is with cookies. When the cookies aren’t set correctly you will be signed out of your forum when you sign into your blog and vice versa. This is a problem I experienced myself at the start and it can be incredibly frustrating.
Firstly, if you are having this problem then I assume that your bbPress forum has installed correctly and is integrated with WordPress. That is, your users from your blog can login to the forum using the same information and your forum users can login to your blog.
However, if you are being logged out every time you login to the other script then you need to check that you have defined the cookie path correctly and matched your authentication cookie keys and salts. In my experience it’s more likely to be a problem with the cookie keys and salts.
Therefore the first thing you should do is generate a new list of keys and salts athttps://api.wordpress.org/secret-key/1.1/salt/. Copy them to your wp-config.php file and upload it. Then copy the same keys to your bb-config.php file and upload the file, making sure you add the prefix BB_ before each key or salt i.e. BB_AUTH_KEY = AUTH_KEY, BB_SECURE_AUTH_KEY=SECURE_AUTH_KEY etc.
If that doesn’t resolve your issue then you should double check all your other settings are correct. It’s perhaps worth deleting the bbPress database tables and reinstalling bbPress just to make sure you did everything correctly if you are struggling to resolve the issue. Jacksi posted in the bbPress forums that integration didn’t work when the cookie keys and salts had 64 characters but did when they were shortened to 32. I didn’t have a problem with this personally though it’s worth trying if you are having problems and nothing else is working.
If you are really struggling with it though please leave a comment here or post a thread in theWP Mod Forums.
The other two main problems that users report are:
You can only integrate bbPress if you use non-www
Many believe that you can only integrate bbPress and WordPress together if you set bbpress at domain.com/bbpress rather than www.domain.com/bbpress. I believe this actually used to be true in older versions because WordPress cookies would let you use www or non-www whilst bbPress cookies would only use non-www (I don’t know for certain, though there are many threads about it in the bbPress forums).
During my tests I installed bbPress and WordPress using www and non-www. The first time I used non-www as the URL it resolved an issue I was having with cookies so I did more tests to see if it was true. It isn’t.
It seems that bbPress is a little more forgiving with cookies when you use non-www though if you set the authentication keys and salts correctly you will not have a problem with either.
It’s better to use the same database
As I mentioned before, another thing which many people are encouraging you to do is use the same database for WordPress and for bbPress. I have installed bbPress in a different database and in the same one as WordPress.There really wasn’t any problems in either location for me so it’s really up to you.
If you are having problems installing bbPress in a different database, I would double check the database information you have given in the integration page.
Changing your forum from BuddyPress to bbPress
BuddyPress is a fantastic script from the Auttomatic team. It integrates with WordPress much easier than bbPress because it is installed as a plugin rather than a stand alone script.
This means that users don’t have to try and integrate two different scripts or integrate their designs, which is why many people install BuddyPress as a forum solution.
However, BuddyPress doesn’t have a forum. It allows you to set up a groups function which can be used as a forum. Through the use of templates BuddyPress can redirect users from a URL such as www.site.com/forums/ to the groups function. Unfortunately, groups work very differently from a forum and many users quickly realise that it doesn’t do what they need it to do, so they then start looking at bbPress. In my opinion this is the best solution (BuddyPress themselves use bbPress for their support forum).
I installed BuddyPress a while ago to try it out and tried out the groups function as a forum. I then uninstalled it and came across a few of the redirect problems which users come across. Specifically, if you had your BuddyPress group/forums at www.site.com/forums, uninstalled BuddyPress and then installed bbPress at the same address; you would get a forum not found error.
This is probably occurring because of the BP Template Pack. If you don’t use a BuddyPress template and instead choose to use your blogs own theme, then you probably installed the template pack plugin. This plugin adds lots of template files to your theme and integrates BuddyPress functions into the WordPress design.
So to uninstall BuddyPress completely you need to deactivate all BuddyPress plugins (and delete them if you wish). You can also delete the BuddyPress tables from your database if you wish (worth doing if you don’t plan on using it again). The last thing you need to do is delete all of the BP Template Pack template files from WordPress. The 6 folders (activity, blogs, forums, groups, members and registration) should all be in your theme folder e.g. www.site.com/wp-content/mytheme/.
These templates added redirections so with them now removed you should now see your bbPress forum at www.site.com/forums. Once BuddyPress has been completely removed, you just need to integrate bbPress with WordPress using the steps mentioned in this article.
Deep Integration
Deep integration involves loading up WordPress and bbPress when your forums are loaded. Some people believe that this is the best way to integrate WordPress and bbPress but I think it’s overkill, you simply don’t need to load everything unless you want to call up functions like latest posts, archives, categories etc. And in my opinion, it’s better to simply link to your blog in your forum area and list the latest forum posts and forum categories than blog pages.
Though I do appreciate that everyone uses WordPress in different ways. So if you want to integrate WordPress and bbPress beyond just sharing the user tables in your database, you should look more into deep integration.
To call WordPress functions within your bbPress forum you need to add the following to your bb-config.php file:
require_once(dirname(__FILE__) . '/path/to/wp-load.php');
This will increase the load on your server, so it’s prudent to check if there are any plugins for bbPress which do what you want first.
Designing your bbPress Forum
Although bbPress integrates well with WordPress, it is completely separate from it. Therefore it doesn’t work the same way as a plugin and won’t share your blogs design. This is a major stumbling block for a lot of bloggers, though it doesn’t need to be, particularly if you know HTML and a little PHP.
The first thing I recommend doing is downloading 4 or 5 bbPress themes from the web and uploading them to your /bb-templates/ folder. Try a few of them out to see which one you like. You may want to go with a theme which has a similar colour scheme to your blog, though I personally prefer to go with something very basic and then change the colours later to blend the bbPress design in with my blogs design.
A good way to understand the templates better is to compare the code which is being used in different themes. Move things around and play around with the themes for a while to get a better understanding of how the templates work. You can find a good reference on what template does what at http://bbpress.org/documentation/themes/.
Blending the forum into the rest of your sites design isn’t too difficult. It’s hard to give a step by step tutorial on how to do this, as it depends on the theme you are using for your blog.
However, below you can see the steps I take to make the forum design the same as the blog.
- Open up the bbPress theme header.php template and import the stylesheet that your blog is using into the head section. For example:
<link rel="stylesheet" href="http://www.yoursite.com/wp-content/themes/mytheme/style.css" type="text/css" />. This allows your forum to use all of the CSS classes that your blog does. You should now be calling two stylesheets in your forum header.php template: your blogs stylesheet and your forum stylesheet. If you prefer, you can copy the forum classes to your blogs stylesheet, but I think it’s better to keep the stylesheets separate to keep things simpler. - View the source of one of your blog pages. You need to copy a lot of the code from here to the header and footer templates of your forum theme. What code you copy over will depend on how your blog design is structured. Though for most blog themes this requires you to copy the code below the body tag to the start of the main content area. Copy this code to the header.php template.
- If you want to include your sidebar in your design, copy the code from the bottom of the content area (including the sidebar code) to the bottom of the page to the footer.php file. If you don’t want to include the sidebar in your forum design, make sure you remove all of the sidebar code. You will also need to create another CSS class for your forums main content area since it will be longer (since there is no sidebar). Basically, what you are trying to do in steps 2 and 3 is copy your blogs header and footer design into your forum templates.
- You should now open up your bbPress stylesheet and tidy up the code. Many of the classes can be removed. For example, common classes for anchors, header tags etc will be duplicated in both stylesheets. If you remove them from your bbPress stylesheet your forum fonts and colours will match your blog more. Though you will also need to watch out for duplicate classes which are clashing (e.g. menu is used a lot for controlling how navigation menus are styled, so it’s possible that the class exists in both stylesheets).
- Your forum should now blend in well with the rest of your website, though there may be a few bugs here or there that need addressed. Usually this is resolved by removing classes that are clashing or over-riding styling from your blogs imported stylesheet.
- At this stage your forum should blend in with your blog design so well that most people won’t even realise that they are powered from a different script. Now you can play around with your forum templates, move things around and get the forum looking the way you want it (I sometimes use other theme templates for reference).
If you have some experience with modifying WordPress themes then you should be comfortable with integrating your bbPress forum design with your blog. In one of my last blogs I integrated a vBulletin forum with the blog and I have to say, integrating the design was much easier with bbPress. So you shouldn’t have any major difficulties. If you do run into some problems though, feel free to post the details in the forum and I’ll do my best to help you out.
Overview
I hope this tutorial will help you integrate these two great scripts together. Whilst bbPress isn’t the most advanced forum script out there, it works great with WordPress. And for me that is a big part of why I like using it.
Unfortunately, these type of integrations don’t always go to plan, so if you are really struggling with this please leave a comment here or post a thread in the WP Mod Forums and I will do my best to help
Good luck,
Kevin
Below is a list of discussions, articles and videos about integrating bbPress and WordPress which you may find useful.