Create Tabbed Settings Pages for WordPress Plugins

Whenever you are creating a plugin that has a lot of settings, it can be hard for the user to use a settings page with tons of options. It may make sense to group your settings into different sections so the user can find what they’re looking for easily. If you create tabbed settings pages for WordPress plugins, you can improve your user’s experience with your plugin.

Create Tabbed Settings Pages for WordPress Plugins

First, we will want to create the page for our settings. In this example, we are going to add the link to our page under the WordPress Settings menu. You can use other functions to put the page elsewhere, but that’s not really important for this tutorial.

function sd_admin_settings_setup() {
	add_options_page('My Plugin Settings', 'My Plugin Settings', 'manage_options', 'sd-settings', 'sd_admin_settings_page');
}
add_action('admin_menu', 'sd_admin_settings_setup');

There are a few parameters in the add_options_page you should be aware of:

• The first instance of ‘My Plugin Settings‘ is the text that will appear in the title tags of the page when you are on the page.
• The second instance of ‘My Plugin Settings‘ is the title that will be displayed in the menu. For demonstration purposes these are the same but they don’t have to be.
• manage_options is the capability a user must have in order to view this page. Manage options is for Administrators, but you can open the settings up to other users if needed by changing the capability.
• sd-settings is part of the URL (slug) to this settings page. You can change this to whatever you want it to be. For example, http://example.com/wp-admin/options-general.php?page=sd-settings
• sd_admin_settings_page is the name of the function that will display the output content for this page.
• The add_action calls the function that contains the add_options_page function.

Next, we need to create the function that will display the output for this page.

<?php
function sd_admin_settings_page(){
	global $sd_active_tab;
	$sd_active_tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'welcome'; ?>
 
	<h2 class="nav-tab-wrapper">
	<?php
		do_action( 'sd_settings_tab' );
	?>
	</h2>
	<?php
		do_action( 'sd_settings_content' );
}

This function by itself doesn’t do much. However we have a few action hooks that allow us (and other developers) to add tabs to our settings page. The sd_settings_tab action hook will create our tabs, and the sd_settings_content will create the content for our tabs. We are also storing the active tab as a global variable so we can use it in other functions (coming up). We set the variable $sd_active_tab as the value of the “tab” we are on.

Now let’s add a tab to the settings page.

<?php
add_action( 'sd_settings_tab', 'sd_welcome_tab', 1 );
function sd_welcome_tab(){
	global $sd_active_tab; ?>
	<a class="nav-tab <?php echo $sd_active_tab == 'welcome' || '' ? 'nav-tab-active' : ''; ?>" href="<?php echo admin_url( 'options-general.php?page=sd-settings&tab=welcome' ); ?>"><?php _e( 'Welcome', 'sd' ); ?> </a>
	<?php
}

This function accesses the global variable we set earlier. If the active tab is the tab we’re working on, we want to give it a different class so it stands out as being active. In this case we want our “Welcome” tab to be the first one displayed so we are doing a few things special on this tab that we won’t do on subsequent tabs.

• In the add_action function we set the priority to 1 so it is displayed first.
  • Additional tabs can be ordered by incrementing this number for each additional tab (2, 3, 4, etc.). If no number is specified the function will default to 10.
• We want to check to see if the global variable is set to our welcome tab, or if it isn’t set at all. When users initially click on our settings page no “tab” variable will be set so we want this page to show regardless of whether or not a tab variable is present.

Next, we need to give our tab some content.

<?php
add_action( 'sd_settings_content', 'sd_welcome_render_options_page' );
 
function sd_welcome_render_options_page() {
	global $sd_active_tab;
	if ( '' || 'welcome' != $sd_active_tab )
		return;
	?>
 
	<h3><?php _e( 'Welcome', 'sd' ); ?></h3>
	<!-- Put your content here -->
	<?php
}

Again, similar to the previous tab function we are checking to see if our $sd_active_tab is set to welcome or if it isn’t even set at all. If either of those are not true (i.e. we’re on another tab), we don’t want to display anything. If either are true we’ll display the content for this tab.

If the order of the tabs doesn’t matter to you, they can be added with the following code:

<?php
add_action( 'sd_settings_tab', 'sd_another_tab' );
function sd_another_tab(){
	global $sd_active_tab; ?>
	<a class="nav-tab <?php echo $sd_active_tab == 'another-tab' ? 'nav-tab-active' : ''; ?>" href="<?php echo admin_url( 'options-general.php?page=sd-settings&tab=another-tab' ); ?>"><?php _e( 'Another Title', 'sd' ); ?> </a>
	<?php
}
 
add_action( 'sd_settings_content', 'sd_another_render_options_page' );
 
function sd_another_render_options_page() {
	global $sd_active_tab;
	if ( 'another-tab' != $sd_active_tab )
		return;
	?>
 
	<h3><?php _e( 'Another Tab Content', 'sd' ); ?></h3>
	<!-- Put your content here -->
	<?php
}