Creating Maintainable WordPress Meta Boxes: The Layout

In this series, we're walking through how to create maintainable WordPress meta boxes. That is, we're looking at some best practices that we can employ in our WordPress development to make sure that we're writing code that's maintainable by ourselves or by our team, as it continues to evolve over time.

In the first post, we looked at the initial directory structure and setup the basic code required to get a plugin running in WordPress. In this post, we're going to continue planning and building our plugin.

We'll also be talking about the decisions that we're making when it comes to separating parts of our code and how it factors into maintainability.

Planning Author's Commentary

In the previous post, we started working on a plugin called Author's Commentary. The idea behind the plugin is that it will allow post authors to leave various notes and assets associated with the post that were used either as inspiration, as thoughts after the post was written and received, and other similar information.

When writing a post, let's say that we want to capture three specific pieces of information:

Notes used when preparing the post
Assets and resources used throughout the post
Tweets and links to comments and feedback after the publication

To be clear, we want to have a way to maintain the notes that went into creating the post before it was written, links to various assets - be it external articles, images, videos, code samples, and so on - and then maintain a list of tweets, links to comments, and various snippets from emails we've received.

At this point, we have enough to go on in order to begin preparing the meta box and the tabbed layout for it.

The Meta Box Tabs

Before we actually begin writing any code, let's name the tabs that will be associated with each of the states of our post as listed above. Doing this will help us conceptually organize our input elements so they are logically grouped together.

Granted, you can name these anything you'd like, but if you're following along with this tutorial and the provided source code, then this is what you can expect to see.

The first tab will be called Draft as it will contain all of the bullet points, sentences, and other notes that went into preparing the post.
The second tab will be called Resources as it will include information on other posts, links, videos, and so on that we may refer to in our post or that we may embed in our post.
The final tab will be called Published as it will contain links to comments, fields for email, and other information all of which are relevant to the post after it has been published.

Straightforward enough, isn't it? We'll talk more about the input elements for each tab once we get to that point in the code, but for now we need to focus on creating the meta box and implementing the tabs.

Creating The Meta Box

To create the meta box, we'll take advantage of the add_meta_box function as documented in the WordPress Codex. To do this, we're going to be introducing a new class, updating the plugin's bootstrap file, and introducing some views that will be used to render markup in the browser.

The Meta Box Class

In order to make sure our code is well-encapsulated and that each class represents a single idea, we're going to create an Authors_Commentary_Meta_Box class. This class will be responsible for registering a hook with the add_meta_box action, setting up the meta box, and rendering its content.

For those who aren't use to writing plugins in an object-oriented manner with WordPress, this approach allows us to segment our areas of responsibility - such as a meta box - and have a single class representing all that goes into creating one.

To do this, first create class-authors-commentary-meta-box.php in the admin directory. Next, add the following code:

<?php

/**
 * Represents the Author's Commentary Meta Box.
 *
 * @link       http://code.tutsplus.com/tutorials/creating-maintainable-wordpress-meta-boxes-the-layout--cms-22208
 * @since      0.2.0
 *
 * @package    Author_Commentary
 * @subpackage Author_Commentary/admin
 */

/**
 * Represents the Author's Commentary Meta Box.
 *
 * Registers the meta box with the WordPress API, sets its properties, and renders the content
 * by including the markup from its associated view.
 *
 * @package    Author_Commentary
 * @subpackage Author_Commentary/admin
 * @author     Tom McFarlin <[email protected]>
 */
class Authors_Commentary_Meta_Box {

    /**
	 * Register this class with the WordPress API
	 *
	 * @since    0.2.0
	 */
	public function __construct() {
		add_action( 'add_meta_boxes', array( $this, 'add_meta_box' ) );
	}

	/**
	 * The function responsible for creating the actual meta box.
	 *
	 * @since    0.2.0
	 */
	public function add_meta_box() {

		add_meta_box(
			'authors-commentary',
			"Author's Commentary",
			array( $this, 'display_meta_box' ),
			'post',
			'normal',
			'default'
		);

	}

	/**
	 * Renders the content of the meta box.
	 *
	 * @since    0.2.0
	 */
	public function display_meta_box() {
	}

}

The comments and the content of the class should make it relatively easy to understand. It does three things, but to be clear:

The constructor registers the add_meta_box function with the corresponding WordPress action.
The add_meta_box function defines the properties of the meta box.
The display_meta_box function doesn't do anything yet - we'll be working on this momentarily.

Before we move on, there are a few changes we need to introduce to the rest of the plugin.

First, we need to include this new file in the plugin's bootstrap file. In authors-commentary.php, add the following line of code above the current require_once statement:

