Skip to:
Content
Pages
Categories
Search
Top
Bottom
Codex Home → Developer Resources → Group Extension API

Group Extension API

We are currently working on a documentation reboot, here’s the new home of the best accurate docs (WIP). You’re very welcome to contribute to it.

Updated documentation for this section is available here.

Note: This guide is for use with BuddyPress 1.8+. A guide for using the Group Extension API with earlier versions of BP can be found at https://codex.buddypress.org/developer/plugin-development/group-extension-api-prior-to-bp-1-8/.

The group extension API makes it very easy to add custom creation steps, edit screens, navigation items and pages to a group. It essentially allows you to create fully functional extensions to BuddyPress created groups.

Note: If you are building a BuddyPress plugin, please make sure you have read how to check if BuddyPress is active. This is very important. You might also want to check & ensure that the Group component is active using the bp_is-active() function.

Overview

The Group Extension API consists of a base class called BP_Group_Extension, which you extend in your own plugin. BP_Group_Extension does most of the work necessary to integrate your content into BP group – creating new navigation tabs, registering a step during group creation, etc. See the Examples section for working examples.

Use

Use BP_Group_Extension as follows:

  1. In a plugin file, create your own class that extends BP_Group_Extension.
  2. In the __construct() method, pass an array of arguments to parent::init(). Arguments are described in the Configuration section.
  3. Write any methods that your extension requires. See the Methods section for available options.
  4. Register your extension with BuddyPress using bp_register_group_extension()

 

Configuration

In the __construct() method of your extension class, you should define a set of arguments and pass them to parent::init(). (Reference the examples to see how this is done.) Possible arguments:

slug
(required) A unique string identifier for your extension. Used, among other places, in the construction of URLs.
name
(required) The translatable name of your extension. Used as the default value for navigation items and page titles.
visibility
(optional) 'public' means that your extension will be visible to anyone who can access the group, 'private' means it won’t. Defaults to 'public'. Note: BuddyPress 2.1.0 added the new argument 'access', which should be used when possible.
nav_item_position
(optional) An integer describing where your extension’s tab should appear. A number between 1 and 100 is recommended. Defaults to 81.
enable_nav_item
(optional) true for the nav item to be enabled for the current user, false otherwise. Defaults to true. Note: BuddyPress 2.1.0 added the new argument 'show_tab', which should be used when possible.
nav_item_name
(optional) The string you want to appear in the navigation tab for your group extension. Defaults to the of the ‘name’ parameter, described above.
display_hook
(optional) The WordPress action that the widget display method is hooked to. Defaults to 'groups_custom_group_boxes'.
template_file
(optional) The template file that BuddyPress will use as a wrapper for your display content. Defaults to 'groups/single/plugins.php'
screens
(optional) A multi-dimensional array of options related to the three secondary “screens” available to group extensions: ‘create’ (the step dedicated to the extension during the group creation process), ‘edit’ (the subtab dedicated to the extension under the Admin tab of the group), and ‘admin’ (the extension’s metabox that appears on the group page when editing via the Groups Administration Dashboard panels). Each of these screens has a set of configuration options, to be described below. Note that all config values are optional, and you only need to override those values where you want to change the default – BuddyPress will parse your ‘screens’ array, using your provided values when available, otherwise falling back on the defaults.

  • create – Config options for the ‘create’ screen
    • position – The position of the extension’s step in the Create a Group process. An integer between 1 and 100 is recommended. Defaults to 81.
    • enabled – true if you want your extension to have a Create step, otherwise false. Defaults to true.
    • name – The name of the creation step, as it appears in the step’s navigation tab. Defaults to the general ‘name’ value described above.
    • slug – The string used to create the URL of the creation step. Defaults to the general ‘slug’ value described above.
    • screen_callback – The function BP will call to display the content of your create screen. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
    • screen_save_callback – The function BP will call after the extension’s create step has been saved. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
  • edit – Config options for the ‘edit’ screen
    • submit_text – The text of the submit button on the edit screen. Defaults to 'Edit'.
    • enabled – true if you want your extension to have a subtab in the Group Adimn area, otherwise false. Defaults to true.
    • name – The text that appears in the navigation tab for the extension’s Edit screen. Defaults to the general ‘name’ value described above.
    • slug – The string used to create the URL of the admin tab. Defaults to the general ‘slug’ value described above.
    • screen_callback – The function BP will call to display the content of your admin tab. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
    • screen_save_callback – The function BP will call after the extension’s admin tab has been saved. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
  • admin – Config options for the ‘admin’ screen
    • metabox_context – The context for your extension’s metabox. Defaults to 'normal'. (See add_meta_box() for more details.)
    • metabox_priority – The priority for your extension’s metabox. Defaults to ''. (See add_meta_box() for more details.)
    • enabled – true if you want your extension to have a subtab in the Group Adimn area, otherwise false. Defaults to true.
    • name – The text that appears in the navigation tab for the extension’s Edit screen. Defaults to the general ‘name’ value described above.
    • slug – The string used to create the URL of the admin tab. Defaults to the general ‘slug’ value described above.
    • screen_callback – The function BP will call to display the content of your admin tab. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
    • screen_save_callback – The function BP will call after the extension’s admin tab has been saved. BuddyPress attempts to determine this function automatically; see Methods below. Do not change this value unless you know what you’re doing.
