Group Types

BuddyPress 2.6 introduced the concept of group types. This functionality is outlined below.

Registering group types

BuddyPress itself does not register any group types. Plugins and themes can register group types using the bp_groups_register_group_type() function:

function my_bp_custom_group_types() {
	bp_groups_register_group_type( 'team', array(
		'labels' => array(
			'name' => 'Teams',
			'singular_name' => 'Team'
		),

		// New parameters as of BP 2.7.
		'has_directory' => 'teams',
		'show_in_create_screen' => true,
		'show_in_list' => true,
		'description' => 'Teams are good',
		'create_screen_checked' => true
	) );
}
add_action( 'bp_groups_register_group_types', 'my_bp_custom_group_types' );

The first parameter of bp_groups_register_group_type() is a string identifier for the group type, used internally by BP as the canonical name of the type. This name should be unique. The second parameter is a list of generic config arguments (see Configuration Arguments section for full details).

Registering a group type will also enable a meta box so administrators can set a groups’s type when editing a group in the WP admin dashboard.

Configuration Arguments

'labels' (available as of BP 2.6)

An array consisting of the 'name' and 'singular_name' keys. 'name' is for the plural form of the group type.

'has_directory' (available as of BP 2.7)

If this argument is passed (eg. ‘ninja’), a list of members matching the group type will be available as a filter from the Groups Directory page. (eg. http://example.com/groups/type/ninja/. You can pass any string to customize the URL for the group type’s directory.) Default: false.

'show_in_create_screen' (available as of BP 2.7)

If set to true, the group type will be selectable during group creation and when a group administrator is on the group’s “Manage > Settings” page. Default: false.

'show_in_list' (available as of BP 2.7)

If set to true, the group type will be shown when the bp_group_type_list() function is used by default. Currently, the group type list is shown when on a group page. This defaults to true if 'show_in_create_screen' is set to true. Default: null.

'description' (available as of BP 2.7)

Used to describe the group type. If this is passed, this is currently shown on the group creation screen to describe the group type.

'create_screen_checked' (available as of BP 2.7)

If the 'show_in_create_screen' argument is set to true, this argument will toggle the checkbox for our group type so it is checked by default during the group creation process. This is handy if you wanted to imply that the group type should be enforced, but the decision ultimately lies with the group creator. Default: false.

Querying by group type

A common task is to retrieve a list of groups of a given type (or set of types). bp_has_groups() and BP_Groups_Group::get() accept a 'group_type' parameter, which can be a single group type or an array/comma-separated list of group types. This will filter query results to those groups matching the type. Example:

// Fetch all teams and companies.
$group_args = array(
    'group_type' => array( 'team', 'company' ),
);
if ( bp_has_groups( $group_args ) ) { // ...

Fetching and setting group types

When BuddyPress detects that group types have been registered, it will display a Group Type metabox when editing a group’s page in Dashboard > Groups. Administrators can use this interface to view or change a groups’s type.

BuddyPress also provides simple functions for fetching and setting group types programatically. To get the group type of a group, use bp_groups_get_group_type():

// Get the group type of group 5412.
$group_type = bp_groups_get_group_type( 5412 );

Set a group’s type using bp_groups_set_group_type():

// Set the group type of group 5412 to 'team'.
$group_type = bp_groups_set_group_type( 5412, 'team' );