Custom Meta Boxes | Plugin Developer Handbook | WordPress Developer Resources

• Updated on: 2023-04-28
• Read original article here

When a user edits a post, the edit screen is composed of several default boxes: Editor, Publish, Categories, Tags, etc. These boxes are meta boxes. Plugins can add custom meta boxes to an edit screen of any post type.

The content of custom meta boxes are usually HTML form elements where the user enters data related to a Plugin’s purpose, but the content can be practically any HTML you desire.

Meta boxes are handy, flexible, modular edit screen elements that can be used to collect information related to the post being edited. Your custom meta box will be on the same screen as all the other post related information; so a clear relationship is established.

Meta boxes are easily hidden from users that do not need to see them, and displayed to those that do. Meta boxes can be user-arranged on the edit screen. The users are free to arrange the edit screen in a way that suits them, giving users control over their editing environment.

All examples on this page are for illustration purposes only. The code is not suitable for production environments.

Operations such as securing input, user capabilities, nonces, and internationalization have been intentionally omitted. Be sure to always address these important operations.

To create a meta box use the add_meta_box() function and plug its execution to the action hook.

The following example is adding a meta box to the edit screen and the edit screen.

The function will hold the HTML for the meta box.

The following example is adding form elements, labels, and other HTML elements.

The example shown here only contains one form field, a drop down list. You may create as many as needed in any particular meta box. If you have a lot of fields to display, consider using multiple meta boxes, grouping similar fields together in each meta box. This helps keep the page more organized and visually appealing.

To retrieve saved user data and make use of it, you need to get it from wherever you saved it initially. If it was stored in the table, you may get the data with get_post_meta() .

The following example enhances the previous form elements with pre-populated data based on saved meta box values. You will learn how to save meta box values in the next section.

More on the selected() function.

When a post type is saved or updated, several actions fire, any of which might be appropriate to hook into in order to save the entered values. In this example we use the action hook but other hooks may be more appropriate for certain situations. Be aware that may fire more than once for a single update event. Structure your approach to saving data accordingly.

You may save the entered data anywhere you want, even outside WordPress. Since you are probably dealing with data related to the post, the table is often a good place to store data.

The following example will save the field value in the meta key, which is hidden.

In production code, remember to follow the security measures outlined in the info box!

You don’t normally need to be concerned about what happens behind the scenes. This section was added for completeness.

When a post edit screen wants to display all the meta boxes that were added to it, it calls the do_meta_boxes() function. This function loops through all meta boxes and invokes the associated with each. In between each call, intervening markup (such as divs, titles, etc.) is added.

To remove an existing meta box from an edit screen use the remove_meta_box() function. The passed parameters must exactly match those used to add the meta box with add_meta_box() .

To remove default meta boxes check the source code for the parameters used. The default add_meta_box() calls are made from .

So far we’ve been using the procedural technique of implementing meta boxes. Many plugin developers find the need to implement meta boxes using various other techniques.

Adding meta boxes using OOP is easy and saves you from having to worry about naming collisions in the global namespace. To save memory and allow easier implementation, the following example uses an abstract Class with static methods.

Since the HTML elements of the meta box are inside the tags of the edit screen, the default behavior is to parse meta box values from the super global after the user have submitted the page.

You can enhance the default experience with AJAX; this allows to perform actions based on user input and behavior; regardless if they’ve submitted the page.

First, you must define the trigger, this can be a link click, a change of a value or any other JavaScript event.

In the example below we will define as our trigger for performing an AJAX request.

Next, we need to define what we want the trigger to do, in other words we need to write our client side code.

In the example below we will make a request, the response will either be success or failure, this will indicate wither the value of the is valid.

We took the WordPress AJAX file URL dynamically from the JavaScript custom object that we will create in the next step.

Next step is to put our code into a script file and enqueue it on our edit screens.

In the example below we will add the AJAX functionality to the edit screens of the following post types: post, wporg_cpt.

The script file will reside at , being the main plugin folder, the file calling the function.

The last step is to write our server side code that is going to handle the request.

As a final reminder, the code illustrated on this page lacks important operations that take care of security. Be sure your production code includes such operations.

See Handbook’s AJAX Chapter and the Codex for more on AJAX.