bbPress Under the Hood: Theme Packages

To display the content for forums, bbPress relies on the theme templates. But, these are specialized template, and most themes don’t have them. So, how the bbPress uses templates?

In previous tutorial in the Under The Hood series, we have discussed how the theme loads bbPress content, focusing mostly on the theme compatibility system that bbPress uses for 99% of all WordPress themes. Now, we have to see how the request content (forum, topic or something else) ends up rendered by bbPress.

Single request loading

To load single forum request, this explanation will use single topic request. This has to display the content of the requested topic. If the theme has single topic template (single-topic.php), that template will have this main element related to bbPress:

<?php if ( bbp_user_can_view_forum( array( 'forum_id' => bbp_get_topic_forum_id() ) ) ) : ?>
  <?php while ( have_posts() ) : the_post(); ?>

    <div id="bbp-topic-wrapper-<?php bbp_topic_id(); ?>" class="bbp-topic-wrapper">
      <h1 class="entry-title"><?php bbp_topic_title(); ?></h1>
      <div class="entry-content">

        <?php bbp_get_template_part( 'content', 'single-topic' ); ?>

      </div>
    </div><!-- #bbp-topic-wrapper-<?php bbp_topic_id(); ?> -->

  <?php endwhile; ?>
<?php elseif ( bbp_is_forum_private( bbp_get_topic_forum_id(), false ) ) : ?>

  <?php bbp_get_template_part( 'feedback', 'no-access' ); ?>

<?php endif; ?>

And, if the theme doesn’t have the template, and if the bbPress uses theme compatibility code, it will use the shortcode to render. This shortcode will check for theme compatibility to setup some of the core query elements, and it will finally render the topic with this:

if ( bbp_user_can_view_forum( array( 'forum_id' => $forum_id ) ) ) {

  bbp_get_template_part( 'content', 'single-topic' );

} elseif ( bbp_is_forum_private( $forum_id, false ) ) {

  bbp_get_template_part( 'feedback', 'no-access' );

}

So, you see that both versions are using bbp_get_template_part() function to load content/single-topic and feedback/no-access template parts.

bbPress Template Parts

Function bbp_get_template_part() is used to load template parts bbPress has for various elements: single forum row in the list of forums, list of forums, list of topics… There are currently more than 50 template parts included with bbPress. All these templates rely on the function to load the templates parts to do so. And, this function is very powerful, allowing you not only to hook in and modify the template part to load, but it uses something called templates storage to determine from where the templates should load. By default, bbPress registers several storages, including the theme. So, you can copy each template part from bbPress into your theme to modify them, and bbPress will load part from theme if exist.

Theme Package

All the template parts bbPress has are part of something called Theme Package. This package contains template parts, JavaScript and CSS needed, including main loader file that is used to setup the theme package. bbPress contains bbPress Default theme package. But, bbPress also allows you to register new theme packages. Theme Package must be contain all the template parts bbPress needs, it must load own CSS and JS files and it can’t rely on the bbPress Default theme package.

Theme Packages give bbPress great flexibility when it comes to the forums display and presentation and they manage to uncouple bbPress core from the rendering layer. But, the best thing about packages is that they can be part of other plugins, allowing the bbPress to still work with any other theme, because Theme Package works outside of the theme, and takes advantage of the bbPress Themes Compatibility System. Theme Package opens up the door for creating totally different forum layouts.

Changing Theme Package

If you don’t have additional Theme Packages registered, bbPress will hide the option to change Theme Package in use. But, if additional packages are registered, new option will be available in bbPress Settings to switch to different Theme Package.

Available Packages

Right now, there is not much choice in theme packages for bbPress. Most websites are just using style customization with some minor templates changes to modify how the forums look like. But, there is one plugin that adds a new Theme Package: GD Quantum Theme Pro for bbPress. If you now about some other plugins that add new bbPress Theme Packages, please, let me know.