Improve the content management experience for your WordPress clients with tooltips

I create bespoke WordPress websites to solve problems. These websites hopefully solve a client’s customer’s problem through the purchase of a product or service. That’s the obvious part of the job. Often neglected though is that the website backend must also be designed to solve content management issues for my clients. One of the ways I customize the websites I build is to leave notes in the editing interface for the client so that they don’t have to guess as to the parameters of things like “what’re the ideal dimensions for featured images for our blog posts”.

I frequently use Advanced Custom Fields to build custom interfaces for specific needs, and there’s a nice spot to leave these notes for users.

For the native WP features, WordPress doesn’t have a native way to do this. Luckily we can use JavaScript to insert these instructions as the backend page is built.

Here’s an example of a note that should now be added to the backend interface:

Here’s the code snippet that accomplishes this:

<?php 
// gives some user instruction for Featured Image on blog posts
function modify_featured_image_instructions() {
	if (get_post_type() !== 'post') {
		return; // exit the function if the post type is not a regular blog post
	}
	?>
        <script>
			document.addEventListener('DOMContentLoaded', () => {
			const postImageDiv = document.querySelector('body.post-type-post #postimagediv .inside');
			if (postImageDiv) {
				postImageDiv.insertAdjacentHTML('beforeend', '<p class="description">This img will display on the top of single blog post pages, & as a thumbnail on the blog archive page. Img should be 1000x300</p>');
			}
			});
        </script>
    <?php
}
add_action('admin_head-post.php', 'modify_featured_image_instructions');
add_action('admin_head-post-new.php', 'modify_featured_image_instructions');
?>

This is what happens

1. The get_post_type() function is used to get the type of the current post being edited in the WordPress admin area. The code then checks if the post type is equal to “post”, which is the post type for regular blog posts. If the post type is not “post”, the function returns without doing anything else.
2. The addEventListener method is called on the document object, which represents the current HTML document. This method takes two arguments:
   • The first argument is the name of the event to listen for. In this case, the event is DOMContentLoaded, which fires when the HTML document has finished loading and is ready to be manipulated with JavaScript.
   • The second argument is a callback function that will be called when the event is triggered.
3. The callback function passed to addEventListener in step 1 begins with a const declaration, which creates a new constant variable called postImageDiv. This variable stores the result of the querySelector method, which is called on the document object. This method takes one argument: a CSS selector that identifies the HTML element(s) to select. In this case, the selector is body.post-type-post #postimagediv .inside. This selector selects the HTML element with the class inside that is a descendant of an element with the ID postimagediv, which is a descendant of the body element that has a class of post-type-post. The postimagediv element is the box that WordPress provides for uploading and setting the Featured Image for a blog post.
4. An if statement checks if the postImageDiv variable contains a truthy value (i.e., an HTML element was found that matches the querySelector selector). If the value is truthy, the code inside the if block will run. If the value is falsy (i.e., no element was found that matches the querySelector selector), the code inside the if block will be skipped.
5. If the if statement in step 4 evaluates to true, the insertAdjacentHTML method is called on the postImageDiv variable. This method allows HTML to be inserted into the DOM (Document Object Model) relative to the element that postImageDiv represents. This method takes two arguments:
   • The first argument specifies where in the DOM the new HTML should be inserted. In this case, the value is 'beforeend', which means the new HTML will be inserted as the last child of the postImageDiv element.
   • The second argument is the actual HTML to be inserted. In this case, the HTML is a p element with a class of description. The p element contains a message that gives user instructions for adding a Featured Image to a blog post. The message specifies the size of the image and where it will be displayed on the blog.
6. When the DOMContentLoaded event is fired (i.e., when the HTML document has finished loading), the callback function passed to addEventListener in step 1 is called. This function selects the HTML element with the ID postimagediv that is a descendant of an element with the class post-type-post and adds a p element with a message for the user to the end of the postImageDiv element.