WordPress action hook contextual_help

iStock_000001952705XSmall

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!

Comments

  1. i love the idea. But i encounter a problem when i try to use your snipet

    i got this error code :Warning: Missing argument 2 for my_admin_help() in C:xampphtdocsmyblogwp.comwp-contentpluginsbakaautoblogcoreadminlayout.php on line 31

    i believe there’s problem on $screen variabel. i had make it global variabel but it still send error.

    by the way, right now i use wpmu Version 2.8.6 as development environtment. i use it using xampp on my localhost. i use your snippet as part of a plugin. i believe where and what version or what kind of wordpress i use is not the main problem. I hope you can help me.

    • Hi,

      Without seeing all your code it’s difficult to say what the problem may be. You don’t need to make either $screen or $text global because they are the arguments passed to your function by the add_action filter. Without the filter, nothing will work. The code in the article will work in WPMU 2.8.6.

    • I figured out that in the add_action function you need to specify the number of arguments the action function takes, which is 2 in this case.

      I changed it to: add_action( ‘contextual_help’, ‘my_function’ ,10,2);

      I also change the $text variable in the actual function to $contextual_help. Not sure if that is related though.

      Flor

  2. I love this concept. Would be really useful when developing themes for clients’ sites.

    Can you offer any links to where I can learn more about how and where page hooks are defined?

    • Hi Philip,

      I’ll write up an article on it in the next day or two.

      Here’s some info to get you going in the meantime…

      Normally you will add your Theme Options page like this (simplified for posting here):

      add_action('admin_menu', 'add_my_theme_options_page');
      function add_my_theme_options_page() {
      	$page_hook = add_submenu_page(args, etc etc);
      }

      The variable $page_hook is what you want. Of course, you will need to be careful with variable scope to make sure you can access this elsewhere.

      A quick way to find your page hook is to look at the Page Source of your Theme Options page – you will see it in the HEAD section.

      • Muzietto says:

        Hello, and thank you for the useful page.
        I didn’t find any follow-up post about page hooks,so I am asking if you could give me some detail.
        If I look in the HEAD of my page I don’t see any reference to page hooks. But there is a line inside a small JS snippet that reads:
        var pagenow = 'toplevel_page_MoxiemailManagementWidget'
        MMWidget is the plugin I am developing.
        Is this the $page_hook?
        I’m using WP 3.3 and I am in the admin section.
        Thanks in advance, Marco

Leave a Comment

*


six − = 1

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>