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-settingssd_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 theadd_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 } |
Mark Rudder says
Minor typo:
“Whenever you are creating a plugin that a lot of settings,”
Scott DeLuzio says
Thanks for spotting that Mark!
It could have been worse…
Luhas says
Thank you Scott very much.
Finally easy solution I was looking for. 🙂
Have a great days.
Szycha says
Hey Scott, thanks for you tutorial.
But i have lite problem because I have use add_submenu_page and get error “Sorry, you are not allowed to access this page.”
it is possible to added in submenu_page ?
code :
add_action(‘admin_menu’, array($this, ‘admin_new_menu’));
function admin_new_menu()
{
add_submenu_page(
‘szycha_plugin’,
‘My Plugin Settings’,
‘Tabs’,
‘manage_options’,
‘sd-settings’,
array($this->tab_page,’sd_admin_settings_page’));
}
Scott DeLuzio says
You need to be logged in as an administrator to see the submenu page. To change that you will have to set the value
manage_options
to something from a role with a lower level. See this table for more information on the capabilities granted to each user role.Toon Langendam says
Hey Scott,
Very usefull tutorial. Only I have a little problem.
I use a form on my setting page and everytime I save the content it resets the other tabs. Do you have any links to blogs or tips for me to fix this issue. Because I can’t find any.