access
(optional) Which users can visit the extension’s tab. Possible values: 'anyone', 'loggedin', 'member', 'mod', 'admin' or 'noone'. ('member', 'mod', 'admin' refer to user’s role in the current group.) Defaults to 'anyone' for public groups and 'member' for private groups. Note that the 'mod' level targets only moderators, so if you want to allow access for group moderators and administrators, specify array( 'mod', 'admin' ). Added in BuddyPress 2.1.0 as a more flexible replacement for 'visibility'.
show_tab
(optional) Which users can see the extension’s navigation tab. Possible values: 'anyone', 'loggedin', 'member', 'mod', 'admin' or 'noone'. ('member', 'mod', 'admin' refer to user’s role in the current group.) Defaults to 'anyone' for public groups and 'member' for private groups. Note that the 'mod' level targets only moderators, so if you want to show the tab to group moderators and administrators, specify array( 'mod', 'admin' ). Added in BuddyPress 2.1.0 as a more flexible replacement for 'enable_nav_item'.

 

Methods

BP_Group_Extension has built-in support for a number of different customization methods, which you can override in your extension as needed.

The most prominent of these methods is display(), which BuddyPress uses to generate the output of the plugin’s main tab. Your display() method should echo markup, which BP will automatically place into the proper template.

For the three “screen” contexts – ‘create’, ‘edit’, and ‘admin’ – a flexible system allows you to customize the way that your settings screens work, without unnecessary reproduction of code. Your extension should, at minimum, provide the following two methods:

settings_screen()
Outputs the fallback markup for your create/edit/admin screens
settings_screen_save()
Called after changes are submitted from the create/edit/admin screens. This methods should contain the logic necessary to catch settings form submits, validate submitted settings, and save them to the database.

If your extension requires further customization to one or more of the screens, BuddyPress provides the following methods, which are context-specific:

If your extension contains any of these methods, BP will use them when appropriate. Otherwise, the generic settings_screen() or settings_screen_save() will be used.

 

Examples

Two examples follow. The first is a very simple (though fully functional) implementation of BP_Group_Extension. The second demonstrates some more advanced customizations.

  1. 
/**
 * The bp_is_active( 'groups' ) check is recommended, to prevent problems
 * during upgrade or when the Groups component is disabled
 */
if ( bp_is_active( 'groups' ) ) :

class Group_Extension_Example_1 extends BP_Group_Extension {
	/**
	 * Your __construct() method will contain configuration options for
	 * your extension, and will pass them to parent::init()
	 */
	function __construct() {
		$args = array(
			'slug' => 'group-extension-example-1',
			'name' => 'Group Extension Example 1',
		);
		parent::init( $args );
	}

	/**
	 * display() contains the markup that will be displayed on the main
	 * plugin tab
	 */
	function display( $group_id = NULL ) {
        $group_id = bp_get_group_id();
		echo 'What a cool plugin!';
	}

