Advertisement
Tips

Quick Tip: Get the Current Screen's Hooks

by

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 by add_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;
}
Related Posts
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML - Creating a Page TemplateCreating wordpress theme from html 400
    So far in this series, I've shown you how to create a fully functioning WordPress theme from static HTML. We've covered the following steps: preparing your markup for WordPress converting your HTML to PHP and splitting your file into template files editing the stylesheet and uploading your theme to WordPress adding a loop to your index file adding meta tags, the wp_head hook and the site title and description to your header file adding a navigation menu adding widget areas to the header and sidebar adding widget areas, a colophon and the wp_footer hook to the footer file. At the moment, your theme only has one template file for displaying content—the index.php file. A powerful feature of WordPress is the ability to use template files for different kinds of content.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML - Adding WidgetsCreating wordpress theme from html 400
    In this series, you've learned how to convert a static HTML file to a WordPress theme and edit the header file. So far you've: prepared your markup for WordPress converted your HTML to PHP and split your file into template files edited the stylesheet and uploaded your theme to WordPress added a loop to your index file added meta tags, the wp_head hook and the site title and description to your header file added a navigation menu. Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML: Adding NavigationCreating wordpress theme from html 400
    If you've been working through this series, you now have a working theme with template files which you've uploaded to WordPress. In this tutorial, you'll continue to work on the header.php file that you created in Part 2. You'll learn how to add a navigation menu which can be edited via the WordPress Menus admin screen. To do this you'll also need to create a new file for your theme: the functions file.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: Creating Template FilesCreating wordpress theme from html 400
    In the first part of this series, I showed you how to prepare your HTML and CSS files for WordPress, ensuring the structure would work, the code was valid and that the correct classes were being used. In this tutorial you'll learn how to take your index.html file and split it up into a set of template files for use by WordPress.Read More…
  • Code
    Creative Coding
    Customizing the WordPress Admin: Help TextCustomize wordpress admin rachel 400
    In Part 2 of this tutorial, I showed you how to add custom metaboxes to the WordPress dashboard, which you can use to provide help text for your clients or users. But what if you want to provide help text on individual editing screens? In this tutorial, I'll show you how to do just that.Read More…
  • Code
    Creative Coding
    Utilizing Custom Fields to Create Review BoxesReview boxes thumb
    Reviews are perhaps one of the greatest powers of blogging in terms of authority. When done properly (with hard work and consistent information), review blogs are arguably the most profitable category in the blogosphere. But every blog has to offer a solid design in their posts, including reviews. In this post, we're going to talk about how to build the perfect review box, since review boxes are probably the first part readers check before reading a review.Read More…