分类： 入门

Codex Home → BuddyPress Plugin Development → Using BP Theme Compat in Plugins
Using BP Theme Compat in Plugins

A BuddyPress plugin can need to display content in several areas of a BuddyPress powered community :

In its own directory
In the member』s profile pages
In groups

The goal of this tutorial is to show you a way to take benefit of the magic that will be introduced in the next major release of BuddyPress (version 1.7) to maximize theme compatibility for BuddyPress content and for the content generated by your plugin.
In Plugin』s main directory.
When using the BP_Component class, we can specify that our plugin will have its own directory area. Here』s a quick reminder :
class BP_Plugin_Component extends BP_Component {

function __construct() {}
function includes() {
// Files to include
$includes = array(
/* some files */
'includes/bp-plugin-screen.php',
/*some other files */
);

parent::includes( $includes );
}

function setup_globals() {
$globals = array(
'slug' => 'some-slug',
'root_slug' => 'some-root-slug',
/* has_directory is set to true in order to setup plugin's main directory */
'has_directory' => true,
'notification_callback' => 'function_to_format_notification',
/* etc... */
);

parent::setup_globals( $globals );
}

function setup_nav() {}
function setup_admin_bar() {}
}

function bp_plugin_load_core_component() {
global $bp;

$bp->bp_plugin = new BP_Plugin_Component;
}
add_action( 'bp_loaded', 'bp_plugin_load_core_component' );

In this example, i』m using the file bp-plugin-screen.php in order to hold all the functions that will allow us to set the needed template for our plugin』s main directory.
So far, in order to indicate to BuddyPress the path to my plugin』s template, i used to filter the bp_located_template hook :

function bp_plugin_load_template_filter( $found_template, $templates ) {

//Only filter the template location when we're on the bp-plugin component pages.
if ( !bp_is_current_component( 'bp-plugin' ) )
return $found_template;

foreach ( (array) $templates as $template ) {
if ( file_exists( STYLESHEETPATH . '/' . $template ) )
$filtered_templates[] = STYLESHEETPATH . '/' . $template;
elseif( file_exists( TEMPLATEPATH . '/' . $template ) )
$filtered_templates[] = TEMPLATEPATH . '/' . $template;
else
$filtered_templates[] = BP_PLUGIN_DIR . '/templates/' . $template;
}

$found_template = $filtered_templates[0];

return apply_filters( 'bp_plugin_load_template_filter', $found_template );
}

add_filter( 'bp_located_template', 'bp_plugin_load_template_filter', 10, 2 );

We first check for our template file in the active theme or in the parent theme, and if nothing was found, we add to the templates array the path to our plugin template folder. Doing so, we allow themes to 「override」 and adapt the template to their design.
This done, in order to tell to BuddyPress to load the required template for my root plugin directory i filter the hook 『bp_screens『 :
function bp_plugin_screen_index() {
// i first check i'm on my plugin directory area...
if ( !bp_displayed_user_id() && bp_is_current_component( 'bp-plugin' ) && !bp_current_action() ) {
bp_update_is_directory( true, 'bp-plugin' );

//... before using bp_core_load_template to ask BuddyPress
// to load the template bp-plugin (which is located in
// BP_PLUGIN_DIR . '/templates/bp-plugin.php)
bp_core_load_template( apply_filters( 'bp_plugin_screen_index', 'bp-plugin' ) );
}
}
add_action( 'bp_screens', 'bp_plugin_screen_index' );

As you can see, when BuddyPress will run the function bp_core_load_template, which is located at line 346 of the /bp-core/bp-core-catchuri.php file (in BuddyPress 1.7-beta1), as soon as it meets the 『bp_located_template『 filter, my function 『bp_plugin_load_template_filter』 will step in to add my plugin template path. This is made possible thanks to line 379 of this file :
// Filter the template locations so that plugins can alter where they are located
$located_template = apply_filters( 'bp_located_template', locate_template( (array) $filtered_templates, false ), $filtered_templates );

