Theme Compatibility & Template Files
An explanation of Theme compatibility and its template files
BuddyPress 1.7 heralded a new era in BP development with a vastly improved approach to templating, its aim being to far more closely mirror the WordPress core templating loading approach.
BuddyPress theme compatibility is based on the great work done by John James Jacoby with the standalone bbPress plugin and ported over to BuddyPress.
What this enhancement means in real terms is that now BuddyPress has the ability to provide its core template files injected into standard WordPress templates in a seamless manner. In other words, users may now choose any WordPress theme for their site and then simply activate the BuddyPress plugin. BuddyPress will automatically check to see if the default BP theme is activated; if not, it will fall back to using the new template files for theme compatibility and select a template file from the parent in the same manner WP does in a template hierarchical fashion
E.G., if your theme has a page.php file, BP will use that file to generate the BuddyPress content
To try and ensure that BP content fits in with a chosen theme as much as is possible, only a very basic set of styles are provided.
When working in theme compatibility mode, BP will look for a series of templates in a specific order much in the same manner WordPress does with it’s main templates ( to better understand template hierarchy read the WP codex page: https://codex.wordpress.org/Template_Hierarchy )
The order of precedence for the file BP will use is:
- ‘plugin-buddypress.php’
- ‘buddypress.php’
- ‘community.php’
- ‘generic.php’
- ‘page.php’
- ‘single.php’
- ‘singular.php’
- ‘index.php’
What this means is BP will look for each named file in the order shown in the stylesheet_directory first (a child theme folder) then in the template_directory (parent theme folder)
As soon as it finds one then that file is used and BP generates its content via this file using the files structure(markup) & get_*( ) calls ( technically BP bypasses the content loop replacing it with the BP content ).
How is this useful?
Use a custom template file for all BP content
This ability to describe what file to use means the user/author may ensure a unique file for BP is used while not having to modify the standard WordPress file e.g. page.php
So if we want to remove the sidebar for BP pages but not for all WP ‘pages’ or call a specific BP sidebar get_sidebar(‘buddypress’), we could take a copy of page.php and rename it to ‘community.php.’ (or ‘buddypress.php’) and have BP use this file for all it’s requirements, as can be seen from the order above the first two files will not be found but the third will be and therefore used.
Overloading Template Compatibility theme files
Template compatibility also runs a check to see if two directories or folders exist in a theme:
- ‘buddypress’
- ‘community’
If either of these two folders exist in your theme and they contain BP template files then those files will be used in preference to the bp plugins versions.
Therefore, you can modify any bp theme compatibility template by copying it over from:
/bp-templates/bp-legacy/buddypress/
To:
/my-theme/community/ or /my-theme/buddypress/
N.B. Inside the subfolder ‘community’ you must preserve the path structure/folders that exist in the BP original /buddypress/ folder so /activity/ must be created to hold index.php or any of the other activity templates.
Additionally to keep things neat & tidy you can keep your custom parent template file ‘community.php’ in these folders as well rather than your theme root.
You may override the css by adding a folder /css/* to your theme root if you then, either, copy buddypress.css from /bp-legacy/ or create a new file named buddypress.css this file will be used instead of the buddypress version.
* As of BP 1.8 the paths for assets i.e styles and JS has been modified to look to your ‘buddypress’ or ‘community’ folders first, this means you will be able to locate your /css/ folder inside your buddypress one.
Child Themes
As mentioned earlier, BP will search the stylesheet and template paths for BP files/folders. This means that the principle of creating child themes still holds true and is to be a strongly recommended procedure to follow as always.
As a brief example, if you’re creating a theme using TwentyTwelve as a base, instead of dropping custom files into the parent theme you would create 2012-child with a stylesheet style.css that has a header line:
Template: TwentyTwelve
In your child theme you would then have all your custom BP templates this way updating WP will not overwrite any changes you have made.
For information on creating child themes see: https://codex.wordpress.org/Child_Themes
This has been a basic guide to familiarise you with the new template files and how you can make them work for you in your chosen theme and more advanced options exist.
As of BP 1.8 we introduce an enhanced template hierarchy, this new addition allows the developer to specify unique templates for BP screens such as ‘Groups’, ‘User’ now we can create templates that take a suffix such as a user id, or an ‘Action’ or ‘Component’; these templates then cut in and provide a custom view in the same manner the template hierarchy does presently in 1.7. You can read a more detailed breakdown and explanation of this new template hierarchy on this page: Enhanced template-hierarchy in BP 1.8
More on BuddyPress 1.7 Theme Compatibility
