Wherever possible it's better to use screen-specific hooks rather than more generic init, admin_init, admin_footer etc. (unless you specifically want your callback to run on every screen). In this quick tip we'll look at how you can easily obtain the screen hooks for any particular page.
Page Specific Hooks
Page specific hooks offer the most efficient (and cleanest) way of targeting a callback for only the screen(s) you need it for. They include:
-
load-{page-hook}– called prior to the screen loading (the logic for this can be found here) -
admin_print_styles-{page-hook}– action for printing styles in the<head>of the admin page -
admin_print_scripts-{page-hook}– action for printing scripts in the<head>of the admin page -
admin_head-{page-hook}– action triggered inside the<head>of the admin page -
admin_footer-{page-hook}– action triggered just above the closing</body>tag on the admin page
But what is the value of {page-hook} for any particular page? Looking at the load-* hook in particular you'll find that there is a fairly convoluted logic in determining the {page-hook}. In particular, it treats custom plug-in pages differently from 'core' pages (such as post type and taxonomy pages), and for the sake of backwards compatibility, it will use multiple hooks for the same screen when editing posts, pages or categories.
The general rules for the value of {page-hook} can be summarised as follows:
- For custom admin pages added via
add_menu_page()(and related functions) it is the screen ID (the value returned byadd_menu_page()) - For the admin page listing posts of any post type, it is
edit.php - On the 'add new' page of any post type, it is
post-new.php - On the edit page of any post type, it is
post.php - For taxonomy pages it is
edit-tags.php
However the page hook is generated, it is ultimately stored in the global $hook_suffix.
Easily Get a Screen's Hooks
In general those rules suffice in determining the page specific hooks. But when working with them I often find it helps to have an easy reference. To create this easy reference we'll add a panel to the 'help' tab on the top right of every screen which will list the screen's details (screen ID, screen base, and most usefully, the screen's hook suffix). It will also list the screen's specific hooks.
Panels in the help tab were introduced in 3.3, so this will only work for WordPress versions 3.3+. To add the panel we use the contextual_help filter. This is a filter for backwards compatibility purposes, so we don't actually filter anything. Instead we use the WP_Screen::add_help_tab method.
/* Add contextual help */
add_filter( 'contextual_help', 'wptuts_screen_help', 10, 3 );
function wptuts_screen_help( $contextual_help, $screen_id, $screen ) {
// The add_help_tab function for screen was introduced in WordPress 3.3.
if ( ! method_exists( $screen, 'add_help_tab' ) )
return $contextual_help;
/* ... generate help content ... */
$help_content ='';
$screen->add_help_tab( array(
'id' => 'wptuts-screen-help',
'title' => 'Screen Information',
'content' => $help_content,
));
return $contextual_help;
}
To generate the help content, we take the global $hook_suffix and append it to the hook stems mentioned above. We also get a list of the screen's details, which are stored as properties of the WP_Screen object.
global $hook_suffix;
// List screen properties
$variables = '<ul style="width:50%;float:left;"><strong>Screen variables </strong>'
. sprintf( '<li> Screen id : %s</li>', $screen_id )
. sprintf( '<li> Screen base : %s</li>', $screen->base )
. sprintf( '<li>Parent base : %s</li>', $screen->parent_base )
. sprintf( '<li> Parent file : %s</li>', $screen->parent_file )
. sprintf( '<li> Hook suffix : %s</li>', $hook_suffix )
. '</ul>';
// Append global $hook_suffix to the hook stems
$hooks = array(
"load-$hook_suffix",
"admin_print_styles-$hook_suffix",
"admin_print_scripts-$hook_suffix",
"admin_head-$hook_suffix",
"admin_footer-$hook_suffix"
);
// If add_meta_boxes or add_meta_boxes_{screen_id} is used, list these too
if ( did_action( 'add_meta_boxes_' . $screen_id ) )
$hooks[] = 'add_meta_boxes_' . $screen_id;
if ( did_action( 'add_meta_boxes' ) )
$hooks[] = 'add_meta_boxes';
// Get List HTML for the hooks
$hooks = '<ul style="width:50%;float:left;"><strong>Hooks</strong> <li>' . implode( '</li><li>', $hooks ) . '</li></ul>';
// Combine $variables list with $hooks list.
$help_content = $variables . $hooks;
Which will give us something like the following:
The Code in Full
You can place the following in your site's utility plug-in, or (if you must), your theme's functions.php. Make sure you rename wptuts_screen_help to something unique to you.
add_action( 'contextual_help', 'wptuts_screen_help', 10, 3 );
function wptuts_screen_help( $contextual_help, $screen_id, $screen ) {
// The add_help_tab function for screen was introduced in WordPress 3.3.
if ( ! method_exists( $screen, 'add_help_tab' ) )
return $contextual_help;
global $hook_suffix;
// List screen properties
$variables = '<ul style="width:50%;float:left;"> <strong>Screen variables </strong>'
. sprintf( '<li> Screen id : %s</li>', $screen_id )
. sprintf( '<li> Screen base : %s</li>', $screen->base )
. sprintf( '<li>Parent base : %s</li>', $screen->parent_base )
. sprintf( '<li> Parent file : %s</li>', $screen->parent_file )
. sprintf( '<li> Hook suffix : %s</li>', $hook_suffix )
. '</ul>';
// Append global $hook_suffix to the hook stems
$hooks = array(
"load-$hook_suffix",
"admin_print_styles-$hook_suffix",
"admin_print_scripts-$hook_suffix",
"admin_head-$hook_suffix",
"admin_footer-$hook_suffix"
);
// If add_meta_boxes or add_meta_boxes_{screen_id} is used, list these too
if ( did_action( 'add_meta_boxes_' . $screen_id ) )
$hooks[] = 'add_meta_boxes_' . $screen_id;
if ( did_action( 'add_meta_boxes' ) )
$hooks[] = 'add_meta_boxes';
// Get List HTML for the hooks
$hooks = '<ul style="width:50%;float:left;"> <strong>Hooks </strong> <li>' . implode( '</li><li>', $hooks ) . '</li></ul>';
// Combine $variables list with $hooks list.
$help_content = $variables . $hooks;
// Add help panel
$screen->add_help_tab( array(
'id' => 'wptuts-screen-help',
'title' => 'Screen Information',
'content' => $help_content,
));
return $contextual_help;
}
Comments