wp_register_widget_control

Registers widget control callback for customizing options.

Description

wp_register_widget_control( (int|string) $id, (string) $name, (callable) $control_callback, (array) $options = array() ); 

Parameters (4)

0. $id (int|string)
Sidebar ID.
1. $name (string)
Sidebar display name.
2. $control_callback (callable)
Run when sidebar is displayed.
3. $options — Optional. (array) => array()
Array or string of control options. Default empty array.

Options

  • height (int) => 200

    Never used.

  • width (int) => 250

    Width of the fully expanded control form (but try hard to use the default width).

array(

    /**
     * Never used.
     *
     * @type int
     * @default 200
     */
    'height' => 200,

    /**
     * Width of the fully expanded control form (but try hard to use the default width).
     *
     * @type int
     * @default 250
     */
    'width' => 250
);        


Usage

  1. if ( !function_exists( 'wp_register_widget_control' ) ) { 
  2. require_once ABSPATH . WPINC . '/widgets.php'; 
  3.  
  4. // Sidebar ID. 
  5. $id = null; 
  6.  
  7. // Sidebar display name. 
  8. $name = ''; 
  9.  
  10. // Run when sidebar is displayed. 
  11. $control_callback = null; 
  12.  
  13. // Optional. Array or string of control options. Default empty array. 
  14. $options = array( 
  15. 'height' => 200, 
  16. 'width' => 250 
  17. ); 
  18.  
  19. // NOTICE! Understand what this does before running. 
  20. $result = wp_register_widget_control($id, $name, $control_callback, $options); 
  21.  

Defined (1)

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

/wp-includes/widgets.php  
  1. function wp_register_widget_control( $id, $name, $control_callback, $options = array() ) { 
  2. global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks; 
  3.  
  4. $id = strtolower($id); 
  5. $id_base = _get_widget_id_base($id); 
  6.  
  7. if ( empty($control_callback) ) { 
  8. unset($wp_registered_widget_controls[$id]); 
  9. unset($wp_registered_widget_updates[$id_base]); 
  10. return; 
  11.  
  12. if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) { 
  13. unset( $wp_registered_widgets[ $id ] ); 
  14. return; 
  15.  
  16. if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) ) 
  17. return; 
  18.  
  19. $defaults = array('width' => 250, 'height' => 200 ); // height is never used 
  20. $options = wp_parse_args($options, $defaults); 
  21. $options['width'] = (int) $options['width']; 
  22. $options['height'] = (int) $options['height']; 
  23.  
  24. $widget = array( 
  25. 'name' => $name,  
  26. 'id' => $id,  
  27. 'callback' => $control_callback,  
  28. 'params' => array_slice(func_get_args(), 4) 
  29. ); 
  30. $widget = array_merge($widget, $options); 
  31.  
  32. $wp_registered_widget_controls[$id] = $widget; 
  33.  
  34. if ( isset($wp_registered_widget_updates[$id_base]) ) 
  35. return; 
  36.  
  37. if ( isset($widget['params'][0]['number']) ) 
  38. $widget['params'][0]['number'] = -1; 
  39.  
  40. unset($widget['width'], $widget['height'], $widget['name'], $widget['id']); 
  41. $wp_registered_widget_updates[$id_base] = $widget;