bbPress Codex

Themes and Templating

These pages are for bbPress versions less than 2.0. They are considered out of date and are here for legacy only.

Installing

Installing themes is easy.

1. Make sure you have a directory called my-templates/ in bbPress’ root directory.
2. Upload the theme to your server as a new subdirectory in your my-templates/ directory.
3. That’s it!

Activating a theme is even easier. Just select it from you bbPress install’s Presentation Admin Panel.

Designing

A theme consists of three things.

1. A stylesheet called style.css.
2. A 240×180 pixel screen shot of your theme called screenshot.png.
3. Some template files.

Stylesheet

A theme really only needs one file: a stylesheet named style.css. At the top of that stylsheet you should put the following information so that bbPress will recognize it as a theme.

/*
Theme Name: The name of your cool new theme.
Theme URI: Your theme's url. Maybe it's the blog post you wrote about it.
Description: Describe your theme here. You can be nice and say something like "Blues and Greens in a two-column format" or enigmatic and say "The river here is only waist deep".
Version: Always number your releases. Please only use numbers and decimal points (yes, we broke our own rule).
Author: Author of the original theme,
Author URI: and his or her url.
Ported By: Name of the person who ported the theme to bbPress (if applicable),
Porter URI: and his or her url.
*/


Screen Shot

You should include a 240×180 pixel screen shot called screenshot.png with your theme so it shows up all purty in the admin panel.

Template Files

In addition to the stylesheet, bbPress will look for the following template files in your theme. If it doesn’t find the file it needs, it will use the one from bbPress’ default theme, Kakumei.

front-page.php

Used for your forums’ front page.

forum.php

When viewing a forum.

edit-post.php

When editing a post.

edit-form.php

Called by edit_form().

favorites.php

When viewing a user’s favorites.

header.php

Called by bb_get_header().

footer.php

Called by bb_get_footer().

login.php

When a user is viewing the login page ( /bb-login.php).

login-form.php

Called by login_form() when user is not logged in.

logged-in.php

Called by login_form() when user is logged in.

password-reset.php

When a user is visiting the reset password page.

post-form.php

Called by post_form().

post.php

Called by bb_post_template()

profile.php

When viewing a user’s profile.

profile-edit.php

When editing a user’s profile.

profile-base.php

When viewing a page added by plugin to a user’s profile.

register.php

When a user is registering.

register-success.php

When a user successfully registers.

search.php

When viewing the results of a search.

search-form.php

Called by search_form().

stats.php

When viewing forum statistics.

topic.php

When viewing a topic.

topic-tags.php

Called by topic_tags().

tag-form.php

Called by tags_form().

topic-tags.php

Called by topic_tags().

tags.php

When viewing the tags page.

tag-single.php

When viewing a single tag.

view.php

When a logged in user is at a “view” page (such as ‘Topics with no replies’).

Whew. That’s a lot. But remember, your theme doesn’t have to include any of them; for the templates you don’t include, bbPress will use the default Kakumei templates.

We’re working on making things tidier too. In future releases, some of these templates may get combined or removed all together.

Notes

And finally, here’s a few things to keep in mind as a theme designer.

• bbPress has some predefined function for adding CSS classes to various elements. Check out how the default templates use alt_class(), post_del_class() and topic_class().
• The AJAX scripts used on the topic pages depend somewhat on the markup the templates use and requires the javascript included in the header file of the default template.
  • The list (or table or whatever) of posts should have the id thread.
  • Each post should be contained in an element with id post-{$post_id}.
  • The post form should have id postform and its submit button should have the id postformsub.
  • The tag list for the current user should have the id yourtaglist and that for all other users should have the id otherstaglist.
  • Each tag should be contained in an element with id tag-{$tag_id}_{$user_id}.
  • The tag form should have id tagform and its submit button should have id tagformsub.
  • The meta information about a topic should be contained in an element with id topicmeta and the element containing the favorites link should have id favorites-toggle.

  All these restrictions are a little annoying. We hope that the markup of the default Kakumei theme is robust enough that you’ll be able to do most of your customization through CSS. If you have suggestions for better markup, let us know.