1. Code
  2. Plugins

Three Practical Uses for Custom Meta Boxes

Scroll to top
Read Time: 16 min

Last week we introduced how to create custom meta boxes inside the post-editor and save the data you put in them. But what are some practical applications of this technique? Today, the goal is to go over three real world examples of using custom meta boxes to improve the post page.

In the introduction article, you learned all about how to implement meta boxes and save/clean the data the goes into them. That great! But it's time to go beyond the conceptual information and put those custom meta boxes to work.

Example 1. Adding a Quote to the Top of Posts

The scenario: You run a website that primarily publishes inspirational content. One of the things you do consistently is put quotes at the top of each post. To separate these quotes from the content, you want to move them into a custom meta box.

In the "how to" article, you learned how to actually implement meta boxes, but here's a quick review.

1. Add the Meta Box

Hook a function into the add_meta_boxes that contains a call to the add_meta_box function.

2. Render the Meta Box

The create a function with the same name as the $callback specified in add_meta_box. This is the piece that actually displays meta box content.

3. Save the Data

Hook a function into save_post that first handles verifying permissions and intention and then cleans and saves the data.

The Quote Meta BoxThe Quote Meta BoxThe Quote Meta Box

Now the Fun Part: Using the Data

We could use the data saved in our meta boxes by editing our theme's template files. But that's too easy. To keep our quote code modular (one plugin file), we'll use filter hooks, part of the Plugin API. Filter hooks are a bit different from actions. When you hook into a filter, the purpose is, most of the time, to alter how a piece of content appears on a page. In our case, we're going to hook into the_content, and if we're on a single post page that has a quote we'll add it above.

Another way to think of action vs. filter hooks is that you echo things out in actions (eg. wp_head, see section 2), but with filters you take in one or more variables, alter them, then return them.

To display our quote, we'll hook into the_content, which passes one variable by default: the content of a given post. Inside our hooked function, we'll make sure we're on a single post and, if we're not, return the content right way (no alterations).

Next up, we'll get our $post variable. Because we're in the loop, we just call global $post. Then we'll get our quote, if no value comes back, we know that no quote was entered and we return the content once again without alteration.

Now that we've made sure we're on a single post and we actually have a quote, we an take care of putting things together. First we'll call our author and her dates via get_post_meta(), then we can start constructing a string in the $out variable. First we'll add a <blockquote> and our quote. Then we check to see if the author field was filled out. If it was we'll start a paragraph for the author then check to see if there was a date and add that to the paragraph as well. Finally, we'll add our closing </blockquote> tag.

Now the most crucial step: returning the combination of our newly made $out string which contains the quote and the original content found in $content.

That's it! You can see the result.

Meta Box Quote DisplayMeta Box Quote DisplayMeta Box Quote Display

Example 2. Adding Open Graph Meta Tags

The scenario: You have an active community of readers who regularly share your articles on Facebook. This is awesome, and it sends a lot of traffic your way. But you start noticing that the images showing up with your articles on Facebook are less than ideal. You're also not happy with how your posts titles are coming out. The solution is to add Open Graph meta tags to control how your articles display. Rather than let this get taken care of automatically, you decide to implement a custom meta box to take care of it.

Set up the Meta Box

You probably have this down by now, but here's the code for getting your meta box going.

Open Graph meta boxOpen Graph meta boxOpen Graph meta box

Add Some JavaScript

To make that "Upload Image" button work, we'll have to add a bit of javascript that hijacks the built in WordPress uploader. This means we're going to use yet another action hook. This time its admin_print_script-{$page}.

When adding scripts and/or styles to the admin area of WordPress, there is one golden rule: only add the scripts/styles where you need them. This prevents your plugin/theme from breaking something else on accident. admin_print_scripts-{$page} lets you only insert scripts (via wp_enqueue_script function) only on the $page specified. In this case, we need to add our script to the post.php and post-new.php screens. This requires hook the same function into both.

