Skip to:

template overload isn’t working as expected

  • kalico


    I want to add some customizations to the BP groups directory page — where the list of groups to join is displayed. However, my attempts at modifying the overloaded template have failed. I have done many other theme modifications using template overloads, so my basic directory structure seems ok, but for some reason this one is not working the way I expect it to.

    Based on this page I copied


    over to


    but it has no effect on my live page.

    Then I read this page which says:

    Group Directory page

    If you are on the groups directory page, BuddyPress will use the following template hierarchy:

    1. /buddypress/groups/index-directory.php
    2. The rest of the base templates as listed here.

    So I renamed




    and whammo….it totally clobbered my page. Not whitescreen, just mangled parts of the page, sidebar out of place, CSS broken, etc.

    So what I’m seeing here is that index.php does not get noticed at all, whereas index-directory.php goes get noticed, but acts entirely different from what I would expect, even though it’s identical to the original index.php from bp-default.

    Can anyone explain what might be going on here?

    Thanks in advance.

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

  • danbp


    bp-default theme is the old mandatory theme. BP doesn’t use it anymore since 1.9. This historical theme is only in for backpat compatibility perhaps still in use on some very old installs…

    Actually, BP fits to almost any modern theme, correctly formated and respecting WP’s code standarts.

    What you can try is to create in your child theme, a directory called “community” or “buddypress”.
    If you need to alter a bp template, you copy the original file from here:

    You copy only the file you need and you respect the folder structure who starts from /buddypress/.../

    Note that you if you want to use /community/ in the child, this folder is equal to /buddypress/ in the original template folder. You copy (for ex.) group’s index.php file.



    I don’t know what’s going on here — I made an edit, and when I hit “submit” my post was gone. I’ve force-reloaded the page several times, and still my post does not show up. However, when I try to repost the same information, I get a message “ERROR: Duplicate reply detected; it looks as though you’ve already said that.”

    If you do not see my reply above (it should be the 3rd message in this thread, this one should be the 4th) then please write back and let me know, and I’ll attempt to repost it.




    I’m now trying to re-word my original response, so hopefully it will get past whatever filter is preventing me from reposting the dropped message.

    Thanks @danbp. Unfortunately, this wasn’t the solution I needed. Partly, perhaps, but not entirely.

    As you pointed out, I was wrongly copying files from bp-themes rather than bp-templates (a codeblind mistake on my part). But I was doing everything else correctly, in terms of file structure and use of /community/ according to your write up.

    I went through my steps again, this time copying


    over to


    with zero impact. (I test this by adding a bit of text in a spot that should display on the live site, and it does not show up. Tried several different places, no effect.)

    This would seem to demonstrate that BP is not reading that index.php file at all. It’s only reacting to the template change if it is called “index-directory.php”.

    I changed the file name (without moving the file) from index.php to index-directory.php, just as I did before, but again, it did not work as expected. The groups directory page picked up the new template, but it displayed a completely stripped-down version of the page, with no CSS at all (white background, default font, everything left-aligned, etc).

    I have been assuming that the index.php file would be a proper starting point (a template) to create custom modifications to the groups directory page (i.e., index-directory.php), but clearly that does not hold true.

    This seems very strange, because in looking at the php code in index.php, it’s got all the elements I see in the source for my live groups directory page. So it appears to be getting that exact same information from “somewhere else” within the plugin structure, but I can’t figure out where.

    My question is now: What file should I use as a starting point to duplicate my existing groups directory, so I can make custom modifications?

    I do hope you (or someone) can point me in the right direction. Thanks in advance!

    @kalico when you create thse template files for index they must be full templates not partials i.e they must include the WP get_header(), get_footer() and any other markup structures representing your themes structure.



    @kalicoTemplate hierarchy doesn’t work for bp-default themes or older-style BuddyPress themes that are derivatives of bp-default.

    In your situation, I would just modify /themes/YOUR-THEME/groups/index.php directly.

    If this doesn’t exist in your theme, that means you are using a child theme, so copy /themes/PARENT-THEME/groups/index.php to your child theme and make your mods.

    I’m so wrong! Read my updated reply below.



    Hi @r-a-y, Thank you for the reply. My parent theme doesn’t have that file, and yes I am using a child theme already, and I do understand that it doesn’t work with bp-default themes, but it SHOULD work with bp-default templates – no?

    For reasons I don’t understand,


    does not work as the index.php file when copied to


    Now, if you’re saying I should not expect it to, then….what should I use as my template for the groups index?

    If I’m reading correctly, @hnla says I should just use a regular page template from my theme, and strategically add in the contents of /bp-templates/bp-legacy/buddypress/groups/index.php (which, as he points out, is not a complete file with header, etc) and call it index-directory.php. (And thank you, @hnla for the reply as well 🙂 )

    I can do that. However, I haven’t found any documentation to that effect, and it seems to be much more complicated than the template hierarchy documentation implies:

    Therefore, you can modify any bp theme compatibility template by copying it over from:



    /my-theme/community/ or /my-theme/buddypress/

    That is what I have always done, and I’ve never had this much trouble with it before.

    I have other template modifications to make, and if Hugo’s instructions are correct, it would be really helpful to know where the documentation is, in case I have further issues.

    If the template hierarchy page is correct, then something is wrong with my site, because I’m following those instructions (in spite of my original faux pas of using “themes” instead of “templates”).

    Thanks in advance for any further clarification you can provide.



    Actually, what hnla points out is correct. Disregard what I previously wrote, I was thinking of something entirely different!

    index-directory.php has to be a full template with get_header() and get_footer().

    You should copy your theme’s page.php template and rename it to index-directory.php. Then move this file to wp-content/themes/YOUR-THEME/buddypress/groups/index-directory.php.

    Please note that template hierarchy means modifying the surrounding elements of the page. If you just want to modify the group loop itself, then just copy /groups/groups-loop.php and make your changes to that file.



    Thanks @r-a-y. That’s very helpful. Appreciate the correction. I’ll give that a shot.


    I can do that. However, I haven’t found any documentation to that effect, and it seems to be much more complicated than the template hierarchy documentation implies:

    Hmm I was 99.999% sure I had or we (r-a-y & I wrote the two main codex pages for template hierarchy) had explicitly mentioned this point about full templates but I checked the other day and failed to find it, so our apologies for that omission. I will try & rectify that with a codex update on relevant pages when I have time.



    Hallelujah! After MUCH ado, I have finally figured out what the heck is going on here.

    At first, every change I made per the instructions from @hnla and @r-a-y had failed. I was sure it must be something in my set up, so I did a LOT of detective work and testing, and finally discovered multiple sources of problems.

    Although it’s unlikely this will be relevant to many others, I am posting it just in case it might help someone. I always like reading other people’s solutions — it often gives me fresh ideas, even if it’s not an exact fit. So here goes….

    1) I was copying my page.php from my child theme to use as /groups/index-directory.php, and it was breaking the groups directory page. Well…it’s in the child theme because it’s been modified from the parent theme, and whatever mods I made were not playing nice with the BP template hierarchy system. When I copied page.php from the parent theme, it worked just fine. (Maybe that’s why they are theme devs and I am a lowly hacker…)

    Now having solved the problem of which file makes the best template for a new groups directory, I had to figure out how to actually affect the area of the page that I want to affect: the section where the tabs and the group search live. Those are not in the page.php file, they are coming from somewhere else.

    I hunted down some bits of code that were in the section I wanted to modify, and searched all the theme and plugin files on my system for that snippet, and discovered the next problem…..

    2) The only place that the code exists is in BP Groups Hierarchy plugin, and BP itself. I had BP Groups Hierarchy (old version, with Ray’s compiled updates) enabled, along with an older version of BuddyPress (due to incompatibility issues between new BP and old BP Groups Hierarchy). Within this environment, the BP Groups Hierarchy plugin was actually taking over the display of the groups/index.php so none of my changes were showing up.

    3) The next thing I realized is that I have a customized community.php file (a.k.a. buddypress.php) which is where my buddypress loop actually lives. Or, more specifically, that file is pulling content-page.php. So I had to use that file (which had already started out as a copy of the parent theme’s page.php) to create a working and fully compatible template.

    In a nutshell, my new groups/index-directory.php goes something like this:

    The first part comes from COMMUNITY.PHP, which is a customized version of the PARENT THEME’S PAGE.PHP

    Then the PAGE TITLE CODE is copied from the child theme’s CONTENT-PAGE.PHP

    Next I replace THE LOOP from COMMUNITY.PHP with the ENTIRE CONTENTS of the original/default GROUPS/INDEX.PHP. We’ll call this the “new loop”.

    After the “new loop” section of the code, then my CUSTOM COMMUNITY.PHP FILE takes over again, filling out the rest of the file with the sidebar and footer.

    Note: Somewhere in here, I had to add a ?> to close the PHP. Can’t remember exactly where, but something I copied did not have a closing PHP tag. So if you get a blank screen, that would be a good place to look. 🙂

    I’ve posted my entire custom index-directory.php in a gist in case anyone wants to see it. It is commented in 4 places where I transitioned from one fragment to another. You can search on “GROUPS INDEX TEMPLATE” to find the comments in the gist. My parent theme is Zerif Pro, and I have a customized community.php/buddypress.php file. so you CANNOT JUST COPY this code. It just serves as an example of how I cobbled the code together to get a working template. Hope it is helpful.

    Grateful thanks to Ray and Hugo for all the assistance and advice!

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