One of the things I’m starting to add to my plugins and themes is custom contextual help text for my settings pages. This is also something I’d love to see more plugin and theme developers start adding to their projects.

There’s a few great benefits to adding contextual help text:

• Provides quick documentation to your users.
• Helps cut back on support questions.
• Gives you an opportunity to link directly to the full documentation or support forums.

What is contextual help text?

If you open any screen in the WordPress admin, you should notice a tab near the top of the page labeled “Help” as shown in the following screenshot.

After clicking the tab, a new panel slides open that offers additional information. Most screens in the WordPress admin provide useful information to the users about what actions they can perform depending on which screen they are viewing.

However, for custom admin pages (such as those found in plugins and themes), WordPress doesn’t know what to show. So, it just adds a link to the WordPress documentation and support forums. That’s not user friendly.

This tutorial will walk you through the steps of adding custom help text for your plugin and theme admin pages.

Adding contextual help text

This will only take a few lines of code in your plugin file or theme’s functions.php file. The biggest thing to keep in mind is that this is contextual text. This means that the text changes depending on what admin screen is currently being viewed by the user. Therefore, you need to make sure you’re only adding text shown for your plugin/theme.

For this, you’ll use the add_contextual_help() function, which takes in two parameters: $screen (the current admin screen) and $text (the help text to show for the screen).

add_contextual_help( $screen, $text );

The following is a sample code snippet that shows how this works.

add_action( 'admin_menu', 'my_admin_setup' );

function my_admin_setup() {

	/* Custom help message. */
	$text = '<p>' . __( 'This is an example of contextual help in WordPress, you could edit this to put information about your plugin or theme so that users will understand what the heck is going on.', 'example-textdomain' ) . '</p>';

	/* Add documentation and support forum links. */
	$text .= '<p><strong>' . __( 'For more information:', 'example-textdomain' ) . '</strong></p>';

	$text .= '<ul>';
	$text .= '<li><a href="http://yoursite.com/theme-documentation">' . __( 'Documentation', 'example-textdomain' ) . '</a></li>';
	$text .= '<li><a href="http://yoursite.com/support">' . __( 'Support Forums', 'example-textdomain' ) . '</a></li>';
	$text .= '</ul>';

	add_contextual_help( 'appearance_page_theme-settings', $text );
}

appearance_page_theme-settings is the screen name for a theme settings page. Figuring out the correct screen name for your plugin/theme is described later in this tutorial.

Thanks to Andrew Nacin for reminding about this method.

Filtering the contextual help text

Another method to adding contextual help text is filtering the contextual_help hook. The following is an example code snippet demonstrating how to add a filter to this hook.

You’ll use the $screen variable to check if the current screen is your plugin or theme’s admin screen. If you’re not sure what the name of your admin screen is, see the next section of this tutorial.

/* Add your filter to the 'contextual_help' hook. */
add_filter( 'contextual_help', 'my_admin_contextual_help', 10, 2 );

function my_admin_contextual_help( $text, $screen ) {

	/* Check that we're on our theme/plugin settings screen. */
	if ( 'appearance_page_theme-settings' == $screen ) {

		/* Custom help message. */
		$text = '<p>' . __( 'This is an example of contextual help in WordPress, you could edit this to put information about your plugin or theme so that users will understand what the heck is going on.', 'example-textdomain' ) . '</p>';

		/* Add documentation and support forum links. */
		$text .= '<p><strong>' . __( 'For more information:', 'example-textdomain' ) . '</strong></p>';

		$text .= '<ul>';
		$text .= '<li><a href="http://yoursite.com/theme-documentation">' . __( 'Documentation', 'example-textdomain' ) . '</a></li>';
		$text .= '<li><a href="http://yoursite.com/support">' . __( 'Support Forums', 'example-textdomain' ) . '</a></li>';
		$text .= '</ul>';
	}

	/* Always return the help tab text. */
	return $text;
}

Note this line of code from the sample code:

if ( 'appearance_page_theme-settings' == $screen ) {

appearance_page_theme-settings is the screen name for a theme settings page. It will change for each custom admin page you add.

How to find the admin screen name

There are several functions for adding administration pages in the WordPress admin. I’ll assume you’re already familiar with the WordPress documentation on administration menus. Each of these functions returns the name of the page added for your plugin/theme.

Suppose you were adding a page under the Appearance menu in the admin. You’d use the add_theme_page() function as shown in the following code.

$my_theme_page = add_theme_page(
	__( 'Theme Settings', 'example-textdomain' ),
	__( 'Theme Settings', 'example-textdomain' ),
	'edit_theme_options',
	'theme-settings',
	'my_settings_page_callback'
);

The return value of add_theme_page() is the name of the page added. So, $my_theme_page will be appearance_page_theme-settings.

Your final code for adding contextual help text might look something like the following.

add_action( 'admin_menu', 'my_admin_setup' );

function my_admin_setup() {

	$my_theme_page = add_theme_page(
		__( 'Theme Settings', 'example-textdomain' ),
		__( 'Theme Settings', 'example-textdomain' ),
		'edit_theme_options',
		'theme-settings',
		'my_settings_page_callback'
	);

	if ( $my_theme_page )
		add_contextual_help( $my_theme_page, '<p>Some custom help text.</p>' );
}

I want to see some help text

Now that I’ve taken some time to write out this tutorial, it’s your turn. If your plugin or theme creates custom admin pages, I want to see some custom help text when I click the “Help” tab.

I hope you enjoyed the tutorial and can use it in your plugins and themes.