add_meta_box

Adds a meta box to one or more screens.

Description

add_meta_box( (string) $id, (string) $title, (callable) $callback, (constant) $screen = null, (string) $context = 'advanced', (string) $priority = 'default', (null) $callback_args = null ); 

Parameters (7)

0. $id (string)
Meta box ID (used in the id attribute for the meta box).
1. $title (string)
Title of the meta box.
2. $callback (callable)
Function that fills the box with the desired content. The function should echo its output.
3. $screen — Optional. (constant) => null
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.
4. $context — Optional. (string) => 'advanced'
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 is advanced.
5. $priority — Optional. (string) => 'default'
The priority within the context where the boxes should show ('high', low). Default default..
6. $callback_args — Optional. (null) => null
Data that should be set as the $args property of the box array (which is the second parameter passed to your callback). Default null.

Usage

  1. if ( !function_exists( 'add_meta_box' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/template.php'; 
  3.  
  4. // Meta box ID (used in the 'id' attribute for the meta box). 
  5. $id = ''; 
  6.  
  7. // Title of the meta box. 
  8. $title = ''; 
  9.  
  10. // Function that fills the box with the desired content. 
  11. // The function should echo its output. 
  12. $callback = null; 
  13. $screen = null; 
  14. $context = 'advanced'; 
  15.  
  16. // Optional. The priority within the context where the boxes 
  17. // should show ('high', 'low'). Default 'default'. 
  18. $priority = 'default'; 
  19. $callback_args = null; 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = add_meta_box($id, $title, $callback, $screen, $context, $priority, $callback_args); 
  23.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/template.php  
  1. function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null ) { 
  2. global $wp_meta_boxes; 
  3.  
  4. if ( empty( $screen ) ) { 
  5. $screen = get_current_screen(); 
  6. } elseif ( is_string( $screen ) ) { 
  7. $screen = convert_to_screen( $screen ); 
  8. } elseif ( is_array( $screen ) ) { 
  9. foreach ( $screen as $single_screen ) { 
  10. add_meta_box( $id, $title, $callback, $single_screen, $context, $priority, $callback_args ); 
  11.  
  12. if ( ! isset( $screen->id ) ) { 
  13. return; 
  14.  
  15. $page = $screen->id; 
  16.  
  17. if ( !isset($wp_meta_boxes) ) 
  18. $wp_meta_boxes = array(); 
  19. if ( !isset($wp_meta_boxes[$page]) ) 
  20. $wp_meta_boxes[$page] = array(); 
  21. if ( !isset($wp_meta_boxes[$page][$context]) ) 
  22. $wp_meta_boxes[$page][$context] = array(); 
  23.  
  24. foreach ( array_keys($wp_meta_boxes[$page]) as $a_context ) { 
  25. foreach ( array('high', 'core', 'default', 'low') as $a_priority ) { 
  26. if ( !isset($wp_meta_boxes[$page][$a_context][$a_priority][$id]) ) 
  27. continue; 
  28.  
  29. // If a core box was previously added or removed by a plugin, don't add. 
  30. if ( 'core' == $priority ) { 
  31. // If core box previously deleted, don't add 
  32. if ( false === $wp_meta_boxes[$page][$a_context][$a_priority][$id] ) 
  33. return; 
  34.  
  35. /** 
  36. * If box was added with default priority, give it core priority to 
  37. * maintain sort order. 
  38. */ 
  39. if ( 'default' == $a_priority ) { 
  40. $wp_meta_boxes[$page][$a_context]['core'][$id] = $wp_meta_boxes[$page][$a_context]['default'][$id]; 
  41. unset($wp_meta_boxes[$page][$a_context]['default'][$id]); 
  42. return; 
  43. // If no priority given and id already present, use existing priority. 
  44. if ( empty($priority) ) { 
  45. $priority = $a_priority; 
  46. /** 
  47. * Else, if we're adding to the sorted priority, we don't know the title 
  48. * or callback. Grab them from the previously added context/priority. 
  49. */ 
  50. } elseif ( 'sorted' == $priority ) { 
  51. $title = $wp_meta_boxes[$page][$a_context][$a_priority][$id]['title']; 
  52. $callback = $wp_meta_boxes[$page][$a_context][$a_priority][$id]['callback']; 
  53. $callback_args = $wp_meta_boxes[$page][$a_context][$a_priority][$id]['args']; 
  54. // An id can be in only one priority and one context. 
  55. if ( $priority != $a_priority || $context != $a_context ) 
  56. unset($wp_meta_boxes[$page][$a_context][$a_priority][$id]); 
  57.  
  58. if ( empty($priority) ) 
  59. $priority = 'low'; 
  60.  
  61. if ( !isset($wp_meta_boxes[$page][$context][$priority]) ) 
  62. $wp_meta_boxes[$page][$context][$priority] = array(); 
  63.  
  64. $wp_meta_boxes[$page][$context][$priority][$id] = array('id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $callback_args);