In BuddyPress 1.7, this method is still working fine as soon as the community administrator is using the bundled BP Default theme or a child of it. But, if he decides to enjoy the 「BP Theme Compat」 great new feature in order to use any WordPress theme, then the content generated by our plugin will not display the best way.
To maximize this, we need to use the new hook introduced in the 1.7 version : do_action(『bp_setup_theme_compat』) which is located at line 410 of the bp_core_load_template function.
Actually, if BuddyPress haven』t found the required template then this hook is finally fired. Unlike what we』ve done just above, the funny part of this tutorial is that we first won』t tell BuddyPress what template to load if the active theme is not BP Default or a child of it.
In order to check if BP Default, or a child of it, or an eventual BuddyPress theme that is not relying on BP Default is active on the blog, i use this function :
function bp_plugin_is_bp_default() {
// if active theme is BP Default or a child theme, then we return true
// If the Buddypress version is < 1.7, then return true too
if(current_theme_supports('buddypress') || in_array( 'bp-default', array( get_stylesheet(), get_template() ) )  || ( defined( 'BP_VERSION' ) && version_compare( BP_VERSION, '1.7', ' 0,
'post_title' => 'BP Plugin Directory',
'post_author' => 0,
'post_date' => 0,
'post_content' => '',
'post_type' => 'bp_plugin',
'post_status' => 'publish',
'is_archive' => true,
'comment_status' => 'closed'
) );
}
/**
* Filter the_content with bp-plugin index template part
*/
public function directory_content() {
bp_buffer_template_part( 'bp-plugin' );
}
}

new BP_Plugin_Theme_Compat ();

Thanks to this step, we just made sure that BuddyPress will look for the bp-plugin template in the WordPress Theme or in the BP Legacy templates before trying to load it.
However, unless the active theme thought about adding this template, it won』t find it as it won』t check our plugin』s templates folder. We need to reference our plugin template folder first.
To do so, we can add a filter on the 「bp_get_template_stack」 hook in order to store our plugin path into the BuddyPress template paths :
function bp_plugin_add_template_stack( $templates ) {
// if we're on a page of our plugin and the theme is not BP Default, then we
// add our path to the template path array
if ( bp_is_current_component( 'bp-plugin' ) && !bp_plugin_is_bp_default() ) {

$templates[] = BP_PLUGIN_DIR . '/templates/';
}

return $templates;
}

add_filter( 'bp_get_template_stack', 'bp_plugin_add_template_stack', 10, 1 );

Doing so we make sure that if our template is not found in the WordPress active theme or in bp-legacy, it will be found in our plugin』s template folder. Finally we just need to adapt our plugin template in BP_PLUGIN_DIR . 『/templates/』 in order to strip the get_header, get_sidebar, and get_footer calls and to simply put our output into the new container tag 『

Codex Home → Developer Resources → Function Examples → bp_profile_field_data()
bp_profile_field_data()

Description
Takes a field name and outputs its corresponding field value. Can be specified by user ID.
Usage
$args = array(
'field' => 'Field Name',
'user_id' => 1
);
bp_profile_field_data( $args );

Parameters

field
(string) Name of profile field to retrieve. The default is false

user_id
(integer) Display field corresponding to a specific user. If no parameter is used, it defaults to bp_displayed_user_id()

Example
To get the current user』s 『Birthday』:
bp_profile_field_data( 'field=Birthday' );
To get User 4』s 『Hire Date』:
bp_profile_field_data( 'field=Hire Date&user_id=4' );
Source File
bp_profile_field_data() is located in bp-xprofile/bp-xprofile-template.php

Codex Home → Developer Resources → Automated Testing → Writing automated tests for BuddyPress-dependent plugins
Writing automated tests for BuddyPress-dependent plugins

