How to Register a Plugin Settings Screen in Multiple Locations

There are many, many ways to register your plugin settings for the WordPress admin. Between the default Settings options, Tools menu, and the Users menu… how does one decide where to place the plugin’s settings?

First, let’s identify the main organizational issue: your plugin’s functionality fits in multiple categories.

Is it a setting? Is it a tool? Both, perhaps? In this tutorial, I will show you the best of both worlds; it can be both.

Find a permanent home to register your settings

Suppose a user is searching for your settings in multiple sub-menus. Where are they most likely to look for regarding your plugin? Chances are, the user will look under the Settings menu item.

However, your plugin is more of a tool, so it should go under the Tools menu, correct?

Let’s set up a plugin that will live under the Tools menu, but have a shortcut under the Settings menu also.

Let’s start with the plugin header

I’m creating a one-file plugin, but I’ll still need to register the plugin’s headers.

<?php
/**
 * Plugin Name:       Fancy Tools: Multiple Admin Menu Locations
 * Plugin URI:        https://dlxplugins.com
 * Description:       A demo plugin showing how to register a menu in multiple locations.
 * Version:           1.0.0
 * Requires at least: 6.0
 * Requires PHP:      7.3
 * Author:            DLX Plugins
 * Author URI:        https://dlxplugins.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 *
 * @package DLXPlugins\FancyTools
 */

namespace DLXPlugins\FancyTools;Code language: PHP (php)

Registering the main admin screen

Up next is initializing our admin screen, which will live under the Tools menu.

/**
 * Initialize the admin panel.
 */
add_action( 'admin_menu', __NAMESPACE__ . '\add_admin_menu' );

/**
 * Add the admin menu.
 */
function add_admin_menu() {
	add_management_page(
		'Fancy Tools',
		'Fancy Tools',
		'manage_options',
		'fancy-plugin',
		__NAMESPACE__ . '\output_admin_page',
		10
	);
}

/**
 * Output the admin page.
 */
function output_admin_page() {
	?>
	<div class="wrap">
		<h1>Fancy Tools</h1>
		<p>Here is some fancy content.</p>
	</div>
	<?php
}Code language: PHP (php)

Making use of the admin_menu callback, I use WordPress function add_management_page to create my settings under Tools.

Finally, a very basic admin is output.

Pin itShare

Since we know the admin setting’s home, let’s just finalize that in a PHP constant:

Pin itShare

Adding a second menu location

Let’s modify our add_admin_menu callback and add a second location for our settings menu. We’re going to add to the Settings menu item, or the main options menu.

/**
 * Add the admin menu.
 */
function add_admin_menu() {
	add_management_page(
		'Fancy Tools',
		'Fancy Tools',
		'manage_options',
		'fancy-plugin',
		__NAMESPACE__ . '\output_admin_page',
		10
	);
	$hook = add_options_page(
		'Fancy Tools',
		'Fancy Tools',
		'manage_options',
		'fancy-plugin',
		'__return_empty_string',
		10
	);
	define( 'FANCY_TOOLS_OPTIONS_HOOK', $hook );
}
Code language: PHP (php)

The highlighted row is where we use add_options_page to register our settings menu item. You’ll notice that I’m assigning the result of add_options_page to a $hook variable. This is so we can match the current screen with the hook later (more on this in a minute).

The function __return_empty_string is used here for the function callback since we don’t actually want to output an admin page.

After the $hook variable is set, it is assigned to a constant, and we can then use that constant further down when the redirect needs to occur.

Adding the redirect to the main Tools screen

Armed with a hook, we can now hook into the current_screen action and do a redirect if anybody tries to visit our admin panel under Settings.

// Add a redirect to the admin settings.
add_action( 'current_screen', __NAMESPACE__ . '\maybe_redirect_to_settings', 10 );

/**
 * Redirect to settings if someone tries to access the options menu.
 */
function maybe_redirect_to_settings() {
	if ( ! is_admin() ) {
		return;
	}
	$screen = get_current_screen();

	if ( defined( 'FANCY_TOOLS_OPTIONS_HOOK' ) && FANCY_TOOLS_OPTIONS_HOOK === $screen->id ) {
		wp_safe_redirect( esc_url_raw( FANCY_TOOLS_ADMIN_URL ) );
		exit;
	}
}Code language: PHP (php)

We’re first checking if we’re not in the admin, otherwise bail. If the current screen matches our options hook, then someone is trying to access the menu under Settings. If all is well, a redirect to the correct admin page is completed.

Pin itShare

Full code

Here is the full code for this example:

<?php
/**
 * Plugin Name:       Fancy Tools: Multiple Admin Menu Locations
 * Plugin URI:        https://dlxplugins.com
 * Description:       A demo plugin showing how to register a menu in multiple locations.
 * Version:           1.0.0
 * Requires at least: 6.0
 * Requires PHP:      7.3
 * Author:            DLX Plugins
 * Author URI:        https://dlxplugins.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 *
 * @package DLXPlugins\FancyTools
 */

namespace DLXPlugins\FancyTools;

define( 'FANCY_TOOLS_ADMIN_URL', admin_url( 'tools.php?page=fancy-plugin' ) );

/**
 * Initialize the admin panel.
 */
add_action( 'admin_menu', __NAMESPACE__ . '\add_admin_menu' );

/**
 * Add the admin menu.
 */
function add_admin_menu() {
	add_management_page(
		'Fancy Tools',
		'Fancy Tools',
		'manage_options',
		'fancy-plugin',
		__NAMESPACE__ . '\output_admin_page',
		10
	);
	$hook = add_options_page(
		'Fancy Tools',
		'Fancy Tools',
		'manage_options',
		'fancy-plugin',
		'__return_empty_string',
		10
	);
	define( 'FANCY_TOOLS_OPTIONS_HOOK', $hook );
}

/**
 * Output the admin page.
 */
function output_admin_page() {
	?>
	<div class="wrap">
		<h1>Fancy Tools</h1>
		<p>Here is some fancy content.</p>
	</div>
	<?php
}

// Add a redirect to the admin settings.
add_action( 'current_screen', __NAMESPACE__ . '\maybe_redirect_to_settings', 10 );

/**
 * Redirect to settings if someone tries to access the options menu.
 */
function maybe_redirect_to_settings() {
	if ( ! is_admin() ) {
		return;
	}
	$screen = get_current_screen();

	if ( defined( 'FANCY_TOOLS_OPTIONS_HOOK' ) && FANCY_TOOLS_OPTIONS_HOOK === $screen->id ) {
		wp_safe_redirect( esc_url_raw( FANCY_TOOLS_ADMIN_URL ) );
		exit;
	}
}Code language: PHP (php)

Conclusion

In this tutorial, I demonstrated that you can truly be in two places at once, at least in regards to the admin settings.

If you have any questions, please leave a comment and I’ll be sure to respond.

Like this tutorial? There's more like it. Subscribe today!

Name(Required)

First Last

Email(Required)

Δ

Published On: on October 21, 2023

Ronald Huereca founded DLX Plugins in 2022 with the goal of providing deluxe plugins available for download. Find out more about DLX Plugins, check out some tutorials, and check out our plugins.