/**
 * The class that represents the meta box that will dispaly the navigation tabs and each of the
 * fields for the meta box.
 */
require_once plugin_dir_path( __FILE__ ) . 'admin/class-authors-commentary-meta-box.php';

We add this line above the initial code because the initial code depends on this particular file to run; therefore, it has to be loaded first.

Next, we need to introduce a new property in side of admin/class-authors-commentary.php that will refer to an instance of the meta box:

/**
 * A reference to the meta box.
 *
 * @since    0.2.0
 * @access   private
 * @var      Authors_Commentary_Meta_Box    $meta_box    A reference to the meta box for the plugin.
 */
private $meta_box;

Finally, we need to instantiate the code in the constructor of the class:

/**
 * Initialize the class and set its properties.
 *
 * @since    0.1.0
 * @var      string    $name       The name of this plugin.
 * @var      string    $version    The version of this plugin.
 */
public function __construct( $name, $version ) {

    $this->name = $name;
	$this->version = $version;

	$this->meta_box = new Authors_Commentary_Meta_Box();

}

At this point, you should be able to activate the plugin, navigate to a post page, and see an empty meta box:

Nothing too exciting, but we have what we need in order to begin introducing our tabbed navigation.

Adding Tabs

At this point, we're ready to introduce the tabbed navigation portion of the meta box. Ultimately, our goal is to introduce the markup and styles for the tab in this post, and then implement the behavior an the elements in the next post in the series.

With that said, let's first create a views subdirectory within the admin directory. Technically, we did this in the previous article; however, we didn't have content in the directory so it wasn't checked into source control (thus, the directory was not added - so if you're following along with the repository, now's the time to create the directory).

Next, create a file within the views directory called authors-commentary-navigation.php. This file will primarily serve as markup; however, it will include a little bit of PHP by the time we're doing with this plugin.

Add the following code to the file. We'll discuss it more in-depth after the block of code:

<div id="authors-commentary-navigation">
    <h2 class="nav-tab-wrapper current">
		<a class="nav-tab nav-tab-active" href="javascript:;">Draft</a>
		<a class="nav-tab" href="javascript:;">Resources</a>
		<a class="nav-tab" href="javascript:;">Published</a>
	</h2>
</div>

Once done, insert the following code into Authors_Commentary_Meta_Box, add the following code to import this particular piece of markup:

<?php

/**
 * Renders the content of the meta box.
 *
 * @since    0.2.0
 */
public function display_meta_box() {
    include_once( 'views/authors-commentary-navigation.php' );
}

Aside from the div container that we have, notice the following:

We've wrapped three anchors in an h2 element. The h2 element contains class attributes of nav-tab-wrapper and current. This allows for us to inherit styles directly from WordPress without doing anything on our part.
Each anchor has a nav-tab class the first of which has the nav-tab-active class. This again gives us a bit of styling from which we inherit from WordPress.
Each anchor also has the href attribute of javascript:; because the anchors aren't actually going to be taking us anywhere. Instead, in a future tutorial, we'll be using JavaScript to control the tabs and the content that's displayed within each one.

At this point, you should see the following:

Notice that all of the styles that are applied to the tabs have been provided by WordPress. The only thing that you may want to tweak is the margin that exists between the tabs and the horizontal line below them.

Let's do that now.

Including a Stylesheet

In the admin directory, add another subdirectory called assets and within it a directory called css. Next, create an empty file called admin.css.

After that, include the following lines in the CSS file:

a.nav-tab {
    margin-bottom: -4px;
}

Then be sure to include the following call in the constructor of class-authors-commentary.php:

add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_styles' ) );

Finally, add the following function - it's responsible for enqueuing the actual stylesheet:

/**
 * Enqueues all files specifically for the dashboard.
 *
 * @since    0.2.0
 */
public function enqueue_admin_styles() {

    wp_enqueue_style(
		$this->name . '-admin',
		plugins_url( 'authors-commentary/admin/assets/css/admin.css' ),
		false,
		$this->version
	);

}

At this point, it should look much cleaner:

With that done, we've completed everything that we need to do for the basic foundation of the navigation tabs for our meta box.

Preparing To Move Forward

In the next article, we're going to introduce the content for each tab and we're going to work through the JavaScript that's necessary to toggle the tabs and each of their content.

For those who are more experienced with WordPress, this series of articles may feel like it's moving at a slower pace, but that's the point - we're looking to be as exhaustive as possible when it comes not only to building our user interface, but also in explaining the rationale behind each of our decisions.

In the meantime, don't forget to checkout the source code on GitHub, follow along, and leave any questions or comments in the feed below.

HIGHLIGHTS OF THE DAY