WordPress plugin and theme authors could get something interesting in WordPress 3.3: a somewhat more comprehensive help screen system.

This is actually just a small part of a more long term makeover involving unifying the admin screen code base, but it’s pretty cool nevertheless. Backward compatibility is sorta fuzzy on parts of it at the moment, but not a lot of authors used these functions previously anyway, from what I can tell.

Anyway, I spent an entertaining half hour reworking the help dropdown for my SFC plugin. Here’s what it looks like in 3.3-aortic-dissection right now (note that the look and feel of this will probably change before final):

SFC Help screen in WordPress 3.3

As you can see, the dropdown Help menu moved into the Admin bar (along with lots of other stuff), and has some tabs on the left hand side where you can make different topics and such for different parts of the plugin.

The code for this is actually fairly straightforward, albeit in a sideways sort of way…

First we have to look at the code that adds my options page in the first place. This would work with any of the add_*_page functions, so add_theme_page and such works fine too.

Here, we call get_current_screen() to get the current WP_Screen object. The WP_Screen object is new to 3.3, but essentially it encapsulates an admin screen. It’s still under active development, but in the long run, it may make the task of creating admin screens much, much easier.

Anyway, right away, I do one thing and that is to check if the ID of the current screen matches the ID I was given for my options page. If it doesn’t match, then the user isn’t on my screen, and so I return having done nothing at all. This is a sort of belt and suspenders approach, since we shouldn’t be here if load-$sfc_options_page didn’t get called, but it never hurts to be sure.

The next bit is where I add my help screens. Here’s an incomplete sample of that code:

I removed the content for each one to make it clearer. Essentially, I’m just calling the object’s add_help_tab function to add my new tabs to the help screen, one by one. Simple, right?

There’s other useful bits in WP_Screen too, such as adding screen options, adding a right hand side sidebar to the help dropdown, and so forth. I haven’t figured out a use for them yet, but they’re still nice to see.

If you have a complex plugin or theme, might be worth looking into this now. Might reduce your need for end-user support. Maybe. Hard to say. People rarely look at the documentation, but inline help might be worth a shot.

25 Comments

I noticed, while working on a plugin, that add_contextual_help was deprecated but didn’t make the switch because of backwards compatibility. How do you plan to handle this? I’m thinking of just leaving it as is until 3.3 has greater use (and is officially released :P).

The deprecation function call in those was commented out sometime recently, so I think they’re leaving full-conversion until 3.4 or later. So it probably won’t be deprecated in 3.3, just on the verge of deprecation.

I’m not big on backwards compatibility. People should upgrade things. So I plan on having the next major release of SFC just require 3.3. Easy.

Thanks for the example of using WP_Screen, but I can’t seem to find any reference to the ‘add_screen_help_and_options’ filter in svn head – nor can I get your method to work as a result. Retrieving the WP_Screen object with $screen = get_current_screen(); at the ‘admin_head’ stage does, however, work fine for me.

It will be very useful to add help for themes/Plugins this way. Also, it may (slightly?) increase the chances of users actually clicking on theme/Plugin page contextual help if you could optionally override the default ‘Help’ with something else, such as ‘My Plugin Help’ etc.

To define your help screen tabs you can use any action hook which has global $current_screen object already set and is activated before admin_head action. The one I’ve tried with success is admin_print_scripts.

[…] version of WordPress, adding help documentation for plugins is really improved and Otto gives a sneak peek at some reworked installation/connection instructions. He also adds a quick fix warning against setting the wrong type of encryption, and the tutorial […]

Where the ‘add_help_tab’ function calls the old ‘add_contextual_help’ function to get the appropriate content.

Still trying to figure out how to alter existing help though (without editing core files). As of WP 3.3 RC31, class WP_Screen can not be extended, and the existing help is stored in a private variable so you can’t access it directly to make changes using a plugin… Sometimes all you want to do is add a sentence to something, in which case adding another help tab is overkill.

[…] to the previous iteration, the WP 3.3 contextual help is actually quite simple to integrate. Otto Wood wrote a detailed tutorial here.All contextual help-related functionality is handled through the WP_Screen() class, so the first […]