How To Add Custom Contextual Help Content To The WordPress Dashboard

Last updated September 23rd, 2020 at 02:29 pm

In this article I explain how to add custom contextual help content to the WordPress dashboard.

If you’re a WordPress developer, you can make your clients more self-sufficient and effective by adding custom contextual help content. And that can make you more valuable to your clients.

Even if you’re not a WordPress developer, this article may be of interest.

Suppose you’re the owner of a WordPress Web site and you perform some site maintenance functions. Unless you’re very experienced, there might be some procedures that a customized cheat sheet — in the form of custom contextual help content — could help you with. This is especially true if your developer added some custom functionality to your site.

The Problem

The purpose of the help content I’ll be adding is to discourage beginning WordPress users from making a common mistake when adding images to pages and posts.

What is this common mistake?

Choosing “Attachment Page” as the “Link to” option from the “Add Media” screen.

Why Linking an Image to its Attachment Page is a Problem

The end result of linking an image to its Attachment Page is almost never desirable. When visitors click on the thumbnail image in the original page or post, they are taken away from the current page and over to a page (the Attachment Page) which, by default and in most cases, pretty much sucks.

Here’s a sample page with an image thumbnail which is linked to its attachment page:

And here is what the attachment page looks like:

Notice the problems?

1. The attachment page displays the same thumbnail as the one that was clicked — requiring yet another click to view the enlarged image.
2. The attachment page displays the image’s title (by default the image’s filename), which is usually something geeky, like img_0513421.
3. The attachment page displays only the image’s description — if one was entered in the media library — and not any caption that may have been assigned to the image. It’s more common for people to give images captions than descriptions.

This is hardly ever the desired result.

In fact, the desired result most often is to have an enlarged version of the image load in a modal window (lightbox effect) when visitors click on thumbnails — just like this screenshot below:

The Solution

For this solution, I’ll be adding contextual help content to the existing help screens for adding and editing WordPress posts and pages. This new help content will warn the user not to link images to their attachment pages — and it will explain the other link-to options.

Caveat

Working with many clients for many years on many WordPress Web sites, I’ve learned that many people just don’t know contextual help screens even exist. Therefore, any attempt to solve this link-image-to-attachment-page problem by adding contextual help content will fail if users never actually look at and read the contextual help screens. So there’s a bit of education involved.

By the way, in case you’re one of those who does not know about WordPress contextual help screens, here’s the quick tip:

You can access contextual help in the WordPress dashboard by clicking on the “Help” tab that appears on dashboard screens that have contextual help. Not all screens do. Below is a screenshot of what you want to look for and click:

Default Contextual Help Screens for Add and Edit Page or Post

WordPress comes with some built-in contextual help screens. Below are screenshots of what the default built-in contextual help screens for posts and pages look like. Note that there are four help tabs, including one for “Inserting Media”, but there is no mention of media-linking options. I aim to correct that.

New Custom Contextual Help

Here’s what the new contextual help screen will look like after my custom content is added:

(I like to distinguish my custom contextual help tabs from the built-in help tabs by embracing their titles in asterisks. This way my clients know at a glance which help content I have added for them.)

Step-By-Step Process For Adding Your Custom Contextual Help Content

Step 1: Create a new file for your php scripts.

Create a php file in your /wp-content/mu-plugins/ folder (create that folder if it does not already exist). Name the file something meaningful like “contextual-help.php”. This file will store and serve up the functions you write in the next steps.

A couple of things:

1. I advise against adding your function scripts to your theme’s functions.php file (or even a child theme’s functions.php file). Why? Because if the functionality you’re building has nothing to do with your theme (and in this case it does not), the code doesn’t belong in a theme file that will be non-operational as soon as someone changes the site’s theme.

   Read about the mu-plugins folder at WordPress.org.

2. Your scripts don’t have to be in their own php file. For example, you might have a functions.php file in your mu-plugins folder that stores and serves up a variety of scripts, and you could add all this help-related code to it.

Step 2: Write the help content you want to show up on your custom help screen.

(Technically — as I’ll explain further on — this step is optional. That’s because you could load the help content in Step 3, when you will be generating the Help tab. That said, I think it’s best to separate things — especially if your help content is lengthy and/or contains lots of HTML that requires escaping.)

Write a php function that contains (and “returns” — in the programming sense of the word) the contextual help content.

Here is my function that contains the help content:

