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
- Adding your field to bp_main settings section
- Adding a new settings section
- Additionnal resources
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
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 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
