Code Styling Project

Starting with WordPress Version 2.7 a new kind of metabox handling has been occured at Backend. You are now able to drag/drop or hide this Boxes. This makes daily work easier.

But there is currently insufficient documentation available, how this metaboxes can be used at your own plugin pages. I try here to explain the needed functions and have written a demo-plugin for download based on this articles information. Feel free to inspect it after reading the article, it may help you understand the concept.

Requirements

At the following article i will explicitely write about WordPress version 2.7 and higher. Older versions of WordPress are unsuitable for this because they lack of available functions. Some have been first introduced with 2.7 so i didn’t spend the time creating this backward compatible even it would be possible with a lot of costs.
I also skipped the gettext functionality for this demo because the plugin is a how to example and showcase. It’s much easier to understand, if it only contains the nessessary metabox stuff.

Function Description

As first step into this topic i will briefly show the available WordPress functions, here they are:

1
2
3
4
5

function add_meta_box($id, $title, $callback, $page, 
                      $context = 'advanced', $priority = 'default')
 
function do_meta_boxes($page, $context, $object)
 

Function: add_meta_box

Using the function add_meta_box(…) you will register a new metabox at WordPress can be used by any page that matches with the given parameters.
The parameter $id is the unique identification for this registered metabox.
With the $title parameter you specifiy, what should be shown at the header of metabox. It is recommended that you use gettext based text here to permit a translation of your box title with language files.
The value $callback expects a callback function. It will be called by WordPress whever the content of this box has to be shown and should directly output the markup needed.
With the parameter $page you define the page, where this metabox is intended to be appearing. This implies also that your metabox can be shown at other plugin or core pages, if you know the exact parameter therefor.
The value $context will be used to define the context in which the box is intended to be appearing. In most cases this will be used to separate between content boxes and sidebar boxes.
Using $priority gives you the limited control in what order the boxes at the same context will be shown. Available values are: ‘high’, ‘core’, ‘default’, ‘low’.

Function: do_meta_boxes

If you call the function do_meta_boxes(…) the WordPress core generates and outputs all parameter matching metaboxes have been prior registered.
The value $object if free for use and intendend for programmers to handover additional informations into the metabox callbacks they may need to generate their content.

Metabox - content generation callback function

1
2
3
4
5
6
7
8
9
10
11

<?php function on_contentbox_1_content($data) {
	sort($data);
	?>
		<p>
			The given parameter at <b>sorted</b> order are: 
			<em><?php echo implode(' | ', $data); ?></em>
		</p>
	<?php
}
?>
 

At this example you will find the parameter $object as Array of strings ($data parameter) passed over to be used inside content generation. You can freely pass any kind ob object into the callbacks, it’s mostly the choise of programmer.
If you think about the admin center page “Write Post” the passed object is there the post object itself ($post).

Metabox Registration - importance of when to execute

You can register our own metabox at 2 different points in time:

1. WordPress tells you, that it is currently loading your plugins page
2. during the output of your own plugin page

This difference of point in time determines if this box can be hidden using the Screen Options menu or not. Boxes that have been registered during load indication call of this plugin page can be hidden using the checkboxes. If you register your metabox during output of your plugin page content but prior to your call to do_meta_boxes(…), you can’t hide this box at this page it is always visible and no checkbox appears therefor.
You don’t have to deal with the mechanism how to get the checkboxes for hiding in place, the WordPress core does this automatical for you and provides the boxes at tab Screen Options without any further programming.

Javascript is nessessary to get show/hide and drag/drop

If you have implemented all your stuff until this point you may wonder, why the boxes can’t be dragged , why WordPress not remembers which have been switched off (hidden) and why it ignores the collapsed state. This is related to some Javascript Magic we have to introduce as next.

1
2
3
4

wp_enqueue_script('common');
wp_enqueue_script('wp-lists');
wp_enqueue_script('postbox');
 

This named scripts have to be used inside your plugin page to get the effects and capabilities working. But the scripts do nothing, if they haven’t been initialized. This mostly will be done by inline javascript code like this:

1
2
3
4
5
6
7
8
9
10
11

<script type="text/javascript">
	//<![CDATA[
	jQuery(document).ready( function($) {
		// close postboxes that should be closed
		$('.if-js-closed').removeClass('if-js-closed').addClass('closed');
		// postboxes setup
		postboxes.add_postbox_toggles('<?php echo $this->pagehook; ?>');
	});
	//]]>
</script>
 

Example Screenshots of Demo-Plugin

Pictures are better than text. I have created 2 screenshots to illustrate what you can expect from this demo plugin, one as overview and an other with expanded Screen Options configuration:
 

Update: Modification for WordPress 2.8 new Metabox Model

The upcomming WordPress version 2.8 will change the handling of meta boxes while new column relations will be introduced. The following screenshot illustrates, what can be found now additionally at the settings tab slider:

That’s why it is necessary to handle this new behavoir. If this would not be changed, WordPress 2.8 versions won’t show any right sidebar for metabox content! It requires as first and new filter to be registered:

1
2
3
4
5
6
7
8
9

add_filter('screen_layout_columns', array(&$this, 'on_screen_layout_columns'), 10, 2);
...
//for WordPress 2.8 we have to tell, that we support 2 columns !
function on_screen_layout_columns($columns, $screen) {
	if ($screen == $this->pagehook) {
		$columns[$this->pagehook] = 2;
	}
	return $columns;
}

Inside the filter method the array must be modified to stored the ammount of columns will be supported by this admin page (in this case 2 - content and right sidebar). But that’s not enough. While rendering (output) the metaboxes, we have to respect the current user choosen number of columns. Dependend on that number we must extend a HTML element with an additional class name:

1
2
3

global $screen_layout_columns;
...
<div id="poststuff" class="metabox-holder<?php echo 2 == $screen_layout_columns ? ' has-right-sidebar' : ''; ?>">

After all this changes the demo plugin now works with WordPress 2.7 and also upcomming WordPress 2.8 version. The download file below has been adjusted and contains the modifications too. The source code also contains additional comments.

Download the example plugin

Based on the explanations and for your more deeply understanding i have build a short package with a full functional plugin that demonstrates all what has been written here. The code is under GPL and can be used or modified as you need it.
If you want to honor this work, please leave a remark at your source code or link to my page. It’s up to you doing so or not.

Here is the download of this demo plugin: howto-metabox-plugin.zip (509 downloads)