Understanding WordPress Custom Meta Box

By Thoriq Firdaus. in WordPress. Updated on October 18, 2022.

In the previous post, we have talked about the WordPress custom field, which allows you to add and output a new entry in a post using the Custom Field box that WordPress provides in the post editing screen. If however you are not comfortable using the custom field box (we all have our individual preferences), here’s an alternative: you can create a meta box.

A meta box is a customized box that we create on our own, which may contain input or other interactive UI to add new entries of posts or pages. You can use the meta box instead of the Custom Field box to do the same thing. Let’s see how to create one.

More on Hongkiat.com:

Creating a Meta Box

WordPress providse an API function, called add_meta_box, which lets us create a meta box straight away. This is it in its utmost basic form.

function add_post_reference() {
	add_meta_box('post-reference', 'Reference', 'referenceCallBack', 'post');
}
add_action('add_meta_boxes', 'add_post_reference');

function referenceCallBack() {
	echo 'Hello World'
}

The add_meta_box takes four parameters: the ID, the meta box title, a callback function that will call out ‘Hello World’, and the post type we want to display. In this case we assign a new meta box in a post editing page (this also works with pages).

In the post editing section, you will find a new box, as follows.

The new meta box, as you can see above, would appear below the WYSIWYG editor. If you want to add it in the sidebar you can add ‘side’ after the post parameter, and along with ‘high’ if you want to put it at the very top of the sidebar.

function add_post_reference() {
	add_meta_box('post-reference', 'Reference', 'referenceCallBack', 'post', 'side', 'high');
}
add_action('add_meta_boxes', 'add_post_reference');

You will now find it above the Publish box..

Now to replace the ‘Hello World’ text in there. Let’s add elements like an input field for a new entry.

In this example, we will add two input fields that consist of one for adding the Reference Name and another for Reference Link:

function referenceCallBack($post) {
	wp_nonce_field( 'reference_meta_box', 'reference_nonce' );

	$name_value = get_post_meta( $post->ID, '_post_reference_name', true );
	$link_value = get_post_meta( $post->ID, '_post_reference_link', true );

	echo '<label for="reference-name">'. 'Reference Name' .'</label>';
	echo '<input type="text" id="reference-name" name="post_reference_name" placeholder="Example" value="'.$name_value.'" size="25"/>';
	echo '<p class="howto">'. 'Add the name of the reference' .'</p>';

	echo '<label for="reference-link">'. 'Reference Link' .'</label>';
	echo '<input type="text" id="reference-link" name="post_reference_link" placeholder="http://www.example.com/" value="'.$link_value.'" size="25"/>';
	echo '<p class="howto">'. 'Add the link of the reference' .'</p>';
}

Refresh the post editing page, and you should see these two inputs added.

The $name_value and $link_value variable will retrieve the entries from the database and populate them into the input fields. To get the entries into the database, we will need to create a function for that.

We need to add a few lines of code that will populate the entries added through these input into the database safely. “Safely” here means a legitimate and authorized entry (not the one coming from hackers or other unauthorized personnel). To save the entry, we will have to create a new function. Let’s name the function: save_post_reference, like so.

function save_post_reference( $post_id ) {
	
}
add_action( 'save_post', 'save_post_reference' );

As we have mentioned, we need to verify a few things for security purposes:

(1) We will need to check whether the user has the ability to edit a post.

if ( ! current_user_can( 'edit_post', $post_id ) ) {
	return;
}

(2) We also need to check if the Nonce is set.

if ( ! isset( $_POST['reference_nonce'] ) ) {
	return;
}
if ( ! wp_verify_nonce( $_POST['reference_nonce'], 'reference_meta_box' ) ) {
	return;
}

(3) Then, we need to prevent the data from being auto-saved. Saving can only be done once the “Save” or “Update” button has been clicked.

if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
	return;
}

(4) We will also have to ensure that our two inputs, post_reference_name and post_reference_link, are set and ready before we submit the entries.

if ( ! isset( $_POST['post_reference_name'] ) || ! isset( $_POST['post_reference_link'] ) ) {
	return;
}

(5) And the entry should be free from any unexpected characters that may compromise website security. To check this you can use the WordPress built-in function sanitize_text_field.

$reference_name = sanitize_text_field( $_POST['post_reference_name'] );
$reference_link = sanitize_text_field( $_POST['post_reference_link'] );

Alright, now we are ready to save the entries into the database:

update_post_meta( $post_id, '_post_reference_name', $reference_name );
update_post_meta( $post_id, '_post_reference_link', $reference_link );

Now you can try it out: input some content into the input fields, and click the “Update” button to save them.

Conclusion

We have just created a meta box that comprises of two inputs. You can further extend the box with other types of inputs such as the radio button or select box. This example may be very basic but once you get the hang of it, you will be able to use this meta box for much more complicated uses. Let us know if you will be using this and what you will be using it for.