Skip to:

How is the forum archive page generated?

  • Michael


    Hi there — I’m running WP 3.4.2, bbPress 2.2.2 & buddypress 1.6.1.  Overall, I’m quite happy with the installation, and I’ve done a fair amount of customization on my site  to give it a nice L&F.  I’ve been using a child theme to do all customization, and it’s been reasonably straightforward, but not trivial.  That said, many thanks to all the bbPress folks who are putting lots of time in on this plugin — it’s a great platform.

    Onto my question:  How is the main forum archive page generated?  I want to create my own template to generate this page, and I’ve been stumped trying to trace the sequence of files/calls used to create it.

    For context, I have the Forums Base set to “member-area/forums” in Settings -> Forums. I can go to http://mysite/member-area/forums and see the standard listing of all the forums in a table.  Perfect, just what I want.

    That said, how exactly is this page created?  Which files & calls in the plugin create it?  I’ve found loop-forums.php in …/plugins/bbpress/templates/default/bbpress/which is used to create the table within the page (apparently called as the_content() somewhere), but I can’t find the code blocks that create the header, footer, etc.  Is there a single template page used to create the Archive Base page?

    Apparently this page is generated regardless of whether there is an existing page (permalink) to the same permalink used as Archive Base.  Nifty, but I want to use my own template (the whole thing) for creating the Archive Base page.

    Even when I create a page with a permalink address the same as Archive Base and insert a  [bbp-forum-index] in the post content, I can’t seem to select a Template from the Page Attribute pull down that has any effect on the creation of the Archive Base page.  It’s like it’s hard wired to use a very specific template — that I can’t find in the directory tree.

    Long winded, but I hope that conveys what I’m trying to do.  In short, I just want to create my own template for creating the Archive Base page.  Any pointers are appreciated.



