wp_add_dashboard_widget

Adds a new dashboard widget.

Description

wp_add_dashboard_widget( (string) $widget_id, (string) $widget_name, (callable) $callback, (constant) $control_callback = null, (null) $callback_args = null ); 

Parameters (5)

0. $widget_id (string)
Widget ID (used in the id attribute for the widget).
1. $widget_name (string)
Title of the widget.
2. $callback (callable)
Function that fills the widget with the desired content. The function should echo its output.
3. $control_callback — Optional. (constant) => null
Function that outputs controls for the widget. Default null.
4. $callback_args — Optional. (null) => null
Data that should be set as the $args property of the widget array (which is the second parameter passed to your callback). Default null.

Usage

  1. if ( !function_exists( 'wp_add_dashboard_widget' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/dashboard.php'; 
  3.  
  4. // Widget ID (used in the 'id' attribute for the widget). 
  5. $widget_id = ''; 
  6.  
  7. // Title of the widget. 
  8. $widget_name = ''; 
  9.  
  10. // Function that fills the widget with the desired content. 
  11. // The function should echo its output. 
  12. $callback = null; 
  13.  
  14. // Optional. Function that outputs controls for the widget. Default null. 
  15. $control_callback = null; 
  16.  
  17. // Optional. Data that should be set as the $args property of the widget array 
  18. // (which is the second parameter passed to your callback). Default null. 
  19. $callback_args = null; 
  20.  
  21. // NOTICE! Understand what this does before running. 
  22. $result = wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback, $callback_args); 
  23.  

Defined (1)

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

/wp-admin/includes/dashboard.php  
  1. function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null ) { 
  2. $screen = get_current_screen(); 
  3. global $wp_dashboard_control_callbacks; 
  4.  
  5. $private_callback_args = array( '__widget_basename' => $widget_name ); 
  6.  
  7. if ( is_null( $callback_args ) ) { 
  8. $callback_args = $private_callback_args; 
  9. } else if ( is_array( $callback_args ) ) { 
  10. $callback_args = array_merge( $callback_args, $private_callback_args ); 
  11.  
  12. if ( $control_callback && current_user_can( 'edit_dashboard' ) && is_callable( $control_callback ) ) { 
  13. $wp_dashboard_control_callbacks[$widget_id] = $control_callback; 
  14. if ( isset( $_GET['edit'] ) && $widget_id == $_GET['edit'] ) { 
  15. list($url) = explode( '#', add_query_arg( 'edit', false ), 2 ); 
  16. $widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( $url ) . '">' . __( 'Cancel' ) . '</a></span>'; 
  17. } else { 
  18. list($url) = explode( '#', add_query_arg( 'edit', $widget_id ), 2 ); 
  19. $widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( "$url#$widget_id" ) . '" class="edit-box open-box">' . __( 'Configure' ) . '</a></span>'; 
  20.  
  21. $side_widgets = array( 'dashboard_quick_press', 'dashboard_primary' ); 
  22.  
  23. $location = 'normal'; 
  24. if ( in_array($widget_id, $side_widgets) ) 
  25. $location = 'side'; 
  26.  
  27. $priority = 'core'; 
  28. if ( 'dashboard_browser_nag' === $widget_id ) 
  29. $priority = 'high'; 
  30.  
  31. add_meta_box( $widget_id, $widget_name, $callback, $screen, $location, $priority, $callback_args );