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.

In this tutorial you'll learn how to:

1. Add a metabox to the editing screen for help text
2. Add additional metaboxes in different positions
3. Create a dummy metabox to display help text at the top of the editing screen

I'm going to create a plugin to do this - if you've already created a plugin after following Parts 1 to 3 of this series you may prefer to add the code from this tutorial to that plugin, giving you one plugin with all of your admin customizations.

What You Will Need to Complete This Tutorial

To complete this tutorial you will need:

• A WordPress installation
• Access to your site's plugins folder to add your plugin
• A text editor to create your plugin

Setting Up the Plugin

At the beginning of my plugin, I'm adding the following lines:

/*
Plugin Name: Wptuts+ Customize the Admin Part 4 - Help Text
Plugin URI: http://rachelmccollin.co.uk
Description: This plugin supports the tutorial in Wptuts+. It adds help text to the WordPress editing screen.
Version: 1.0
Author: Rachel McCollin
Author URI: http://rachelmccollin.com
License: GPLv2
*/

1. Adding a Help Metabox to the Post Editing Screen

To add a metabox containing help text, you use the add_meta_box() function, which you would also use if you were creating a metabox for post metadata or in a settings screen. This function takes a few parameters:

<?php add_meta_box( $id, $title, $callback, $post_type, $context, $priority, $callback_args ); ?>

The parameters are:

• $id - the unique ID for the metabox.
• $title - the title which will be displayed to users.
• $callback - the callback function defining the contents of the metabox.
• $post_type - the post type whose editing screen the metabox will appear in. Leave this blank to add the metaboxes to all post type editing screens, or specify which post type you want to target.
• $context - where in the editing screen you want the metabox to appear - 'normal', 'advanced' or 'side'. The default is 'advanced' which places the metabox in the main area of the screen.
• $priority - within the context you've defined, the priority for this metabox ('high', 'core', 'default' or 'low'). This is useful if you're adding multiple metaboxes.
• $callback_args - arguments to pass into your callback function (optional)

So, to add a metabox to the main area of the post editing screen for posts only, I add the following to my plugin:

// Add metabox below editing pane
function wptutsplus_metabox_after_title() {
	add_meta_box( 'after-title-help', 'Using this Screen', 'wptutsplus_after_title_help_metabox_content', 'post', 'advanced', 'high' );
}
add_action( 'add_meta_boxes', 'wptutsplus_metabox_after_title' );

This adds an empty metabox, which won't work yet because I haven't added the callback function. This is as follows:

// callback function to populate metabox
function wptutsplus_after_title_help_metabox_content() { ?>
	<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>
<?php }

This now adds a metabox to my post editing screen, as shown in the screenshot:

As you can see, I've removed some of the other metaboxes normally seen in the post editing screen (such as excerpts and discussion), but my new metabox is below the editing pane and therefore not very visible. It's impossible to use the add_meta_box() function to add a metabox above the main editing pane without resorting to a jQuery solution which moves the main editing pane down, and which I think is overkill for this problem. So what alternatives do I have?

1. Firstly, I can add a metabox above the 'Publish' metabox, which will be more obvious to users.
2. Alternatively, I can cheat, and use the edit_form_after_title action hook to add a fake metabox above the editing pane.

I'll start with the first option: adding a metabox on the right above the 'Publish' metabox.

2. Adding a Metabox on the Right of the Editing Screen

To add a metabox at the top right of the screen I use the add_meta_box() function in the same way as before, with some of the parameters changed. I'll also use a different callback function to populate the metabox with different content.

In your plugin, add the following:

// Add help text to right of screen in a metabox
function wptutsplus_metabox_top_right() {
	add_meta_box( 'after-title-help', 'Publishing and Saving Changes', 'wptutsplus_top_right_help_metabox_content', 'post', 'side', 'high' );
}
// callback function to populate metabox
function wptutsplus_top_right_help_metabox_content() { ?>
	<p>Make sure you click 'Publish' below to publish a new article once you've added it, or 'Update' to save any changes.</p>
<?php }
add_action( 'add_meta_boxes', 'wptutsplus_metabox_top_right' );

This adds a small metabox with brief instructions - if I added a lot more text, it would move the metaboxes below it too far down the screen. You can see the result in the screenshot:

Note: I commented out the function for the metabox in the main area of the screen before adding this new metabox, which is why you can't see it in the screenshot.

3. Adding a 'Fake' Metabox Above the Editing Pane

So adding a small metabox on the top right of the screen is fairly simple - but what if I want a metabox at the top left, above the editing pane?

To do this, you don't use the add_meta_box() function, but use the edit_form_after_title hook, which inserts content after the post title and before the editing pane. I'll attach a function to that hook to define the markup which will be added to the screen, and I'll use classes in my markup to replicate the look of a metabox.

In your plugin, add the following:

function wptutsplus_text_after_title( $post_type ) { ?>
	<div class="after-title-help postbox">
		<h3>Using this screen</h3>
		<div class="inside">
			<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>
		</div><!-- .inside -->
	</div><!-- .postbox -->
<?php }
add_action( 'edit_form_after_title', 'wptutsplus_text_after_title' );

This adds some markup to the editing screen which looks a lot like a metabox, because I included the .postbox and .inside classes:

However, there is one problem with this markup - it will appear on the editing screen for each and every post type. As I'm not using the add_meta_box() function, I don't have the luxury of the $post_type parameter. So instead of using this, I'll perform a check for the editing page we're on before outputting the markup.

As I'm in the WordPress backend, I can't use the standard conditional tags I would use in a template file to check my location, but I can use the get_current_screen() function to identify which editing screen I'm on.

The get_current_screen() function returns an array, which will include the post type of the current screen, among other things. I can use this to check if the post type that's being edited is 'post'.

Inside your function, above the other contents, add the following:

$screen = get_current_screen();
$edit_post_type = $screen->post_type;

if ( $edit_post_type != 'post' )
	return;
?>

The entire function will now look like this:

// Add fake metabox above editing pane
function wptutsplus_text_after_title( $post_type ) {
	$screen = get_current_screen();
	$edit_post_type = $screen->post_type;
	if ( $edit_post_type != 'post' )
		return;
	?>
	<div class="after-title-help postbox">
		<h3>Using this screen</h3>
		<div class="inside">
			<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>
		</div><!-- .inside -->
	</div><!-- .postbox -->
<?php }
add_action( 'edit_form_after_title', 'wptutsplus_text_after_title' );

This will ensure that the 'fake' metabox will only be output on the Post editing screen, and not the editing screen for other post types. You could then repeat this function for different post types (such as 'page' and 'attachment', as well as your own custom post types), to display different help text for those.

Summary

Adding help text to individual editing screens can be very useful for users who don't want to keep returning to the dashboard to get help.

In this tutorial, you've learned how to add metaboxes for help text on editing screens, as well as how to use the edit_form_after_title hook to add help text immediately above the editing pane.