Help and screen API changes in 3.3

WordPress 3.3 introduces a new APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. 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 taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format., 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party 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