Viewing 6 replies - 1 through 6 (of 6 total)

  • Michael


    For what it’s worth, I’m looking for whatever function is calling content-archive-forum.php.  I can edit this file in my child theme per the Codex, but I’m trying to figure out which function is calling this, and in particular, what function generates the code above the <div id=”bbpress-forums”> at the start of content-archive-forum.php.

    Does bbPress simply use the default post display template, and if so, where is the call to load and execute content-archive-forum.php  made?

    I tried a grep for content-archive-forum in the entire wordpress tree from wp-content on down, and I can’t find where this is called from.

    Many thanks



    and not just this template file



    Okay, I’ve been doing some digging and perhaps as expected, the theme Template page.php (the default WP Template) is being called to build the Archive Base page.  I can edit the page.php in my child theme and customize from there (where it eventually calls the_content(), which apparently executes content-archive-forum.php to display the Forum “front page”), but that’s a brute-force method since page.php is the default Template for all pages. I want to create a Template explicitly for bbPress pages, which means I need a way to specify the Template to use on a per-page basis.

    Normally this would be done by simply creating a Template (like page.php) and put it in your child theme directory, then select it for a specific page you want to apply it to using the wp-admin Edit Page -> Page Attributes -> Template pull down, save it and voila, your page uses your custom Template.

    But with bbPress pages that are “partnered with a WordPress page” (per this topic discussion), this doesn’t work for the partnered page.  The Template setting seems to be ignored, and only for bbPress pages partnered this way.

    This may not be a show-stopper for me, but may be for others looking to customize the overall page Template for their bbPress pages.  Is it a bbPress bug?  I can’t tell, and hopefully I’m missing something painfully obvious, being new to installing/using bbPress.

    Seems like there must be some kind of code frag in the plugin that does something like:

    if (request to display (Archive Base | Topic Base) {
      if ((Archive Base | Topic Base) is partnered with WP page) {
        point the_content() at (content-archive-forum.php | content-archive-topic.php);
        call default page Template;

    JJJ or someone else in-the-know, can you comment on how the “partnering with a WordPress page” works? Where is this performed? Sorry if the question is naive, I’m just having trouble understanding how this partnering works at the Template execution level.

    Many thanks.



    Okay, after some sleuthing I’ve figured out why page.php is *always* called to display the Archive Base and Topic Base.

    The set of available templates appears to be hard-wired in (rather than selecting from all available Templates in the selected Theme) in bbp_get_theme_compat_templates() in …/bbpress/includes/core/template-loader.php.

    bbPress appears to want to select from a known list of “bbPress friendly” Templates to display pages, so it uses this hard-wired list when it goes hunting for the Template to use for displaying a given bbPress page.

    The $templates array includes the following Template file names (as of v2.2.2):

    $templates = array(

    What’s important here is that the ORDERING of the Templates in the array matters, as the function bbp_locate_template() goes through this array sequentially and returns the first Template it finds, which gets used to display the bbPress page.

    bbp_locate_template() searches the Child Theme first, then the Parent Theme, and finally the theme-compat folder, so in theory one can install a Template in the Child or Parent Theme with one of the above Template file names, and so long as bbp_locate_template() finds it first, we’re all cool — that Template will get used for Forum pages.

    There are 3 ways I can see to ensure my special Template is used when the Archive Base is displayed, in order of simplicity:

    1.  Edit the hard-wired $templates array in bbp_get_theme_compat_templates() in template-loader.php and add my template name to the top of the list.  Of course, this is BAD PRACTICE since it will get overwritten in the next bbPress update, but a quick way to test out a Template.

    2.  Create a Template called “plugin-bbpress.php” and put it in my Child Theme directory.  That’s the simplest.

    3.  Hook into bbp_get_bbpress_template, which is used as a filter on the $templates array and add my Template name as the first entry in the array.  This is the way it’s intended to be done, from what I can tell.

    All three of these will work, but they all have the downside of completely ignoring the Template setting of the Page Attribute for a given WP page (see here for what I’m talking about).  For a given WP page that is “partnered” with a bbPress page, bbPress should use the Template specified in the Page Attribute.  That’s what it’s there for.

    While I haven’t tried it yet, perhaps I can hook into bbp_get_bbpress_template and inject the current page’s Page Attribute for the Template.  I’ll have to dig into this a bit and see if it’s worth the effort.  It seems like that would be the cleanest way, as well as in the spirit of how Page Attributes are supposed to be used.

    Wish me luck.




    Okay, I’ve made some further progress with method #3 above (hooking into bbp_get_bbpress_template ).  Here’s the general approach I’m taking:

    add_filter( 'bbp_get_bbpress_template', 'my_add_page_template', $templates );
    function my_add_page_template( array $templates ) {
      $page_template = get_post_meta( $post_id, '_wp_page_template', true );
      if ( $page_template != 'default' )
        array_unshift( $templates, $page_template );
    return $templates;

    The only issue I have right now is that $post_id is difficult to extract if the archive pages (Archive Base and Topics Base) are being displayed. Right now I am hard wiring it to the post_id of the Archive Base page (getting it from the editor), and it works okay but not what I want.

    Since these pages (archives) are custom post types, I haven’t found an easy way to find their post_id’s, and querying globals like $post->ID and calling functions like get_the_ID() and url_to_postid() don’t work for custom post IDs ($post->ID and get_the_ID() return 0).

    QUESTION: For a bbPress page that is currently being built for display, is the post_id of the page being stored somewhere in a bbPress global?


    John James Jacoby


    Modifying core files is never the way. There are plenty of filters in place to override any bit of functionality regarding bbPress’s theme compat,

    There are, as you’ve already found, numerous vectors depending on exactly what you want to accomplish. Each filter has an intended purpose, and solves a specific problem. The underlying code is identical to WordPress’s own template loader, until a template isn’t found (which is a majority of installations.) In that case, bbPress replaces the_content with template parts using page.php, or whatever is a match in the stack you found already.

    Also, don’t forget about the typical WordPress templates: archive-forum.php, and archive-topic.php, etc…

    To answer your question about why get_the_ID() doesn’t work on archive pages, why would it? It’s an archive, not a post/page. There is not ID to get.

    From your posts here, you’ve basically solved much of what’s already in the codex regarding how some of these things work; also, I’m fuzzy on what problem you’re trying to solve. What is the end goal you’re working towards? I can give you some advice on what I think will work best.



    Hi John James — thanks for responding, much appreciated.

    Regarding get_the_ID() not working on an archive page, I understanding your point — there isn’t a page associated with it.

    The only issue I have is that the Forum Archive page is associated (“partnered” to use the documentation phrase) with a real page, and essentially it is just a regular page with embedded shortcodes.

    In my case, the partnered page has content and embedded shortcodes, and it has a real page ID (#1296 in my case).  That’s what I wanted to find so I can extract information specific to that partnered page.

    What am I doing with all this?  Well, the short story is that certain specific pages on my website have some special header images attached above the_content(), and I have created a custom Template in my child theme to handle it.  Information about the slug is extracted, which is used to lookup random images in a database of images.

    I’m trying to keep a consistent approach with all pages, hence the use of a custom Template that I set as a page attribute in the editor.

    None of this is fatal for my needs, but if a page is partnered with the Forum or Topic Archive pages, it seems like the selected Template for displaying those pages should come from the Template page attribute associated with it.  Hence the need for post ID of the partnered page.



Viewing 6 replies - 1 through 6 (of 6 total)
  • You must be logged in to reply to this topic.
Skip to toolbar