Skip to:
Content
Pages
Categories
Search
Top
Bottom

Group Extension API

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 http://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'.
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.
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.
    • enabledtrue 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'.
    • enabledtrue 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.)
    • enabledtrue 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.

 

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 class_exists() check is recommended, to prevent problems during upgrade
     * or when the Groups component is disabled
     */
    if ( class_exists( 'BP_Group_Extension' ) ) :
    
    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() {
    		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 ) {
    		$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 ) {
    		$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 ( class_exists( 'BP_Group_Extension' ) )
    
  2. /**
     * The class_exists() check is recommended, to prevent problems during upgrade
     * or when the Groups component is disabled
     */
    if ( class_exists( 'BP_Group_Extension' ) ) :
     
    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() {
    		echo 'This plugin is 2x cooler!';
    	}
    
    	function settings_screen( $group_id ) {
    		$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 ) {
    		$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 ) {
    		$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;