WPAlchemy MetaBox: Data Storage Modes

This release introduces two modes of operation when creating a WordPress Meta Box: Array Mode and Extract Mode. The default mode is Array and will typically work well for the majority of users. Learn how and when to use Extract mode.

This release introduces two modes of operation when creating a WordPress Meta Box:

1. Array Mode (WPALCHEMY_MODE_ARRAY): Meta box data is stored in a single meta entry as an associative array.
2. Extract Mode (WPALCHEMY_MODE_EXTRACT): First tier variables (fields) are each stored as individual meta entries.

Tip: Select 720 HD mode and watch it fullscreen or click the YouTube button to watch it on YouTube.

What Am I Talking About, and Why Should You Care

The WPALCHEMY_MODE_ARRAY mode is the default mode and is currently how the PHP class operates. The class will store all of its values as an associative array in a single meta entry (in the wp_postmeta table). This mode will typically work well for the majority of users.

But, there are instances where you can use meta data directly in WordPress functions. Such is the case with the query_posts() function. This function allows you to use certain values (meta_key, meta_value and meta_compare) to directly access post meta data. In these cases it is useful to have access to a single meta entry (name/value pair) versus an associative array entry.

The WPALCHEMY_MODE_EXTRACT mode will extract all the first tier variables (fields) and create individual meta entries in the wp_postmeta table.

So, How Do I Use It

Setting your meta box to use WPALCHEMY_MODE_EXTRACT mode is straight forward, you would do something like the following:

$custom_metabox = new WPAlchemy_MetaBox(array
(
	'id' => '_custom_meta',
	'title' => 'My Custom Meta',
	'template' => TEMPLATEPATH . '/custom/meta.php',
	'mode' => WPALCHEMY_MODE_EXTRACT,
	'prefix' => '_my_'
));

What is The Prefix For?

The prefix parameter allows you to prefix all the first tier variables (fields) with a string value. This is important because when using WPALCHEMY_MODE_EXTRACT mode, you have to take care to avoid name collisions with other meta entries. The easiest way to do this is to add a prefix to your variables.

You can do this automatically for all extracted values in the meta box (as seen above, using the prefix parameter) or you can do this manually in the meta box template file when declaring your form fields, as such:

// manually adding "_my_" prefix to each field name
<?php $mb->the_field('_my_name'); ?>
<input type="text" name="<?php $mb->the_name(); ?>" value="<?php $mb->the_value(); ?>"/>

<?php $mb->the_field('_my_description'); ?>
<textarea name="<?php $mb->the_name(); ?>" rows="3"><?php $mb->the_value(); ?></textarea>

Using the values in your theme template files is equally straight forward, the following are all equivalent ways of accessing the variables (fields):

$custom_metabox->the_value('name');

$custom_metabox->the_field('name');
$custom_metabox->the_value();

// uses the true meta entry name directly
echo get_post_meta(get_the_ID(),'_my_name',TRUE);

// using get_the_name(), both examples work
echo get_post_meta(get_the_ID(),$custom_metabox->get_the_name('name'),TRUE);
echo get_post_meta(get_the_ID(),$custom_metabox->get_the_name('_wpa_name'),TRUE);

In the case of the query_posts() function you could do something like:

query_posts('cat=3&orderby=meta_value&meta_key=' . $custom_metabox->get_the_name('name'));

Download

WPAlchemy MetaBox Class, this project is on github

I Need Your Help

I generally do a better job of adding features which I use personally. This particular feature was added because its had a few requests, and I do see a need for it, however I haven’t yet had a requirement to use it myself.

Other than testing the feature and having a general idea of how you are going to use it, I need your feedback. If you are using this release please give me your candid thoughts, opinions and wishes. This will help me shape a solid and elegant API.