	/**
	 * settings_screen() is the catch-all method for displaying the content
	 * of the edit, create, and Dashboard admin panels
	 */
	function settings_screen( $group_id = NULL ) {
		$setting = groups_get_groupmeta( $group_id, 'group_extension_example_1_setting' );

		?>
		Save your plugin setting here: <input type="text" name="group_extension_example_1_setting" value="<?php echo esc_attr( $setting ) ?>" />
		<?php
	}

	/**
	 * settings_sceren_save() contains the catch-all logic for saving
	 * settings from the edit, create, and Dashboard admin panels
	 */
	function settings_screen_save( $group_id = NULL ) {
		$setting = '';

		if ( isset( $_POST['group_extension_example_1_setting'] ) ) {
		    $setting = $_POST['group_extension_example_1_setting'];
		}

		groups_update_groupmeta( $group_id, 'group_extension_example_1_setting', $setting );
	}
}
bp_register_group_extension( 'Group_Extension_Example_1' );

endif; // if ( bp_is_active( 'groups' ) )

  2. /**
 * The bp_is_active( 'groups' ) check is recommended, to prevent problems
 * during upgrade or when the Groups component is disabled
 */
if ( bp_is_active( 'groups' ) ) :

class Group_Extension_Example_2 extends BP_Group_Extension {
	/**
	 * Here you can see more customization of the config options
	 */
	function __construct() {
		$args = array(
			'slug' => 'group-extension-example-2',
			'name' => 'Group Extension Example 2',
			'nav_item_position' => 105,
			'screens' => array(
				'edit' => array(
					'name' => 'GE Example 2',
					// Changes the text of the Submit button
					// on the Edit page
					'submit_text' => 'Submit, suckaz',
				),
				'create' => array(
					'position' => 100,
				),
			),
		);
		parent::init( $args );
	}

	function display( $group_id = NULL ) {
        $group_id = bp_get_group_id();
		echo 'This plugin is 2x cooler!';
	}

	function settings_screen( $group_id = NULL ) {
		$setting = groups_get_groupmeta( $group_id, 'group_extension_example_2_setting' );

		?>
		Save your plugin setting here: <input type="text" name="group_extension_example_2_setting" value="<?php echo esc_attr( $setting ) ?>" />
		<?php
	}

	function settings_screen_save( $group_id = NULL ) {
		$setting = isset( $_POST['group_extension_example_2_setting'] ) ? $_POST['group_extension_example_2_setting'] : '';
		groups_update_groupmeta( $group_id, 'group_extension_example_2_setting', $setting );
	}

	/**
	 * create_screen() is an optional method that, when present, will
	 * be used instead of settings_screen() in the context of group
	 * creation.
	 *
	 * Similar overrides exist via the following methods:
	 *   * create_screen_save()
	 *   * edit_screen()
	 *   * edit_screen_save()
	 *   * admin_screen()
	 *   * admin_screen_save()
	 */
	function create_screen( $group_id = NULL ) {
		$setting = groups_get_groupmeta( $group_id, 'group_extension_example_2_setting' );

		?>
		Welcome to your new group! You are neat.
		Save your plugin setting here: <input type="text" name="group_extension_example_2_setting" value="<?php echo esc_attr( $setting ) ?>" />
		<?php
	}

}
bp_register_group_extension( 'Group_Extension_Example_2' );

endif;

 

Updated Recommendations for BuddyPress 2.6

Please note: Before BuddyPress 2.6, we recommended checking that the `BP_Group_Extension` class existed before calling it. BP 2.6 introduces class autoloading, so the `BP_Group_Extension` class could be autoloaded even if the groups component isn’t active, which causes problems. For this reason, we now recommend that extensions of the `BP_Group_Extension` class be wrapped in an `if ( bp_is_active( ‘groups’ ) )` conditional.

Contents

Article Contributors

30
Boone Gorges
4
David Cavins
4
Hugo Ashmore

Updated 8 months ago / Published 11 years ago

Want to help?

The BuddyPress Codex is volunteer-powered, which means you can contribute too! If you're interested in updating existing articles or creating entirely new ones, please read our Codex Standards & Guidelines.

Skip to toolbar