WordPress 3.0 action hook contextual_help

Development of WordPress 3.0 is in full swing and, knowing that there will be quite a few significant changes to the code base with the merge of WP and WPMU, I’m keeping a close eye on the nightly builds to make sure that my Dynamic Content Gallery plugin keeps up to date with these changes.

In doing this, I’ve discovered a significant change regarding the contextual_help filter hook, which I use in my plugin, and which I wrote about in WordPress action hook contextual_help a few weeks ago.

So, for the benefit of those who are using this hook in their plugins, here’s how to make your existing code compatible with WordPress 3.0.

New $screen object for WordPress 3.0

The contextual_help filter, is defined in wp-admin/includes/template.php as follows:

apply_filters('contextual_help', $contextual_help, $screen);

The significant change in WP 3.0 is that $screen is now an Object, not a String. This makes a lot of sense, as the previous way of handling location within the WP backend was a bit of a nightmare to decipher. Converting it to an Object allows more information to be stored in this one variable – which can be very handy for developers.

Here’s what the new $screen Object contains, this example being a var_dump() from the Dynamic Content Gallery plugin:

object(stdClass)#156 (4) {
	["id"]=>  string(37) "settings_page_dynamic_content_gallery" 
	["base"]=>  string(37) "settings_page_dynamic_content_gallery" 
	["parent_file"]=>  string(19) "options-general.php" 
	["parent_base"]=>  string(15) "options-general"
}

By itself, this change is relatively harmless and unlikely to cause issues in many cases. However, in the case of the Dynamic Content Gallery, this change caused the plugin to throw a fatal error. This is because in order to make sure that my plugin’s contextual help only appears on my plugin’s Settings page, I use strcmp() to compare the value of $screen to the plugin’s page hook – which will only work when $screen is a String. Fix coming up…

Updating the filter function

The filter hook is called in the same way it was before (nothing has changed here):

add_action( 'contextual_help', 'my_admin_help_function' );

However, my_admin_help_function needs tweaking to deal with $screen being an Object.

Old way (pre-version 3.0)

This is the way I described how to do it in the previous WordPress action hook contextual_help article – which will break in WP 3.0:

function my_admin_help_function($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;
}

New way (WordPress 3.0)

And here’s the updated code for compatibility with WordPress 3.0:

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

• Line 1: I always like to match the argument names with the WordPress filter arguments, therefore $text is changed to $contextual_help. This is simply a name change to keep my code consistent with the naming conventions used in WP and doesn’t have any wider significance.
• Line 4:This line checks that the current screen is my plugin’s Settings page, using strcmp(). Because $screen is now an Object, we need to access the String we want to compare by using $screen->base instead.

Next steps…

For theme developers out there, I will be following up with some code snippets to show how to use this code for adding contextual help to Theme Options pages. Watch this space…

Hope you found this useful. Have fun!