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.
- Array Mode (
WPALCHEMY_MODE_ARRAY): Meta box data is stored in a single meta entry as an associative array.
- 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
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_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.
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?
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):
// 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'));
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.