Note: Post has been updated for 3.3 beta 2
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.
add_action('admin_menu', 'sfc_admin_add_page');
function sfc_admin_add_page() {
global $sfc_options_page;
$sfc_options_page = add_options_page(__('Simple Facebook Connect', 'sfc'), __('Simple Facebook Connect', 'sfc'), 'manage_options', 'sfc', 'sfc_options_page');
add_action("load-$sfc_options_page", 'sfc_plugin_help');
}
This makes an options page, and then uses the assigned identifier for that page to hook the load-* action. This means that when our page is loaded, the sfc_plugin_help function will get called.
function sfc_plugin_help() {
global $sfc_options_page;
$screen = get_current_screen();
if ($screen->id != $sfc_options_page)
return;
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:
$screen->add_help_tab( array(
'id' => 'sfc-base',
'title' => __('Connecting to Facebook', 'sfc'),
'content' => "HTML for help content",
));
$screen->add_help_tab( array(
'id' => 'sfc-modules',
'title' => __('SFC Modules', 'sfc'),
'content' => "HTML for help content",
));
$screen->add_help_tab( array(
'id' => 'sfc-login',
'title' => __('Login and Register', 'sfc'),
'content' => "HTML for help content",
));
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.
