Help and screen API changes in 3.3

WordPress 3.3 introduces a new API for working with administration screen help content. add_contextual_help( $screen, $content ) is deprecated.

There are now tabs inside the help tab:

The way to add these are to attach a function to an existing hook such as the load-{$pagenow} hook, then using the add_help_tab() method of the current screen object.

For example:

add_action( 'admin_menu', 'nacin_add_special_theme_page' );
function nacin_add_special_theme_page() {
    $theme_page = add_theme_page( ... );
    if ( $theme_page )
        add_action( 'load-' . $theme_page, 'nacin_add_help_tabs_to_theme_page' );
function nacin_add_help_tabs_to_theme_page() {
    $screen = get_current_screen();
    $screen->add_help_tab( array(
        'id'      => 'additional-plugin-help', // This should be unique for the screen.
        'title'   => 'Special Instructions',
        'content' => '<p>This is the content for the tab.</p>',
        // Use 'callback' instead of 'content' for a function callback that renders the tab content.
    ) );

If you want to add a tab to an existing core screen, you’ll probably want to use the admin_head-{$pagenow} instead (to add them to the bottom), since core help tabs are not added until after load-{$pagenow}.

Help Sidebars

You can set the content of the right sidebar using $screen->set_help_sidebar( $content ) on the same hook where you used $screen->add_help_tab().

Removing Help Tabs

You can use $screen->remove_help_tab( $id ). Additionally, $screen->remove_help_tabs() will remove all tabs for a page.

Using the new WP_Screen object to adapt to screen contexts

The get_current_screen() function returns an object that includes the screen’s ID, base, post type, and taxonomy, among other data points. While get_current_screen() (and $current_screen, though the use of the global isn’t necessary) existed since 3.0, it now contains more accurate screen context (and the methods we covered above).

You can use $screen->id, $screen->base, etc., to ascertain which page you are on. This is helpful as seen above, to make sure that the help tab is only added to edit-tags.php if the taxonomy is post_tag. Of course, this is also helpful on the admin_enqueue_scripts hook (to figure out which scripts or styles to enqueue on a page) as it provides more context than a simple $pagenow or $hook_suffix.

More about what IDs and bases look like:

  • For edit.php (list for posts, pages, and post types), the ID is ‘edit-{$post_type}’ and the base is ‘edit’. The $post_type value is additionally set.
  • For post.php and post-new.php, the ID is {$post_type} and the base is ‘post’. For post-new.php, $screen->action is ‘add’.
  • For edit-tags.php, the ID is ‘edit-{$taxonomy}’ and the base is ‘edit-tags’. The $taxonomy and $post_type values are additionally set.
  • For all other core pages, the ID and base are generally the same and equivalent to the $pagenow value (minus ‘.php’).
  • For plugin pages, the ID is the value returned by add_menu_page(), add_submenu_page(), or the like, or get_plugin_page_hookname().

Note on add_contextual_help() and the contextual_help and contextual_help_list filters

The function and these filters continue to work, but their use is deprecated, and they are not ideal for use. They only work on a single chunk of text, rather than multiple tabs. So if the function is called or if the filters return any data, a separate ‘Overview’ tab will be added for compatibility sake.

#3-3, #dev-notes