Adding Custom Meta Boxes to WordPress Post Editor
Posted on 16th June 2023
WordPress is a great content management system and one of its key features is the ability to add custom fields to posts and pages. This enables you to add extra data to your content which can be used to display custom information on your website or within your WordPress themes and plugins.
One popular use for custom fields is to add extra data to posts such as product prices, author information, or data that you want to be able to query and display in different ways.
In this article, we will show you how to add custom meta boxes to the WordPress post editor.
What is a Meta Box?
A meta box is a custom area where you can add extra information to a post or page. Meta boxes can be used to display custom fields, taxonomies, and other data specific to that post or page.
Meta boxes are usually displayed on the post editor screen under the post title. However, some themes and plugins display meta boxes on the sidebar of the post editor.
Creating a Custom Meta Box
Fortunately, adding a custom meta box to the WordPress post editor is not as difficult as it may seem. With a few lines of code, you can easily add a custom meta box to any post type.
The first thing you need to do is to register a new meta box using the add_meta_box() function. This function accepts seven parameters, but we will only focus on the first five.
The first parameter is the id of the meta box. This should be a unique string that is used to identify the meta box.
The second parameter is the title of the meta box. This is the title that will be displayed on the post editor screen.
The third parameter is the callback function that will be used to display the contents of the meta box. This function will be discussed in more detail later in the article.
The fourth parameter is the post type where the meta box should be displayed. This can be either a string or an array of post types.
The fifth parameter is the context where the meta box should be displayed. This can be either ‘normal’, ‘advanced’, or ‘side’. The ‘normal’ context is the default WordPress behavior and will display the meta box below the post editor. The ‘advanced’ context will display the meta box below the ‘normal’ context meta boxes. The ‘side’ context will display the meta box in the sidebar of the post editor.
The following code shows how to register a new meta box:
function wpdocs_register_meta_boxes() {
add_meta_box( 'meta-box-id', __( 'My Meta Box', 'textdomain' ), 'wpdocs_my_display_callback', 'post' );
}
add_action( 'add_meta_boxes', 'wpdocs_register_meta_boxes' );
In the code above, we are registering a new meta box with the id ‘meta-box-id’. The title of the meta box is ‘My Meta Box’ and the post type is ‘post’. The meta box will be displayed in the ‘normal’ context.
Displaying Meta Box Contents
Now that we have registered our meta box, we need to define the callback function that will be used to display the contents of the meta box.
This callback function can be defined anywhere in your plugin or theme code. However, it is a good practice to define all your callback functions in a separate file and include that file only when needed. This helps to keep your plugin or theme code clean and organized.
The callback function for our meta box is defined as follows:
function wpdocs_my_display_callback( $post ) {
// Add an nonce field so we can check for it later.
wp_nonce_field( 'wpdocs_meta_box', 'wpdocs_meta_box_nonce' );
/*
* Use get_post_meta() to retrieve an existing value
* from the database and use the value for the form.
*/
$value = get_post_meta( $post->ID, '_my_meta_value_key', true );
echo '<label for="my_meta_box_field">';
_e( 'Description for this field', 'textdomain' );
echo '</label> ';
echo '<input type="text" id="my_meta_box_field" name="my_meta_box_field" value="' . esc_attr( $value ) . '" size="25" />';
}
In the code above, we first use the wp_nonce_field() function to add a security check to our meta box. This is a recommended practice as it helps to prevent data tampering.
Next, we use the get_post_meta() function to retrieve the value of our custom field from the WordPress database. If the custom field does not exist, then the get_post_meta() function will return an empty string.
We then display a label and a text input field for our custom field. The value of the text input field is set to the value of our custom field.
Saving Meta Box Data
Once we have defined the callback function to display the contents of our meta box, we need to save the data when the post is saved.
This can be done by using the save_post hook which is triggered whenever a post is created or updated.
The following code shows how to save the data from our custom meta box:
function wpdocs_save_meta_box_data( $post_id ) {
// Verify that the nonce is valid.
if ( ! isset( $_POST['wpdocs_meta_box_nonce'] ) || ! wp_verify_nonce( $_POST['wpdocs_meta_box_nonce'], 'wpdocs_meta_box' ) ) {
return;
}
// If this is an autosave, our form has not been submitted, so we don't want to do anything.
if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
return;
}
// Check the user's permissions.
if ( isset( $_POST['post_type'] ) && 'page' == $_POST['post_type'] ) {
if ( ! current_user_can( 'edit_page', $post_id ) ) {
return;
}
} else {
if ( ! current_user_can( 'edit_post', $post_id ) ) {
return;
}
}
/* OK, it's safe for us to save the data now. */
// Make sure that it is set.
if ( ! isset( $_POST['my_meta_box_field'] ) ) {
return;
}
// Sanitize user input.
$my_data = sanitize_text_field( $_POST['my_meta_box_field'] );
// Update the meta field in the database.
update_post_meta( $post_id, '_my_meta_value_key', $my_data );
}
add_action( 'save_post', 'wpdocs_save_meta_box_data' );
In the code above, we first check if the nonce is valid and if the form has been submitted. We also check for the ‘DOING_AUTOSAVE’ constant to make sure that we are not doing an autosave.
Next, we check the user’s permissions. This is a good practice as it makes sure that only authorized users can save data to your custom fields.
If all checks have passed, then we sanitize the data and update the custom field in the WordPress database.
Displaying Meta Box Data on the Front-end
Once you have saved the data to your custom field, you can display that data on the front-end of your website.
This can be done by using the get_post_meta() function. The following code shows how to retrieve and display the data from our custom field:
// Get the value of the 'my_meta_box_field' custom field
$my_meta_box_field = get_post_meta( $post->ID, '_my_meta_value_key', true );
// If