function nwb_help_content_image_linking() {
	$content = <<<CONTENT
<h1>Media Linking Options</h1>
When adding media to a post, do <b>NOT</b> select <b>Attachment Page</b> as the <em><b>Link To</b></em> option. Read on to learn more.
<h2>Link to Options:</h2>
There are <strong>four</strong> options for linking media. Here are my recommendations for use.
<dl>
<dt><strong>None:</strong></dt>
<dd>Choose this option when you simply want the image to display and you are adding either the Full Size version of the image or some other size that will render acceptably without being enlarged.</dd>
<dt><strong>Media File:</strong></dt>
<dd>Choose this option when selecting a display size other than <strong>Full Size</strong> and you want the image enlarged when a visitor clicks on it. This is especially useful in conjunction with <em>lightbox</em> plugins that enlarge images in modal windows.</dd>
<dt><strong>Attachment Page:</strong></dt>
<dd>With very few exceptions, <strong>this option should <em>never</em> be chosen</strong>. The result is almost always undesirable.</dd>
<dt><strong>Custom URL:</strong></dt>
<dd>Choose this option if you want to navigate the visitor to some specific Web page. Example: You have an image that is a graphic of a discount coupon — essentially a graphic button — and you want visitors to be taken to the page where they can redeem the coupon.</dd>
</dl>
CONTENT;
	return $content;
}

Note that I’m using the php HEREDOC syntax (lines 2 and 17). This makes it really easy to write HTML without escaping things all over the place. I’m simply loading all of my help content into the variable $content and then returning it. Also, I like to format content like this using the HTML Description List element (<dl>) along with HTML Term element (<dt>) and the HTML Description element (<dd>). (Reference)

You may be wondering: return it ($content) to where? That’s step 3!

Step 3: Write a function that generates the help tab

Here is my function that generates the new help tab:

function nwb_add_post_help_tab() {
	$screen = get_current_screen();
	if ( $screen->id == 'post' || $screen->id == 'page'  ) {
		$screen->add_help_tab( array(
			'id'       => 'media_linking_help', 
			'title'    => '*About Linking Media*', 
			'content'  => nwb_help_content_image_linking(),
			) 
		);
	}
}

At the heart of this function are two built-in WordPress functions:

• get_current_screen()
  This returns a screen object containing values I’ll test further down.
• add_help_tab())
  This is the function that registers the new help tab.

Explanation:

• Line 3: This code tests whether the current admin screen is for posts or pages. If so, the rest of the function is executed. (Note: If you have other custom post types into which the user might add images, you would want to extend the conditional statment on line 3 to include them.)
• Line 5: The id element should be a unique identifier for the help tab you’re creating.
• Line 6: The title element is what you want the tab’s title to be.
• Line 7: The content element defines the content. In this case I’m using the HTML that is returned from the nwb_help_content_image_linking() function I created in Step 2.

Note: What was that again about Step 2 being optional?

The fact is that you could just hard-code the help content on line 7 of the script, without calling another function. This might be a preferable way to go if your help content is short and simple, like in the following example:

function nwb_add_post_help_tab() {
	$screen = get_current_screen();
	if ( $screen->id == 'post' || $screen->id == 'page'  ) {
		$screen->add_help_tab( array(
			'id'       => 'media_linking_help', 
			'title'    => '*About Linking Media*', 
			'content'  => 'Do not even THINK about linking images to attachment pages!',
			) 
		);
	}
}

Step 4: Add the action to kick it all off

Finally, a simple one-liner will set off the chain of events:

add_action( "admin_head", 'nwb_add_post_help_tab');

Step 5: Upload the file to the server.

Putting all the code pieces together, here’s what my contextual-help.php file looks like:

<?php
add_action( "admin_head", 'nwb_add_post_help_tab');

function nwb_add_post_help_tab() {
	$screen = get_current_screen();
	if ( $screen->id == 'post' || $screen->id == 'page'  ) {
		$screen->add_help_tab( array(
			'id'       => 'media_linking_help', 
			'title'    => '*About Linking Media*', 
			'content'  => nwb_help_content_image_linking(),
			) 
		);
	}
}

function nwb_help_content_image_linking() {
	$content = <<<CONTENT
<h1>Media Linking Options</h1>
<p>When adding media to a post, do <b>NOT</b> select <b>Attachment Page</b> as the <em><b>Link To</b></em> option. Read on to learn more.</p>
<h2>Link to Options:</h2>
<p>There are <strong>four</strong> options for linking media. Here are my recommendations for use.</p>
<dl>
<dt><strong>None:</strong></dt>
<dd>Choose this option when you simply want the image to display and you are adding either the Full Size version of the image or some other size that will render acceptably without being enlarged.</dd>
<dt><strong>Media File:</strong></dt>
<dd>Choose this option when selecting a display size other than <strong>Full Size</strong> and you want the image enlarged when a visitor clicks on it. This is especially useful in conjunction with <em>lightbox</em> plugins that enlarge images in modal windows.</dd>
<dt><strong>Attachment Page:</strong></dt>
<dd>With very few exceptions, <strong>this option should <em>never</em> be chosen</strong>. The result is almost always undesirable.</dd>
<dt><strong>Custom URL:</strong></dt>
<dd>Choose this option if you want to navigate the visitor to some specific Web page. Example: You have an image that is a graphic of a discount coupon — essentially a graphic button — and you want visitors to be taken to the page where they can redeem the coupon.</dd>
</dl>
CONTENT;
	return $content;
}

Upload the file to the server, and your new custom contextual help content will show up in the admin panel!