And the javascript.

First we make sure the thickbox uploader pops up when clicking on the button, and we set up a variable that tells WordPress that it was our button that was clicked. Next, we save the window.send_to_editor function with a new name. This is the function that actually inserts the image HTML into the post editing area. We're going to hijack this function to send on the src attribute to our own form field, but only if the thickbox was brought up by our button.

Add the Open Graph Tags

We're going to hook into the wp_head action to add our meta tags in the <head> section. First we'll make sure we're on a single post page, and then set up our $post variable. $post shouldn't be empty at this point as WordPress has already decided what sort of object its rendering and what template file it needs to use. But, in case it is, we'll retrieve post with get_queried_object().

Next up we can go through each Open Graph variable, fetching everything with get_post_custom(), and, if its there, echo it out into the head section of our page.

Open Graph meta box frontendOpen Graph meta box frontendOpen Graph meta box frontend

Example 3. Change Twenty Eleven Layouts on the Fly

The scenario: You rely heavily on Twenty Eleven's sidebar page template. But you want to be able to switch between left and right sidebars for each page.

The following code would be something better left in a theme's functions file. That said, because we're using a plugin here, we can hook into the init and with our function check to make sure Twenty Eleven is the current theme. If it's not, we'll deactivate the plugin. First, however, we'll define a constant containing the URL of the directory in which our plugin resides.

Adding the Meta Box

Same routine as before: add the meta box, render it, and save the data. This time, however, we're going to display our meta box on the edit screen for pages. We're also going to use a nifty wordpress function called get_template_directory_uri, which returns a string containing the URI of the directory for the current theme. We're going to use this to borrow a few images that Twenty Eleven uses on its theme options page. We're also going to use the constant we defined earlier to add an image of our own.

To prettify our meta box a bit, we'll need to add our own stylesheet as well. Remember admin_print_scripts-{$page} from the second scenario above? It has a brother, admin_print_styles-{$page}, which, as the name implies, lets you add stylesheet to the wordpress admin on specific pages. We'll need to hook into this function for post.php and post-new.php. We'll also be using wp_enqueue_style(); it works the same was as wp_enqueue_script(), which we used in the second example above.

And the CSS.

Open Graph meta box frontendOpen Graph meta box frontendOpen Graph meta box frontend

Digging into Twenty Eleven

Twenty Eleven accomplishes its sidebar positioning by hooking into a filter called body_class. This is part of the function called <?php body_class(); ?>, which, if you've designed a theme before, you've probably used. If the default layout is two column, Twenty Eleven adds one of two additional items to body_class: right-sidebar or left-sidebar. You can see the code for this in the theme's inc folder in the file theme-options.php.

Our own code is also going to hook into body_class. First, we'll make sure we're on a page, and that that page is using the Sidebar Template. Then we'll get the $post variable or set it if its empty. Notice two additional arguments for add_filter. 99 is the priority. We want this to fire last, so we use a higher number. 1 is the number or arguments to send to our function.

body_class will send an array of all the items that will go into the body_class() output function. From here, we just need to get our own meta values. If our value is 'right', we'll look for "left-sidebar" in the body class array. If it's there, we'll unset it and replace it with "right-sidebar". Vice versa if our value is left.

The above would work, but we've left out a little detail. If a user happened to have Twenty Eleven's theme options set to a one column display, none of the options in our meta box would work. So lets modify out add_meta_box call a bit. First we'll get Twenty Eleven's options, then we'll make sure the theme layout option is not set to one column. If the theme is set to one column, we won't add the meta box.

Wrap Up

As you might imagine, there are many other uses for custom meta boxes... these are just a few practical examples to get your mind working. When combined with custom post types, they allow you to create extremely customized editing screens. The real strength of custom meta boxes, however, lies in how theme designers and plugin developers can create more user friendly interfaces for post or page level settings.

We hope you enjoyed the tutorial!

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.