add_meta_box( string $id, string $title, callable $callback, string|array|WP_Screen $screen = null, string $context = 'advanced', string $priority = 'default', array $callback_args = null )
Adds a meta box to one or more screens.
Description Description
Parameters Parameters
- $id
-
(string) (Required) Meta box ID (used in the 'id' attribute for the meta box).
- $title
-
(string) (Required) Title of the meta box.
- $callback
-
(callable) (Required) Function that fills the box with the desired content. The function should echo its output.
- $screen
-
(string|array|WP_Screen) (Optional) The screen or screens on which to show the box (such as a post type, 'link', or 'comment'). Accepts a single screen ID, WP_Screen object, or array of screen IDs. Default is the current screen. If you have used add_menu_page() or add_submenu_page() to create a new screen (and hence screen_id), make sure your menu slug conforms to the limits of sanitize_key() otherwise the 'screen' menu may not correctly render on your page.
Default value: null
- $context
-
(string) (Optional) The context within the screen where the boxes should display. Available contexts vary from screen to screen. Post edit screen contexts include 'normal', 'side', and 'advanced'. Comments screen contexts include 'normal' and 'side'. Menus meta boxes (accordion sections) all use the 'side' context. Global
Default value: 'advanced'
- $priority
-
(string) (Optional) The priority within the context where the boxes should show ('high', 'low').
Default value: 'default'
- $callback_args
-
(array) (Optional) Data that should be set as the $args property of the box array (which is the second parameter passed to your callback).
Default value: null
Source Source
File: wp-admin/includes/template.php
function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null ) { global $wp_meta_boxes; if ( empty( $screen ) ) { $screen = get_current_screen(); } elseif ( is_string( $screen ) ) { $screen = convert_to_screen( $screen ); } elseif ( is_array( $screen ) ) { foreach ( $screen as $single_screen ) { add_meta_box( $id, $title, $callback, $single_screen, $context, $priority, $callback_args ); } } if ( ! isset( $screen->id ) ) { return; } $page = $screen->id; if ( ! isset( $wp_meta_boxes ) ) { $wp_meta_boxes = array(); } if ( ! isset( $wp_meta_boxes[ $page ] ) ) { $wp_meta_boxes[ $page ] = array(); } if ( ! isset( $wp_meta_boxes[ $page ][ $context ] ) ) { $wp_meta_boxes[ $page ][ $context ] = array(); } foreach ( array_keys( $wp_meta_boxes[ $page ] ) as $a_context ) { foreach ( array( 'high', 'core', 'default', 'low' ) as $a_priority ) { if ( ! isset( $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] ) ) { continue; } // If a core box was previously added or removed by a plugin, don't add. if ( 'core' == $priority ) { // If core box previously deleted, don't add if ( false === $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] ) { return; } /* * If box was added with default priority, give it core priority to * maintain sort order. */ if ( 'default' == $a_priority ) { $wp_meta_boxes[ $page ][ $a_context ]['core'][ $id ] = $wp_meta_boxes[ $page ][ $a_context ]['default'][ $id ]; unset( $wp_meta_boxes[ $page ][ $a_context ]['default'][ $id ] ); } return; } // If no priority given and id already present, use existing priority. if ( empty( $priority ) ) { $priority = $a_priority; /* * Else, if we're adding to the sorted priority, we don't know the title * or callback. Grab them from the previously added context/priority. */ } elseif ( 'sorted' == $priority ) { $title = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['title']; $callback = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['callback']; $callback_args = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['args']; } // An id can be in only one priority and one context. if ( $priority != $a_priority || $context != $a_context ) { unset( $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] ); } } } if ( empty( $priority ) ) { $priority = 'low'; } if ( ! isset( $wp_meta_boxes[ $page ][ $context ][ $priority ] ) ) { $wp_meta_boxes[ $page ][ $context ][ $priority ] = array(); } $wp_meta_boxes[ $page ][ $context ][ $priority ][ $id ] = array( 'id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $callback_args, ); }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
4.4.0 | The $screen parameter now accepts an array of screen IDs. |
2.5.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Expand full source codeCollapse full source code
Class
This is an example of how to add a meta box from inside a class
Expand full source codeCollapse full source code
Expand full source codeCollapse full source code
Callback args
The
$callback_args
array will be passed to the callback function as the second argument. The first argument is the post’s$post
object.Expand full source codeCollapse full source code
This is the way to register menu screen metabox :)
Expand full source codeCollapse full source code
An often forgotten, but also very important, fact is that any
save_post
handler should check for a multisite switched context. Here’s an example of such guard:Expand full source codeCollapse full source code
That ensures compatibility with other plugins that uses
switch_to_blog()
while they are working on thesave_post
hook. If they are callingwp_insert_post()
again on other sites, your code would overwrite the wrong content without this check.Seems to me this page should reference the ‘__block_editor_compatible_meta_box’ and ‘__back_compat_meta_box’ options for $callback_args as described in this article: https://make.wordpress.org/core/2018/11/07/meta-box-compatibility-flags/
Expand full source codeCollapse full source code
Slight gotcha for comments metabox
If you need to add a metabox to the comment edit screen, you have to pass in the value ‘
normal
‘ for the$context
parameter.Expand full source codeCollapse full source code
This is how the metabox data should be processed in the
save_post
action.Expand full source codeCollapse full source code
Not only is the second parameter
$title
required. If$title
is an empty string or the string"0"
, the meta box will not be rendered.Sorry didn’t find any edit option. The last function should be declared as static:
From WordPress 4.4 the $screen arg can be an array, which greatly simplifies mass additions or alterations of meta boxes. The following code changes the title of the “Author” meta box to “Editor” on pages, posts, attachments, and all custom post types no matter how many are added or when they are added to your site.
This is how it can be called within a class:
Expand full source codeCollapse full source code
You have $screen = null in the function call but no check and balances for if it IS null. This was causing an error warning when error logging was turned on.
Expand full source codeCollapse full source code
should be replaced with..
Expand full source codeCollapse full source code
not
IMHO
Best,
Design Drumm