This post will explain how to easily implement custom meta boxes in your WordPress theme by using the Theme Toolkit provided by Theme Foundation. If you don’t want to use the toolkit, but are interested in implementing custom meta boxes from scratch, please see WordPress Meta Boxes: a Comprehensive Developer’s Guide.
1. Get the Theme Toolkit
The Theme Toolkit is currently in semi-private beta. If you sign up to receive Theme Foundation updates you will be sent a link to the Theme Toolkit. You will be able to browse the code and download the toolkit for use in your projects.
Please note: Since the toolkit is still in beta, it is subject to change before release. However, please give it a try and let me know if you have any questions or suggestions. Thanks!
2. Load the required files
Once we’ve downloaded the toolkit, we can simply place the “toolkit” folder in our theme and add the following code to the theme’s functions.php file.
/**
* Loads the toolkit/toolkit.php file for adding toolkit feature support.
*
* @since toolkit 1.0
*/
function theme_toolkit_setup() {
// Adds theme support for toolkit features.
add_theme_support( 'toolkit-meta-boxes' );
// Loads the toolkit setup file.
require_once 'toolkit/toolkit.php';
// Initializes the theme toolkit.
theme_toolkit_init();
} // End function thtk_setup()
add_action( 'init', 'theme_toolkit_setup', 1 );
This function adds theme support for the toolkit theme customizer. It then loads the toolkit.php file. Finally, it initializes the theme toolkit.
Once this initial section of code is in place, we interact with the theme toolkit using filters. For those of you who are not familiar with WordPress filters, the following documentation and tutorials should be helpful:
- Of course, the WordPress Codex
- Tom McFarlin’s “The Beginner’s Guide to WordPress Actions and Filters” on WPTuts.
- Gennady Kovshenin’s “Inside WordPress Actions And Filters” on Smashing Magazine.
3. Define the meta boxes array
When using the theme toolkit, all custom meta boxes are defined in an array. This array is passed to the toolkit using a filter. The following code adds two new custom meta boxes. The first one is added to both the post editor and the page editor. It contains examples of all the input types currently supported by the toolkit. The second meta box is displayed only on the post editor, and contains a simple text input. To give it a try, we’ll place the following code in our functions.php file:
/**
* Defines custom meta boxes array
*/
function thtk_example_meta_boxes() {
// Defines $prefix. Should begin with an underscore unless you want fields to be doubled in the Custom Fields editor.
$prefix = '_example_';
// Defines meta box array.
$meta_boxes[] = array(
'id' => 'example_meta_box',
'title' => 'Example Meta Box',
'post_type' => array( 'page', 'post' ), // Post types to display meta box.
'context' => 'normal', // Optional.
'priority' => 'high', // Optional.
'meta_box_fields' => array(
array(
'id' => $prefix . 'textbox',
'title' => 'Text box',
'type' => 'text',
'description' => 'This is an example text box.', // Optional.
'valid' => 'text' // Optional. Defaults to 'text'
),
array(
'id' => $prefix . 'textarea',
'title' => 'Text area',
'type' => 'textarea',
'description' => 'This is an example textarea', // Optional.
'valid' => 'text' // Optional. Defaults to 'text'
),
array(
'id' => $prefix . 'select',
'title' => 'Select input',
'type' => 'select',
'choices' => array('Option 1', 'Option 2', 'test'),
'description' => 'This is an example select input', // Optional.
// 'valid' property is not available for select lists.
// The options listed in the 'options' property are automatically the only valid results.
),
array(
'id' => $prefix . 'radio',
'title' => 'Radio input',
'type' => 'radio',
'choices' => array('Option 3', 'Option 4', 'test'),
'description' => 'This is an example radio input', // Optional.
// 'valid' property is not available for radio buttons.
// The options listed in the 'options' property are automatically the only valid results.
),
array(
'id' => $prefix . 'checkbox',
'title' => 'Single checkbox',
'type' => 'checkbox',
'label' => 'Check this out!',
'description' => 'This is an example text box.', // Optional.
// 'valid' property is not available for checkboxes.
// The 'label' property will be the checked box value and the only valid result.
),
array(
'id' => $prefix . 'color',
'title' => 'Color picker',
'type' => 'color',
'description' => 'This is an example color picker.', // Optional.
'valid' => 'color' // Optional. Defaults to 'text'
),
array(
'id' => $prefix . 'image',
'title' => 'Image upload',
'type' => 'image',
'description' => 'This is an example image upload.', // Optional.
'valid' => 'text' // Optional. Defaults to 'text'
),
array(
'id' => $prefix . 'file',
'title' => 'File upload',
'type' => 'file',
'description' => 'This is an example file upload.', // Optional.
'valid' => 'text' // Optional. Defaults to 'text'
),
) // End array meta_box_fields
); // End array $meta_boxes
$meta_boxes[] = array(
'id' => 'another_meta_box',
'title' => 'Another Meta Box',
'post_type' => array( 'post' ), // Post types to display meta box.
'meta_box_fields' => array(
array(
'id' => $prefix . 'another',
'title' => 'Another example',
'type' => 'text',
),
) // End array meta_box_fields
); // End array $meta_boxes
// Add other meta boxes here as needed.
return $meta_boxes;
} // End function thtk_example_meta_boxes()
add_filter( 'thtk_meta_boxes_filter', 'thtk_example_meta_boxes' );
Here we created the function that will hold the meta boxes array and attached it to the thtk_meta_boxes_filter filter hook. Inside this function we have a variable named $prefix. This is an optional variable that can be used as a prefix for the meta box IDs to ensure they are unique. Next there is an array named $meta_boxes. Each item in this array will define one custom meta box.
| id | string | The unique ID of this meta box. |
| title | string | Meta box title. |
| post_type | array | An array containing the posts types this meta box should be applied to. |
| context | string | Optional. Controls the placement of the meta box on the page. Can be set to ‘normal’, ‘advanced’, or ‘side’. Default: ‘advanced’ |
| priority | string | Optional. Controls the order in which the meta box is displayed within its context. Can be set to ‘high’, ‘core’, ‘default’ or ‘low’. Default: ‘default’ |
| meta_box_fields | array | An array of settings for all the fields that will be added to the meta box. |
Now let’s look in greater detail at the meta_box_fields array that holds the settings for the meta box fields. Each field is defined in it’s own array, with the following values.
| id | string | The unique ID of this field. |
| title | string | Field title (used as the input label for most input types). |
| type | string | The input type (text, radio, checkbox, etc.). |
| choices | array | An array of choices, used only for multiple choice input types (radio buttons and select lists). |
| label | string | Label for checkbox inputs. |
| description | string | Optional. Additional instructions regarding the input field. |
| valid | string | Optional. Used to specify sanitization requirements. Default: ‘text’. |
And there we have it! …a couple meta box examples to demonstrate the use of the theme toolkit. If you have any comments, questions, or suggestions, please let me know via twitter.