We Are Communication Architects

Building brand awareness through content creation and community engagement.

September 20th, 2010

A Pattern for Creating Supportable Custom Meta Box Handlers in WordPress

Back while helping work on WordPress 3.0 and all the changes that were involved in adding better support for custom post types, I saw a need for improving the registration of meta-boxes. Specifically, making it so custom meta handlers could be supportable like the built in ones such as the editor, excerpt, and thumbnail meta-boxes. This would allow you to setup up a post type and add custom meta handlers just by adding a call to add_post_type_support($post_type, $feature);.

I had ambitions to get a patch together for WordPress 3.1, but sadly, haven’t made any headway at this point. So, for the time being, I’ve come up with a pattern to simplify the creation of supportable meta-box handlers. To illustrate this pattern, I’ll be creating a simple meta-box to store a twitter handle for any post type that supports it. We’ll start with creating the plugin class Twitter_Meta_Handler and initializing it. Other than the init hook, we’ll put all other needed hooks within the initialize() method to keep things clean.

class Twitter_Meta_Handler {
  public function initialize() {
    //empty for now
  }
}
add_action('init', array(new Twitter_Meta_Handler(), 'initialize'));

Now that the basic wrapper and initialization for the meta handler is setup, we’ll need to register the meta-box that will present the editable field to the user. A hook needs to be added to the initialize() method to that will register to call our plugin’s add_metabox() during the ‘add_meta_boxes’ action. When registering the meta-box, we’ll first check that the post type being displayed supports our meta handler, in this case, ‘twitter_handle’.

public function initialize() {
  add_action('add_meta_boxes', array($this, 'add_metabox'), 10, 2);
}

public function add_metabox($post_type, $post) {
  if(post_type_supports($post_type, 'twitter_handle')) {
    add_meta_box('twitter_handle', 'Twitter Handle', array($this, 'metabox'), $post_type);
  }
}

Once the meta-box callback is registered, we need to implement the method that is called to display the edit box. For the twitter handle, it will be nothing more than a simple text input.

public function metabox($post) {
  $twitter_handle = get_post_meta($post->ID, 'twitter_handle', true);
  if(!$twitter_handle) {
    $twitter_handle = '';
  }
  echo '<input type="text" style="width: 70%;" value="' . esc_attr($twitter_handle) . '" name="twitter_handle" id="twitter_handle">';
}

The next step is to save the submitted value during the ‘save_post’ action, we’ll add a ‘save_post’ action in our initialize() method to register a callback to a new update() method. With everything together we now have:

class Twitter_Meta_Handler {
  public function initialize() {
    add_action('add_meta_boxes', array($this, 'add_metabox'), 10, 2);
    add_action('save_post', array($this, 'update'));
  }

  public function add_metabox($post_type, $post) {
    if(post_type_supports($post_type, 'twitter_handle')) {
      add_meta_box('twitter_handle', 'Twitter Handle', array($this, 'metabox'), $post_type);
    }
  }

  public function metabox($post) {
    $twitter_handle = get_post_meta($post->ID, 'twitter_handle', true);
    if(!$twitter_handle) {
      $twitter_handle = '';
    }
    echo '<input type="text" style="width: 70%;" value="' . esc_attr($twitter_handle) . '" name="twitter_handle" id="twitter_handle">';
  }

  public function update($post_id) {
    if(wp_is_post_autosave($post_id) || wp_is_post_revision($post_id)) {
      return $post_id;
    }
    if(post_type_supports( get_post_type( $post_id ), 'twitter_handle' ) && isset($_REQUEST['twitter_handle'])) {
      $twitter_handle = strip_tags($_REQUEST['twitter_handle']);
      if(empty($twitter_handle)) {
        delete_post_meta($post_id, 'twitter_handle');
      } else {
        update_post_meta($post_id, 'twitter_handle', $twitter_handle);
      }
    }
  }
}
add_action('init', array(new Twitter_Meta_Handler(), 'initialize'));

With the final setup of saving the submitted twitter_handle, we now have a very simple meta-box handler that can be added to any post type with a single line of code: add_post_type_support('your_post_type', 'twitter_handle');. But even more than that, we now have a reusable pattern for creating other supportable meta-box handlers. By replacing the supportable string ‘twitter_handle’, meta-box display and update methods will allow this pattern plugin to easily be modified to work with other meta fields.

About the Author
Michael Pretty is an application developer for the Voce Connect Platforms team with a background in developing for PHP, mySQL, WordPress and a handful of other environments. Follow him on Twitter @prettyboymp

Filed in Development, Programming, WordPress

Add Your Comment2 Responses to “A Pattern for Creating Supportable Custom Meta Box Handlers in WordPress”

Bill on October 7th, 2010 at 1:59 pm

This is great. Thank you. How do you move the new Meta Box higher on the page?

Michael Pretty (prettyboymp) on October 12th, 2010 at 2:58 pm

There are two more parameters the add_meta_box() function will take after the ‘post_type’ argument. The first one is ‘context’, and the second is ‘priority’. Changing either of those to other applicable values will change the default position. Check out the codex to see how these work in more detail: http://codex.wordpress.org/Function_Reference/add_meta_box