WordPress action hook contextual_help

This WordPress hook is probably of more use to plugin developers than anyone else – though it could be a useful add-on in theme development, or as part of a backend modification for a CMS-type site – and gives a handy way to add content to the “Help” pulldown panel in the Dashboard.

This mini-tutorial explains how to use the contextual_help action hook to add your own customised help information to your plugin’s Settings page. More information on using this with Themes will be covered in a future article.

See it in action

Navigate to any Dashboard screen and you should see a Help tab in the top right-hand corner of your screen. Click it and you will see the “contextual help” for that screen.

Using it in a plugin

contextual_help is an action hook and, like any action hook, is added to the plugin like this:

// Let's hook my function to the contextual_help action
add_action( 'contextual_help', 'my_function' );

my_function is the name of your function that will output the content which will be displayed in the contextual help panel.

A few points to note:

• The function my_function should be defined with two arguments: $text and $screen.
• $text represents the default contextual help content relevant to the screen being viewed.
• $screen represents the screen being viewed, ie the “page hook” of that screen.
• The function my_function can either replace the default $text or add to it.
• The function my_function should include a check to ensure that the default $text is only modified or replaced on your own plugin’s Settings page – and not on every Admin screen!

Defining the function

Here’s a sample function to show how the hook works:

function my_admin_help($text, $screen) {
	
	// Check we're only on my Settings page
	if (strcmp($screen, MY_PAGEHOOK) == 0 ) {
		
		$text = 'Here is some very useful information to help you use this plugin...';
		return $text;
	}
	// Let the default WP Dashboard help stuff through on other Admin pages
	return $text;
}

• Line 4: This line checks that the current screen is my plugin’s Settings page, using strcmp() to compare $screen with the page hook of my Settings page. In this example I’m assuming that the plugin’s page hook has been defined as a PHP constant elsewhere in the plugin file.
• Line 6: This is the content that will replace the default contextual help for my plugin page.
• Line 10: If we’re not on my plugin’s Settings page, we just return the original $text argument untouched by our function, so that the defaults will be displayed on all other Admin pages.

Hope you found this useful. Have fun!