[John James Jacoby]

A few questions have cropped up already, so lets funnel the discussion here.

bbPress 2.0 introduces a radical new approach at integrating robust new functionality into existing WordPress themes. If you’re an average user looking for a turn-key forum solution, this works out pretty awesomely – If you’re a talented developer trying to beat your own drum, it’s all probably a little bit confusing.

Theme Compatibility

bbPress comes with a child theme of TwentyTen, titled (you guessed it) bbPress – TwentyTen. This theme includes all of the custom bits that bbPress needs to function, broken up into template parts to allow them to be used in several places, like template files, shortcodes, and widgets.

1. MOST COMMON – If you’re using any other conventional WordPress theme (TwentyEleven, BP-Default) and find the default template layout of bbPress acceptable, you don’t need to do anything at all – it should just work.
2. DO NOT put any custom themes in “/bbpress/bbp-themes/” as they will get wiped out when you update bbPress.
3. CUSTOM – If you want to build your own theme or make changes to the existing template files, you’ll need to do the following:

   Copy Files

   • If this is not a custom theme under your control (meaning you are not the author) you’ll want to copy the contents of the “/bbpress/bbp-themes/bbp-twentyten” folder into your “wp-content/themes/%YOURTHEMENAME%” folder, where %YOURTHEMENAME% is the name of your custom Child Theme of whatever your current theme is. This is so theme updates don’t wipe out all your hard work later.
   • If you are the author of this theme, then you can copy all the files *out of* the “/bbpress/bbp-themes/bbp-twentyten” folder into the folder of your theme, and make your own edits from there. The files to copy include the single-*, archive-*, page-*, and anything in the subfolders.
   • In neither case should a new folder with the name “bbp-twentyten” exist. You are not copying the FOLDER, you are copying what’s IN the folder.

   Add Theme Support

   Now that you’ve got the files copied over, you’ll need to tell bbPress that you are in control of the theme situation. You do this by adding this to your functions.php file:

   add_theme_support( 'bbpress' );

   By doing this, you’re telling bbPress that your theme has its own template files to handle all of the new functionality that bbPress adds. This method gives you a single on/off switch to either use the standard theme compatibility, or use your own.

In the future, specialized template compatibility themes can be created either as plugins or child-themes to work like “add on packages” to existing themes, without requiring elaborate edits to existing themes, moving files around, etc…

Shortcodes (as of May 23, 2011)

Whether you rely on theme compatibility, or decide to go the custom route, we’ve included a few standard shortcodes to let you output specific forum content on any post or page in your forums. This is accomplished within an output buffer, so they won’t interfere with any of your existing page or post content. Note that if your theme specifically removes the shortcode functionality, these will not work, and will instead the actual text of the shortcode will appear on your site.

• [bbp-forum-index] – Show the root forums
• [bbp-single-forum id="A forum ID"] – Show a specific forum
• [bbp-topic-index] – Show all topics
• [bbp-single-topic id="A topic ID"] – Show a specific topic
• [bbp-topic-tags] – Show all topic tags
• [bbp-topic-tag] – Show topics of a specific tag
• [bbp-topic-form] – Show the new topic form
• [bbp-reply-form] – Show the new reply form (not commonly used)
• [bbp-single-view id="A view slug"] – Show the topics of a registered view

In the future, we’ll be adding more shortcodes as the needs arise.

That’s it for the first round of explanations. I’ll edit this post as more questions and answers come through.

[MTPrower]

I agree with Crisium. There is no clear-cut documentation on how to integrate bbPress into WordPress. I myself am at a loss trying to figure out how to force bbPress to use a template that is not my default php template, and at how to create a bbPress child theme. I’ve been reading, reading, reading(!) for the past several days and it all just seems like a big confusing mess to me. If there IS any “user-friendly” and very-thorough documentation for anything in bbPress at ALL, could somebody please link me to it?

[MTPrower]

I read the entire three pages of this topic in one sitting now. I’ve been fooling around with files and folders all day. I give up trying to create a bbPress theme or child theme. I’m just going to edit Twenty-Eleven’s bbpress.css, and if I run into issues updating, then so be it. All I want to do is override Twenty-Eleven’s CSS. It can’t be this difficult…

[ddlg2007]

No one answer our question, i know you are bussy guys but please really this dont work correctly for custom themes or child theme.

I do like Crisium, and nothing, some one can please say how do it correctly?

[ddlg2007]

Can anyone tell me how to use a custom style.css for bbpress bbp-twentyten without import my style.css of theme worpress??? Please that can be a good solution for make a better custom…

[MTPrower]

Does nobody know how to use a custom CSS file with bbPress 2.0 that overwrites the default TwentyEleven bbPress theme and doesn’t get removed with updates? Nobody?

[Hard Seat Sleeper]

Here are the steps I just took to install bbpress on a wp install and get a child theme started so I can develop with it. It assumes you have a mirror of your site files on your computer HD. Hopefully it will help someone.

1) Install plugin on live site.

2) Download

/wp-content/plugins/bbpress/bbp-themes/bbp-twentyten

