Group Extension API (legacy)

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.

Archived file. Good only up to BP 1.7 version

Note: This guide is for use with versions of BuddyPress older than 1.8. In BP 1.8, the group extension API was rewritten. Plugins written as described below should continue to work, but for new projects you are highly encouraged to use the 1.8+ methods described on the main Group Extension API Codex page.

The group extension API (1.1+) 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.

Note: The admin_screen() and admin_screen_save() methods are new in BuddyPress 1.7. On earlier versions of BP, they won’t do anything.

The API Syntax

A group extension could be created as a standalone plugin file, or included as code within a plugin that performs other tasks. The core API code is as follows:

if ( bp_is_active( 'groups' ) ) : // Recommended, to prevent problems during upgrade or when Groups are disabled

	class My_Group_Extension extends BP_Group_Extension {

		function __construct() {
			$this->name = 'My Group Extension';
			$this->slug = 'my-group-extension';

			$this->create_step_position = 21;
			$this->nav_item_position = 31;
		}

		/**
		 * The content of the My Group Extension tab of the group creation process
		 *
		 * Don't need a group creation step? In the __construct() method:
		 *
		 *     $this->enable_create_step = false;
		 */
		function create_screen() {
			if ( !bp_is_group_creation_step( $this->slug ) )
				return false;

			/**
			 * If your extension's Create step shares much of its code with
			 * its Edit step, you might consider putting shared markup into
			 * a separate method (such as edit_create_markup()), and then
			 * call the method here:
			 *
			 *     $this->edit_create_markup();
			 */
			?>

			<p>The HTML for my creation step goes here.</p>

			<?php
			wp_nonce_field( 'groups_create_save_' . $this->slug );
		}

		/**
		 * The routine run after the user clicks Continue from your creation step
		 *
		 * You'll be pulling your data out of the $_POST global. Be sure to
		 * sanitize as necessary.
		 */
		function create_screen_save() {
			global $bp;

			check_admin_referer( 'groups_create_save_' . $this->slug );

			/* Save any details submitted here */
			groups_update_groupmeta( $bp->groups->new_group_id, 'my_meta_name', 'value' );
		}

		/**
		 * The content of the My Group Extension tab of the group admin
		 */
		function edit_screen() {
			if ( !bp_is_group_admin_screen( $this->slug ) )
				return false; ?>

			<h2><?php echo esc_attr( $this->name ) ?></h2>

			<p>Edit steps here</p>
			<input type="submit" name="save" value="Save" />

			<?php
			wp_nonce_field( 'groups_edit_save_' . $this->slug );
		}

		/**
		 * The routine run after the user clicks Save from your admin tab
		 *
		 * You'll be pulling your data out of the $_POST global. Be sure to
		 * sanitize as necessary.
		 */
		function edit_screen_save() {
			global $bp;

			if ( !isset( $_POST['save'] ) )
				return false;

			check_admin_referer( 'groups_edit_save_' . $this->slug );

			/* Insert your edit screen save code here */

			/* To post an error/success message to the screen, use the following */
			if ( !$success )
				bp_core_add_message( __( 'There was an error saving, please try again', 'buddypress' ), 'error' );
			else
				bp_core_add_message( __( 'Settings saved successfully', 'buddypress' ) );

			bp_core_redirect( bp_get_group_permalink( $bp->groups->current_group ) . '/admin/' . $this->slug );
		}

		/**
		 * Use this function to display the actual content of your group extension when the nav item is selected
		 */
		function display() {
			?>

			<p>Welcome to my cool group extension!</p>

			<?php
		}

		/**
		 * If your group extension requires a meta box in the Dashboard group admin,
		 * use this method to display the content of the metabox
		 *
		 * As in the case of create_screen() and edit_screen(), it may be helpful
		 * to abstract shared markup into a separate method.
		 *
		 * This is an optional method. If you don't need/want a metabox on the group
		 * admin panel, don't define this method in your class.
		 *
		 * @param int $group_id The numeric ID of the group being edited. Use
		 *   this id to pull up any relevant metadata
		 */
		function admin_screen( $group_id ) {
			?>

			<p>The HTML for my admin panel.</p>

			<?php
		}

		/**
		 * The routine run after the group is saved on the Dashboard group admin screen
		 *
		 * @param int $group_id The numeric ID of the group being edited. Use
		 *   this id to pull up any relevant metadata
		 */
		function admin_screen_save( $group_id ) {
			// Grab your data out of the $_POST global and save as necessary
		}

		function widget_display() { ?>
			<div class="info-group">
				<h4><?php echo esc_attr( $this->name ) ?></h4>
				<p>
					You could display a small snippet of information from your group extension here. It will show on the group
					home screen.
				</p>
			</div>
			<?php
		}
	}

	bp_register_group_extension( 'My_Group_Extension' );

endif; // class_exists( 'BP_Group_Extension' )

Optional Parameters

There are some optional parameters you can set in your group extension. These all go above the constructor (the __construct() function in the example above).

var $visibility = 'public'; // 'public' will show your extension to non-group members, 'private' means you have to be a member of the group to view your extension.

var $enable_create_step = true; // If your extension does not need a creation step, set this to false
var $enable_nav_item = true; // If your extension does not need a navigation item, set this to false
var $enable_edit_item = true; // If your extension does not need an edit screen, set this to false
var $enable_admin_item = true; // If your extension does not need an admin metabox, set this to false

var $admin_metabox_context = 'core'; // The context of your admin metabox. See add_meta_box()
var $admin_metabox_priority = 'normal'; // The priority of your admin metabox. See add_meta_box()

Advanced Usage

There may be circumstances where your group extension will need a navigation item, but sometimes not. Usually it is not quite as cut and try as “true” or “false”. In these cases you can could add and extra method to the extension that will dynamically change these options on a group by group basis.

/* Place this in the constructor */
$this->enable_nav_item = $this->enable_nav_item();

/* Add this method the end of your extension class */
function enable_nav_item() {
	global $bp;

	/* You might want to check some groupmeta for this group, before determining whether to enable the nav item */
	if ( groups_get_groupmeta( $bp->groups->current_group->id, 'settings_complete' ) )
		return true;
	else
		return false;
}