The automated testing suite introduced into BuddyPress after 1.7 make it easy to write unit tests for your BP-dependent plugins. Our implementation assumes that you』ll be writing your plugin tests according to wordpress-plugin-tests method. If you』re new to writing WordPress plugin tests, it』s highly recommended that you use the wordpress-plugin-tests technique (or, even easier, the wp-cli unit-tests scaffold tool.
BuddyPress provides two useful kinds of utilities that your plugin』s tests can take advantage of. We』ll discuss the two utilities briefly, and follow it with a working example.
Note: In this tutorial, we』ll be extending BP』s test suite for use in a plugin. But a similar technique could be used for BP themes, as well as for setting up integration tests for an entire, highly-customized BuddyPress installation.

BuddyPress installation and bootstrapping – If your plugin depends on BuddyPress, then you』ll need to make sure that BuddyPress is installed and running when running your tests. Establishing the proper dependencies manually can be very tricky, because BP』s setup routine requires the installation of custom tables and other important one-time configuration, and it all has to happen in a very specific order in order to have a functioning version of BuddyPress. Luckily, you don』t have to do it manually. Just require buddypress/tests/phpunit/includes/loader.php in a callback function hooked to muplugins_loaded using tests_add_filter() – right before you manually load your own plugin – and BP will make sure that (1) BP gets installed correctly, and (2) BP is fully loaded.
BP_UnitTestCase and data factories – When you use the BP_UnitTestCase class for your test cases, you automatically get access to some helpful utility methods (such as go_to(), which is sensitive to the requirements of BP URLs), as well as the BuddyPress data factories for generating groups, activity, and other BP test data. Does your plugin have additional data factories? Consider building your own _UnitTestCase that extends BP_UnitTestCase.

What follows is an annotated bootstrap.php that demonstrates the best way to take inherit BP』s unit testing tools in your own plugin』s test suite. The plugin in the example can be found at BP-CLI, and the code below is from the file bp-cli/tests/bootstrap.php. You should be able to copy and paste this code into your own tests/phpunit/bootstrap.php file – just change the paths for your plugin loader file, and your optional _UnitTestCase class file.
<?php

// The BP_TESTS_DIR constant is a helpful shorthand for accessing assets later
// on. By defining in a constant, we allow for setups where the BuddyPress
// tests may be located in a non-standard location.
if ( ! defined( 'BP_TESTS_DIR' ) ) {
define( 'BP_TESTS_DIR', dirname( __FILE__ ) . '/../../buddypress/tests/phpunit' );
}

// Checking for the existence of tests/phpunit/bootstrap.php ensures that your version
// of BuddyPress supports this kind of automated testing
if ( file_exists( BP_TESTS_DIR . '/bootstrap.php' ) ) {

// The functions.php file from the WP test suite needs to be defined early,
// because it gives us access to the tests_add_filter() function
require_once getenv( 'WP_TESTS_DIR' ) . '/includes/functions.php';

// Hooked to muplugins_loaded, this function is responsible for bootstrapping
// BuddyPress, as well as your own plugin
function _bootstrap_plugins() {

// loader.php will ensure that BP gets installed at the right time, and
// that BP is initialized before your own plugin
require BP_TESTS_DIR . '/includes/loader.php';

// Change this path to point to your plugin's loader file
require dirname( __FILE__ ) . '/../bp-cli.php';
}
tests_add_filter( 'muplugins_loaded', '_bootstrap_plugins' );

// Start up the WP testing environment
require getenv( 'WP_TESTS_DIR' ) . '/includes/bootstrap.php';

// Requiring this file gives you access to BP_UnitTestCase
require BP_TESTS_DIR . '/includes/testcase.php';

// Optional: If your plugin needs its own _UnitTestCase class, include it
// here so that it's available when your testcases are loaded
require dirname( __FILE__ ) . '/bp-cli-testcase.php';
}

Codex Home → BuddyPress Theme Development → Theme Compatibility → Template Hierarchy
Template Hierarchy

A detailed look at theme compatibilities template hierarchy
BuddyPress 1.7 introduced universal theme compatibility making it easier for WordPress theme designers to work with BuddyPress.
What this means is if you are on a BuddyPress page, BuddyPress will look for a specific template file in your theme and use that template to inject its contents into.
If you』re unfamiliar with BP』s Theme Compatibility please read this guide first which explains the templates and how and where to overload them theme compatibility
The base templates that BP looks for in order of priority are:

plugin-buddypress.php
buddypress.php
community.php
generic.php
page.php
single.php
singular.php
index.php

Most of the time BP will use page.php since that template file exists in the majority of WordPress themes. However, if you wanted to style BuddyPress pages differently than a regular WordPress page, you could add a template file named buddypress.php to your theme』s directory and BP would use that template instead since that file is ahead of page.php in the hierarchy above.
See also: a-quick-look-at-1-7-theme-compatibility for an introduction to theme compatibility and how to overload the templates to your child theme
This is all fine and dandy if you wanted all your BuddyPress pages to look the same, but let』s say I wanted to style the member pages differently than group pages? You』ll notice that this isn』t quite possible.
What if BuddyPress had a more advanced template hierarchy that looked for additional template files depending on the BuddyPress page you』re on?
BuddyPress 1.8 solves this problem.
Overview of Template Hierarchy in BuddyPress
Single Member Pages
If you are on a single member page, BuddyPress will use the following template hierarchy:
(We will use the following URL as an example – example.com/members/admin/activity/mentions/)

/buddypress/members/single/index-id-{id}.php – If the member profile』s user ID is 1, BuddyPress will look to use /buddypress/members/single/index-id-1.php first.
/buddypress/members/single/index-nicename-{nicename}.php – If we look at the sample URL, the user』s nicename is admin, BuddyPress will look to use /buddypress/members/single/index-nicename-admin.php second.
/buddypress/members/single/index-action-{action}.php – If we look at the sample URL, the action is mentions, BuddyPress will look to use /buddypress/members/single/index-action-mentions.php third.
/buddypress/members/single/index-component-{component}.php – If we look at the sample URL, the component is activity, BuddyPress will look to use /buddypress/members/single/index-component-activity.php fourth.
/buddypress/members/single/index.php – If this template file is used in your theme, all member pages will use this template. BP will look to use this if the other four templates mentioned above are not found.
The rest of the base templates as listed here.

Single Member Front page
Since version 2.6.0, if a front.php template is located into the /buddypress/members/single/ directory it will be used as the home page for members profile pages. This template is not included into the BP Legacy template pack. Themes can use it to customize the Member』s home page. If you need different front pages for your users, you can use this template hierarchy:

/buddypress/members/single/front-id-{id}.php – If the member』s ID is 42, BuddyPress will look to use /buddypress/members/single/front-id-42.php first.
/buddypress/members/single/front-nicename-{nicename}.php – If the member』s nicename is 「john」, BuddyPress will look to use /buddypress/members/single/front-nicename-john.php second.
/buddypress/members/single/front-member-type-{member-type}.php – If you registered member types (see this codex page), you can use the member type name to build different front pages for each member type. For instance BP will look to use /buddypress/members/single/front-member-type-student.php if the other two templates mentioned above are not found and the displayed user has the 「student」 member type.
/buddypress/members/single/front.php – If none of the above are found.

If you have trouble determining the action or component, you could try using this small debug plugin to help output information about the current BuddyPress page.
Single Group Pages
If you are on a single group page, BuddyPress will use the following template hierarchy:
(We will use the following URL as an example – example.com/groups/my-test-group/members/)

/buddypress/groups/single/index-id-{id}.php -If the group』s ID is 1, BuddyPress will look to use /buddypress/groups/single/index-id-1.php first.
/buddypress/groups/single/index-slug-{slug}.php – If we look at the sample URL, the slug is my-test-group, BuddyPress will look to use /buddypress/groups/single/index-slug-my-test-group.php second.
/buddypress/groups/single/index-action-{action}.php – If we look at the sample URL, the action is members, BuddyPress will look to use /buddypress/groups/single/index-action-members.php third.
/buddypress/groups/single/index-status-{status}.php – Either public, private or hidden. So let』s say you wanted all private groups to have a similar look, you would want to add the following template – /buddypress/groups/single/index-status-private.php. BP will look to use this if the other three templates mentioned above are not found.
/buddypress/groups/single/index.php – If this template file is used in your theme, all group pages will use this template. BP will look to use this if the other three templates mentioned above are not found.
The rest of the base templates as listed here.

Single Groups Front page
Since version 2.4.0, we added a template hierarchy to the front.php template. This template is not included into the BP Legacy template pack. Themes can use it to customize the Group』s home page.

/buddypress/groups/single/front-id-{id}.php – If the group』s ID is 1, BuddyPress will look to use /buddypress/groups/single/front-id-1.php first.
/buddypress/groups/single/front-slug-{slug}.php – If we look at the sample URL, the slug is my-test-group, BuddyPress will look to use /buddypress/groups/single/front-slug-my-test-group.php second.
/buddypress/groups/single/front-group-type-{type}.php – (Since 2.6.0) If the group has the type of 「team」, BuddyPress will look to use /buddypress/groups/single/front-group-type-team.php next.
/buddypress/groups/single/front-status-{status}.php – Either public, private or hidden. So let』s say you wanted all public groups to have a similar front page, you would want to add the following template – /buddypress/groups/single/front-status-public.php. BP will look to use this if the templates mentioned above are not found.
/buddypress/groups/single/front.php – If none of the above are found.

If you have trouble determining the slug, action or status, you could try using this small debug plugin to help output information about the current BuddyPress page.
Activity Permalink pages
If you are on an activity permalink page, BuddyPress will use the following template hierarchy:

/buddypress/activity/single/index.php
The rest of the base templates as listed here.

Activity Directory page
If you are on the activity directory page, BuddyPress will use the following template hierarchy:

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

Member Directory page
If you are on the members directory page, BuddyPress will use the following template hierarchy:

/buddypress/members/index-directory-type-{member_type}.php when viewing member type specific directory page, {member_type} is the current member type.
/buddypress/members/index-directory.php
The rest of the base templates as listed here.

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

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

Group Creation page
If you are on the group creation page, BuddyPress will use the following template hierarchy:

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

Site Directory page
Only applicable if you are running WordPress multisite.
If you are on the site directory page, BuddyPress will use the following template hierarchy:

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

Site Creation page
Only applicable if you are running WordPress multisite.
If you are on the site creation page, BuddyPress will use the following template hierarchy:

/buddypress/blogs/index-create.php
The rest of the base templates as listed here.

Registration page
If you are on the registration page, BuddyPress will use the following template hierarchy:

/buddypress/members/index-register.php
The rest of the base templates as listed here.

Activation page
If you are on the activation page, BuddyPress will use the following template hierarchy:

/buddypress/members/index-activate.php
The rest of the base templates as listed here.

Codex Home → Participate and Contribute → Codex Standards & Guidelines
Codex Standards & Guidelines

If you are considering contributing to the codex this simple guide is here to help you with the formatting of pages and standards & conventions to follow to keep a set appearance to pages.
The Codex is curated by a team of volunteers they will check and verify articles for accuracy and adherence to Codex Standards, this is in order to maintain a consistent quality of article and standard throughout the codex. If you notice any articles of concern or think something is outdated or needs checking please contact one of the team members, if you are sure an article contains content that needs attention you may edit it and add a warning to the top of the article – please see the bottom of this page for markup to be copied and used in such circumstances.
Please note: All entries to the Codex are covered by the GNU General Public Licence. All entries may be edited or altered by other contributors.
Sections

How to Create a New Codex Article
How to Edit/Update an Article in the Codex
Codex General Guidelines
Codex Conventions
Formatting Guide
Adding article header messages

How to Create a New Codex Article

Log in using your WordPress username and password.
Click on the 「Create New Page」 link under the header or click on the 「+New > Page」 link on the WP Toolbar
Add the Title of your article
Add the article metas: Versions, Components, Types and Context. Meta boxes are located on the screen』s right sidebar
Add your article in the appropriate codex section in the Page Attributes meta box under the Context box.
For reference, please go to the BuddyPress Codex Table of Contents which is updated regularly to guide you where to place your article
Add content of your article. Check that it follows the Codex General Guidelines, Codex Conventions, and Formatting guides posted below for your reference
After you』re done, click on the 「Publish」 button

How to Edit/Update an Article in the Codex

Log in using your WordPress username and password
Navigate to the page you want to edit/update
Click on the 「Edit Page」 link under the header of the page or click on the 「Edit Page」 link on the WP Toolbar
After you have made the edit/update, please double-check that the Versions, Components, Types and Context are correct and updated as well
Click on the 「Update」 button in the Publish meta box

General Guidelines
Broad guidelines on writing for the BuddyPress Codex

When writing articles please use the second-person point of view to address the reader. e.g. 「Now navigate to your」 Rather than 「Now navigate to our「
When writing technical articles (functions, actions, etc.) please use the draft template you will find in the dashboard, copy and paste it』s body outline markup to your new post
Please keep styling to a minimum, avoid inline styling of elements unless to provide something like a color highlight if thought necessary to lend further emphasis to a piece of text e.g styling a warning in red Ensure you have backed up your DB. Please use elements sparingly , are typographic conventions and used to embolden text and italicize text for foreign & scientific words/phrases; , are to lend weight or importance to a word or phrase i.e 』em』 is not used simply to visually style text in italics
Links: External resource links: Provided to the bottom of the article framework is a section for links to external resources, please use this section for any links to resources that help further however please ensure that these links are additional resources and that your article does not depend on them for all or any part of your article explanation, the reasoning here is external links are not guaranteed to always be available and if the article relies on them and they are down then the article is effectively useless for users. Links that are not related directly to the article content are to be avoided and if found will be removed
Images: Do add images to articles where they help to illustrate your points or explanations, nothing helps illustrate things better than a timely graphic, screen shots of BuddyPress or WordPress screens help to show the reader layouts. As with links please avoid calling remote images, always upload to the media library, and embed. If uploading images please ensure you have the right to do so and are not infringing on any copyrights that may exist. Any images thought to be or that are under copyright will be removed from pages
Creating pages: When creating pages , please ensure you select a suitable 『Version』 tag, and optionally select from available 『Components』 tags & 『Types』. Please only select a parent category from the available parent sections, We request that authors DO NOT create new pages that act as parent pages for their article/s, this is to ensure the integrity of the codex structure, however it may be possible to expand the structure if thought beneficial, but please make a request for this to one of the Codex curation team members for consideration