to your computer, and copy folder and contents to

/wp-content/themes/

rename the folder if you want, so you have

/wp-content/themes/newchildtheme/

3) turn this into a child theme:

https://codex.wordpress.org/Child_Themes

(basically, add a “Template: ” parameter)

4) Upload this new child theme to your server

5) In the parent theme, add

add_theme_support( ‘bbpress’ );

to functions.php

5) Upload functions.php to server

6) Go to

/wp-admin/themes.php?activated=true

on your site and activate your child theme

[MTPrower]

I already have a child theme activated for WordPress, and I intend to keep it. Does this mean I can’t have a separate WordPress theme and bbPress theme at the same time? I need to use my current WordPress child theme. I can’t just get rid of it because I want to style bbPress!

[Hard Seat Sleeper]

MTPrower,

I’m no expert, believe me.

But, if you have a child theme already, did you try merging your child theme with a bbpress child theme?

I would try dropping all the relevant bbpress php templates into your child theme, putting the necessary info into functions.php, and seeing what you get.

[MTPrower]

I did try it once and then put the add_theme_support into my WordPress child functions.php. It didn’t get me anywhere. If anyone knows of anybody who’s successfully merged a WordPress child theme and a bbPress child theme, please tell.

[MTPrower]

I call spam on the above comment.

[Hard Seat Sleeper]

Try putting add_theme_support into the parent theme’s functions.php

[MTPrower]

Thanks. Will try, then report my findings.

[MTPrower]

I got it working! However, I did not do anything with the bbPress functions.php. Was I supposed to combine it with my WordPress functions.php or something? Do I continue to just ignore it?

[Secrets of Safety]

I personally find it ridiculous that someone would suggest that the developer shouldn’t have to do the documentation. Or at least that is what it sounded like when I read these comments.

If the dev doesn’t completely supply documentation, how is anyone else going to know what the heck to do with this plugin?

If this is such a great plugin, then make it easier to integrate into the themes.

It is difficult enough getting our websites up and functioning without having to pull our hair out trying to figure out how to use a plugin that is supposed to be so great.

I have noticed that there are a lot of dev’s who don’t contribute much documentation for wordpress. How unfortunate they assume everyone can read their minds.

This topic has been up for months and still having no clear directions. Hope everyone else figures it out. I’m not going to bother with this.. If the dev doesn’t care, I sure don’t.

[MTPrower]

Couldn’t agree with you more, secretsofsafety. Having a website for me is 5% enjoying the website and 95% building and maintenance.

[lokize]

Hi nice work, great plugin, but i using the theme LeetPress 1.0, and I can not make it run this thema, any solution? hugs!

[raphaelsuzuki]

Well, I have a quick, but questionable and probably not recommended, solution, if you just want to style with CSS.

1) Copy the content from bbp-twentyten/css/bbpress.css to your child theme styles.css – this should give you all the ids and classes to work with;

2) Rename the original bbpress.css file to something else, in order to turn it unusable – this should be done because the original bbpress.css file always override your theme’s CSS;

3) Style at your taste.

This should avoid your work from being deleted on every update.

When an update occurs, just do step 2 again.

A quick and easy solution like this is unlikely to be the right one in this case, but works for simple styling.

[WhiteRau]

i got mine working almost without effort. i literally read the sticky at the top of this thread and it worked.

a couple of things to note, that people are stumbling over:

1) READ THE STICKY. don’t peruse it. READ IT.

2) the sticky actually says the same thing twice. COPY the CONTENTS of wp-contentpluginsbbpressbbp-themesbbp-twentyten to YOUR theme’s folder, whether it be a child theme or not. in my case the path was wp-contentthemesSuperTurboTheme.

3) it’ll ask it you want to overwrite ‘style.css’. don’t. just let the OS rename it to ‘style(2).css’.

4) ditto for the ‘functions.php’ file. it should, temporarily, be ‘functions(2).php.

5) MERGE the two functions.php files. i just copy/pasted everything from ‘functions(2).php’ to the bottom of the ‘functions.php’ file. just like in the sticky. i didn’t merge the ‘style.css’ and ‘style(2).css’ files. but i DID make sure the ‘Tags:’ line in my ‘style.css’ file included ‘bbPress’ as the first item, just to be sure. it was an old requirement that doesn’t seem to have been deprecated anywhere and i’m a belt-n-suspenders boy…

6) at the very top of your newly expanded ‘functions.php’ file, add the line ‘add_theme_support( ‘bbpress’ );’ to the very top. just like in the sticky. EVEN THOUGH THERE IS A SIMILAR LINE IN the bbPress’ functions.php file, YOUR functions.php file MUST HAVE THIS LINE as well. EVEN THOUGH THEY ARE MERGED.

7) reload.

don’t get clever. don’t reinvent. don’t assume anything. just follow the steps and you should be fine.

