Skip to:
Content
Pages
Categories
Search
Top
Bottom
Codex HomeBuddyPress Plugin Development → Adding Plugin’s Options to BuddyPress Settings Page

Adding Plugin’s Options to BuddyPress Settings Page

When writing your plugin you may need to give the community administrator the ability to set some options about it to eventually let him customize some behaviors. When you have a lot options, you would use the WordPress built in add_options_page() or add_submenu_page() functions to create your plugin’s settings page.

But, If your plugin only needs a very few options to be set by the community administrator, it can be interesting to use BuddyPress settings administration screen to add your own fields.

Sections

Choosing the best BuddyPress settings section

BuddyPress settings are divided into sections. Depending on your plugins features you can choose to include your setting in the best one. For instance, if your plugin is extending the Groups component, you can choose the ‘bp_groups’ section.

Available BuddyPress settings sections

Available BuddyPress settings sections

Adding your field to bp_main settings section

The following code illustrates how you could add your setting field to the ‘bp_main’ BuddyPress settings section.

/**
 * Your settings main function
 */
function bp_plugin_admin_settings() {

	add_settings_field(
		/* the option name you want to use for your plugin */
		'bp-plugin-option-name',

		/* The title for your setting */
		__( 'BP Plugin Setting', 'bp-plugin-domain' ),

		/* Display function */
		'bp_plugin_setting_field_callback',

		/* BuddyPress settings */
		'buddypress',

		/* BuddyPress setting section
		Here you are adding a field to 'bp_main' section.
		As shown on the image, other available sections are :
		- if xprofile component is active : 'bp_xprofile',
		- if groups component is active : 'bp_groups',
		- if legacy forums component is active : 'bp_forums',
		- if activity component is active : 'bp_activity'
		*/
		'bp_main'
	);

	/* This is where you add your setting to BuddyPress ones */
	register_setting(
		/* BuddyPress settings */
		'buddypress',

		/* the option name you want to use for your plugin */
		'bp-plugin-option-name',

		/* the validatation function you use before saving your option to the database */
		'bp_plugin_setting_field_validate'
	);

}

add_action( 'bp_register_admin_settings', 'bp_plugin_admin_settings' );

/**
 * This is the display function for your field
 */
function bp_plugin_setting_field_callback() {
	/* if you use bp_get_option(), then you are sure to get the option for the blog BuddyPress is activated on */
	$bp_plugin_option_value = bp_get_option( 'bp-plugin-option-name' );

	// you can use the checked() function to easily add a checked attribute to the checkbox if needed
	?>
	<input id="bp-plugin-option-name" name="bp-plugin-option-name" type="checkbox" value="1" <?php checked( $bp_plugin_option_value ); ?> />
	<label for="bp-plugin-option-name"><?php _e( 'BP Plugin option label', 'bp-plugin-domain' ); ?></label>
	<p class="description"><?php _e( 'BP Plugin option description', 'bp-plugin-domain' ); ?></p>
	<?php
}

/**
 * This is validation function for your field
 */
function bp_plugin_setting_field_validate( $option = 0 ) {
	/* you could directly use 'intval' as your the 3rd argument of the register_setting() function in this case..
	   For the purpose of this example, this specific function illustrates a custom validation function */
	return intval( $option );
}

This screenshot is illustrating the above code

Adding a field to bp_main section

Adding a field to bp_main section

Adding a new settings section

/**
 * Your setting main function
 */
function bp_plugin_admin_settings() {

	/* This is how you add a new section to BuddyPress settings */
	add_settings_section(
		/* the id of your new section */
		'bp_plugin_section',

		/* the title of your section */
		__( 'BP Plugin Settings',  'bp-plugin-domain' ),

		/* the display function for your section's description */
		'bp_plugin_setting_callback_section',

		/* BuddyPress settings */
		'buddypress'
	);

	/* This is how you add a new field to your plugin's section */
	add_settings_field(
		/* the option name you want to use for your plugin */
		'bp-plugin-option-name',

		/* The title for your setting */
		__( 'BP Plugin Setting', 'bp-plugin-domain' ),

		/* Display function */
		'bp_plugin_setting_field_callback',

		/* BuddyPress settings */
		'buddypress',

		/* Your plugin's section id */
		'bp_plugin_section'
	);

	/*
	   This is where you add your setting to BuddyPress ones
	   Here you are directly using intval as your validation function
	*/
	register_setting(
		/* BuddyPress settings */
		'buddypress',

		/* the option name you want to use for your plugin */
		'bp-plugin-option-name',

		/* the validatation function you use before saving your option to the database */
		'intval'
	);

}

/**
 * You need to hook bp_register_admin_settings to register your settings
 */
add_action( 'bp_register_admin_settings', 'bp_plugin_admin_settings' );

/**
 * This is the display function for your section's description
 */
function bp_plugin_setting_callback_section() {
	?>
	<p class="description"><?php _e( 'This is a descrition of BP Plugin section', 'bp-plugin-domain' );?></p>
	<?php
}

/**
 * This is the display function for your field
 */
function bp_plugin_setting_field_callback() {
	/* if you use bp_get_option(), then you are sure to get the option for the blog BuddyPress is activated on */
	$bp_plugin_option_value = bp_get_option( 'bp-plugin-option-name' );
	?>
	<input id="bp-plugin-option-name" name="bp-plugin-option-name" type="checkbox" value="1" <?php checked( $bp_plugin_option_value ); ?> />
	<label for="bp-plugin-option-name"><?php _e( 'BP Plugin option label', 'bp-plugin-domain' ); ?></label>
	<p class="description"><?php _e( 'BP Plugin option description', 'bp-plugin-domain' ); ?></p>
	<?php
}

Here is a screenhot of your custom section in BuddyPress settings.

A custom section for your plugin's option

A custom section for your plugin’s option

Additional resources

Skip to toolbar