add_meta_box()
Adds a meta box to one or more screens.
No Hooks.
Return
null
. Nothing (null).
Usage
add_meta_box( $id, $title, $callback, $screen, $context, $priority, $callback_args );
- $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)
- 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. 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: current screen - $context(string)
- The context within the screen where the box 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 is 'advanced'.
Default: 'advanced' - $priority(string)
- The priority within the context where the box should show. Accepts 'high', 'core', 'default', or 'low'.
Default: 'default' - $callback_args(array)
- Data that should be set as the $args property of the box array (which is the second parameter passed to your callback).
Default: null
Examples
#1 Display the metabox in an custom place
This example shows how to output the metabox in an custom place: right after the header field. To do this, set your own value for the $context parameter, and then output it with the edit_form_after_title hook. You can see the whole map of hooks on the post editing page here.
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback', null, 'my_custom_context', 'high' ); add_action( 'edit_form_after_title', 'show_custom_meatbox' ); function show_custom_meatbox( $post ) { do_meta_boxes( null, 'my_custom_context', $post ); }
#2 New accordion tab (metabox in the accordion menu)
This example shows how to add an additional accordion element to the WordPress menu settings page.
<?php add_action( 'admin_head-nav-menus.php', 'register_my_meta_box_accordion_nav_menus' ); function register_my_meta_box_accordion_nav_menus() { add_meta_box( 'my-custom-meta-box', 'My metabox', 'render_my_meta_box_accordion_nav_menus', 'nav-menus', 'side' ); } function render_my_meta_box_accordion_nav_menus() { ?> <div class="my-custom-meta-box" id="my-custom-meta-box"> Metabox content </div> <?php }
We get it:
#3 PHP class
This example shows how to add an extra block in OOP-style:
#4 Accordion tab with content
Finished code that adds a new item to the navigation menu (in the accordion) and fills it, allowing you to select a media library item (files) and add it into the menu:
We get it:
Note: The base of code is taken from the file [custom-menu-panel.php] (https://gist.github.com/nikolov-tmw/8698598), found on github, which implements adding custom objects to the list.
#5 Using the $callback_args parameter
The first parameter passes post data (array $_POST).
The second has an array of $callback_args arguments.
// This function adds a Block that passes additional parameters to the // `callback` my_metabox_callback() function. function add_my_meta_box() { $var1 = "this"; $var2 = "that"; $callback_args = array( 'foo'=>$var1,'bar'=>$var2 ); add_meta_box( 'metabox_id', 'Metabox Title', 'my_metabox_callback', 'page', 'normal', 'low', $callback_args ); } // $post is an object containing data from the global array $_POST // $metabox is an array of metabox_id, title, callback // and the new passed arguments in the $callback_args parameter function my_metabox_callback( $post, $metabox ){ echo 'Last Modified: ' . $post->post_modified; // the time the post was last modified echo $metabox['args']['foo']; // once echo $metabox['args']['bar']; // two echo get_post_meta( $post->ID, 'my_custom_field', true ); // arbitrary field value }
#6 Using the anonymous function
You can pass an anonymous function as a callback function to the $callback_args parameter, for example:
add_action( 'add_meta_boxes', 'add_custom_meatbox' ); function add_custom_meatbox(){ $screens = array( 'post', 'page' ); add_meta_box( 'wpsb', __( 'Metabox title', 'my-plugin' ), function() { _e( 'Metabox content', 'my-plugin' ); }, $screens ); }
It's a little more convenient if you just need to get something out in the metabox.
#7 Metabox for posts and pages
An example of adding a custom block to the edit/create pages of posts and static pages:
// Add blocks to the main column on the post/page pages add_action( 'add_meta_boxes', 'myplugin_add_custom_box' ); // Saving data when the post is saved add_action( 'save_post', 'myplugin_save_postdata' ); function myplugin_add_custom_box(){ $screens = array( 'post', 'page' ); add_meta_box( 'myplugin_sectionid', 'Meta block name', 'myplugin_meta_box_callback', $screens ); } // HTML code of the block function myplugin_meta_box_callback( $post, $meta ){ $screens = $meta['args']; // Use nonce for verification wp_nonce_field( plugin_basename(__FILE__), 'myplugin_noncename' ); // field value $value = get_post_meta( $post->ID, 'my_meta_key', 1 ); // Form fields for entering data echo '<label for="myplugin_new_field">' . __("Description for this field", 'myplugin_textdomain' ) . '</label> '; echo '<input type="text" id="myplugin_new_field" name="myplugin_new_field" value="'. $value .'" size="25" />'; } function myplugin_save_postdata( $post_id ) { // make sure the field is set. if ( ! isset( $_POST['myplugin_new_field'] ) ) return; // check the nonce of our page, because save_post can be called from another location. if ( ! wp_verify_nonce( $_POST['myplugin_noncename'], plugin_basename(__FILE__) ) ) return; // if this is autosave do nothing if ( defined('DOING_AUTOSAVE') && DOING_AUTOSAVE ) return; // check user permission if( ! current_user_can( 'edit_post', $post_id ) ) return; // Everything is OK. Now, we need to find and save the data // clear the value of the input field. $my_data = sanitize_text_field( $_POST['myplugin_new_field'] ); // Update data in the database. update_post_meta( $post_id, 'my_meta_key', $my_data ); }
Notes
- Global. Array. $wp_meta_boxes Global meta box state.
Changelog
Since 2.5.0 | Introduced. |
Since 4.4.0 | The $screen parameter now accepts an array of screen IDs. |