your only challenge now is figuring out how to do your CSS. the ‘style.css’ will control the WordPress portion of the site. it CAN handle the bbPress styling as well, but i prefer to leave it to bbPress.css (located in the ‘css’ folder you copied over) to handle the forum styles. its a bit of a headache sorting out the bevy of tags that get generates, but hey, it works. and i DO mean headache.

not to beat a dead horse, but the real challenge IS sorting out the secondary CSS. i recommend Firebug to help you drill down the the styles. the byzantine class structure can make your head spin. try using the elements that are relatively easy to spot. and REMEMBER THIS: NOT ALL CLASSES ARE IN THE STYLESHEET. this can really toss a wrench into things. they are added for future slice-n-dice, but seems overkill to me. low-order CSS has proved easier for me. i can’t foresee a reason to slice the site up so finely…but it’s futureproofed to the wheel-wells!

good luck. hope this was useful. i apologize if i missed anything. i tried to be thorough AND simple.

feel free to correct me if i stepped wrong somewhere. this is what worked to me.

WR!

[WhiteRau]

okay. this is an addendum to my previous post, something was nagging at me and it has to do with the way bbPress’ functions enqueue the stylesheets.

you are going to have problems. i forgot a CRITICAL MODIFICATION. and it may ONLY apply to CHILD THEMES. i haven’t finished testing it on standalone themes, but put it in your watch folder…

if you look at the bbPress’ functions, near the middle, there is a section that enqueues stylesheets. i’m not sure why this is there because, in essence, it COMPLETELY OVERRIDES any style changes you make to your child theme’s CSS. what it does is load ANOTHER copy of the parent-style’s stylesheet with a version number tacked on. this forces a precedence over your own style.css, essentially making the newly loaded CSS sheet last-defined. and we know what that means.

so. the fix:

1) find this line in your functions.php file (the one you have the merged bbPress functions.php code in):

wp_enqueue_style( ‘twentyten’, get_template_directory_uri() . ‘/style.css’, ”, $this->version, ‘screen’ );

it’s on line 149 of the original functions(2).php file from my post above, so to make it easy to find, you can do some quick math to find the relevant line number in your (merged) functions.php file. (hope that made sense…)

2) comment it out by simply adding ‘//’ in front of it.

3) reload. your style.css sheet will now be dominant and the css/bbPress.css file will act in a better support role, as it should.

i understand the long-view logic of why this function does what it does, but at a non-galaxy-class-developer level, it makes for massive headaches… and you still have the fun headaches with the bbPress tags…

hope this was also useful. it will save you going bald.

WR!

[Crisium]

@WhiteRau

you are way off with your comment about “just follow what the sticky comment says”

you meaning yourself are merging… nowhere does it state that we should merge.. that is a big difference

and you are having duplicate files and functions… wtf?

I have given up on this plugin!… I can write a new one faster than getting this one to work.

Peter

[WhiteRau]

as you like. my blogs and forums are all working. no need to be offended! i just found that after reading this thread *most* people’s questions came from not reading the sticky all the way through. and you are correct: the sticky doesn’t mention merging files. i read that elsewhere (i’ll try and recall where). does it matter? regardless: what i outlined works.

as for duplicates, they override eachother. there’s duplication, overriding and modifying all over the place in WordPress and bbPress. this is nothing new. all that matters is precedence at the end of the day.

nitpicking is pointless and unhelpful. take it or leave it. don’t really care. all i’m interested in is helping people sort this out. my way works. end of story. if you can indeed write a new plugin, then by all means give ‘er! yours might be the halcyon we’ve all been hoping for! that’s the beauty of all this stuff!

WR!

[devotee]

I´m also having problem with this. I´m getting the forum to work, but I have problems getting access to css and template files.

I have created a child theme from the bp-default theme, which doesnt seem to support bbPress-templates, but still displays everything nicely somehow. Within this child-theme I change css and templates belonging to the bp-default theme and that works fine.

Now I would like to be able to modify the bbPress part of the site from this child theme aswell, but I cant because the theme has no template files for the bbPress installation (even though it presents the forum very nicely). I can change the css-part by just copying the css from the bbpress.css into my styles.css (it get´s priority). But there is no template-files to copy except those from the bbp-twentyten theme, and if I do, the appearance just breaks

What I want: The forum to look exactly like it does from the default bp-default theme, but with access to template files so I can remove and add stuff on my own.

Can anyone help me with this one?

[farinspace]

Also useful to know are the actions/filters (hooks) in bbPress … I wrote a little something to get a list of the current actions/filters in bbPress 2.0.1, should help out someone …

https://gist.github.com/1372637

[maxfaction]

I was able to get it working after 4 hours of manipulating css code… which isn’t uncommon when bending code to suit your theme design. I’m still working on a few bugs, nothing serious but its tedious nonetheless… so I’ll contribute my discoveries when I’m done. It’s not for the faint-hearted to be sure, but its do-able. At least you won’t have to invest as much time as I did to “get it”. More to come…

Resident newbie

[tamaral]

I’ve just installed the 2.0.2 version and I get a 404 error when I click on one of the forums link. Do I need to follow the steps on this post in order to get it running right on my site?

Thanks.