Justin Tadlock

How to create custom views in bbPress

In bbPress, we have these things called views. Views are used to show a certain, well, view of your topics, posts, users, and so on depending on the purpose of the view. Several plugins offer alternative views (e.g., highest rated topics, most posts, etc.).

Fortunately, bbPress comes loaded with a function called bb_register_view() that makes this extremely simple. I’ll be showing you how to create new views in this tutorial.

Some things worth noting:

  • Views are displayed according to the view.php file within your theme.
  • bbPress comes loaded with with two default views: “Topics with no replies” and “Topics with no tags.”
  • The My Views plugin creates some neat views and is definitely worth checking out.

Here’s a look at some custom views I’ve create:

Custom bbPress views
Custom bbPress views

The bb_register_view() function

bb_register_view() is the function that handles creating new views. Let’s take a look at its parameters and what we can do with them.

bb_register_view( $view, $title, $query_args = '', $feed = TRUE );

$view is what you’ll name the view. What you put here will also become part of the permalink to the view page.

$title is the title of the view that you’ll see on screen. It’ll show in view lists and likely on your view page. Note: Theme and plugin developers should localize this so it can be translated.

Optional: $query_args should be an array of arguments on how to display the topics and such on the view’s page.

Optional: $feed is whether the view should have its own feed. This is set to true by default.

Creating a custom view

Now that you know how the bb_register_view() function works, it’s time to create a couple of views. The first thing you should do is open your theme’s functions.php. If your theme doesn’t have this file, create one.

We’ll create two new views: Alphabetical (ascending) and Alphabetical (descending). Drop this code in your functions.php file:

<?php

add_action( 'bb_init', 'my_custom_views_init' );

function my_custom_views_init() {
    $args = array( 'order_by' => 'topic_title', 'order' => 'ASC' );
    bb_register_view( 'alphabetical-ascending', __('Alphabetical: Ascending (A – Z)', 'example'), $args, false );

    $args = array( 'order_by' => 'topic_title', 'order' => 'DESC' );
    bb_register_view( 'alphabetical-descending', __('Alphabetical: Descending (Z – A)', 'example'), $args, false );
}

?>

In your views list, you should now be able to click on either of these views and see what happens.

Custom view templates

By default, bbPress will use your theme’s view.php template to display a view. Sometimes, you might want to create an entirely custom template though, which is perfectly fine.

For the sake of simplicity, we’ll create two new templates with the same names as our views from above: alphabetical-ascending.php and alphabetical-descending.php. Place those files in your theme’s folder.

Then, add this code to your functions.php file:

<?php

add_action( 'bb_custom_view', 'my_custom_views_templates' );

function my_custom_views_templates( $view ) {

    if ( 'alphabetical-ascending' == $view ) {
        bb_load_template( 'alphabetical-ascending.php' );
        exit();
    }
    elseif ( 'alphabetical-descending' == $view ) {
        bb_load_template( 'alphabetical-descending.php' );
        exit();
    }
}

?>

Of course, what goes in your custom templates is entirely up to you. Use your imagination.

Note: There may be a more elegant way to load custom view templates, so if you have suggestions, I’d love to hear them.

How to list your views

Most bbPress themes will likely list your views somewhere within the theme, but if yours doesn’t, just drop this code wherever you need to list them:

<ul>
    <?php foreach ( bb_get_views() as $view => $title ) : ?>
        <li class="view"><a href="<?php view_link( $view ); ?>" title="<?php view_name( $view ); ?>"><?php view_name( $view ); ?></a></li>
    <?php endforeach; ?>
</ul>

Views are not pages

On a final note, I wanted to point out that views are not pages. bbPress is not a CMS like WordPress, which is what you’d use to create things like pages. One could use views to create ad hoc pages, but this seems a bit crude.

I can see the need for something like a page feature for forum-only sites, but I’ll leave that discussion for another time.