wp_register_widget_control() │ WP 2.2.0

Registers a function responsible for displaying widget settings in the admin panel. Saving widget options occurs in this same function.

When registering a widget using this function, the widget can only be used once. To register a recursive widget, use the function register_widget().

No Hooks.

Returns

null. Does not return anything.

Usage

wp_register_widget_control( $id, $name, $control_callback, $options, $params,... );
$id(integer/string) (required)
ID of the widget, a unique name. For example, your_widget_1. Must match the $id of the function wp_register_sidebar_widget( $id, ... ), which registers the widget.
$name(string/string) (required)
Display name of the widget in the sidebar. Specify the same as id (I couldn't find where it is displayed)... The name (title) of the widget in the admin panel is specified in the $name parameter when registering wp_register_sidebar_widget( $id, $name, ... ).
$control_callback(callback/string) (required)
Name of the callback function that will be responsible for displaying the content of the widget in the sidebar.
$options(array)

Contains an array of the following elements: height, width’ and id_base.

  • height - never used.
  • width - this is the width of the expanded widget. If you specify, for example, 500, then when expanded, the widget will overflow the general container.
  • id_base - determined automatically. To allow the widget to be used multiple times, this parameter can be specified. It should look something like: {$id_base}-{$unique_number}. I didn't understand how to use it.

Default: array()

$params,...(mixed/string) (required)
Additional parameters that need to be passed to the widget. For example, here we can specify such strings: wp_register_widget_control( ..., $param1='foo', $param2='foo2' ); then in the $control_callback function, the parameters will be passed: $param1='foo', $param2='foo2'.

Examples

0

#1 Widget settings registration

We need to set the settings for the custom widget. The function which is responsible for outputting the widget's settings is registered as follows:

<?php
// register widget settings
wp_register_widget_control(
	'my_widget',         // id
	'my_widget',         // name
	'my_widget_control', // name of the callback function
	array('width'=>500), // width of settings block
	$param1 = 'foo' // parameter passed to my_widget_control($param1)
);

// widget settings form and save options
function my_widget_control( $param1 = array() ) {

	// if the data is sent, save it in an option
	if( isset($_POST['submitted']) ) {
		update_option('my_widget_title', $_POST['widgettitle']);
		update_option('my_widget_twitterurl', $_POST['twitterurl']);
		update_option('my_widget_description', $_POST['description']);
	}

	// Load options
	$widgettitle = get_option('my_widget_title');
	$twitterurl  = get_option('my_widget_twitterurl');
	$description = get_option('my_widget_description');
	?>

	Widget title:<br />
	<input type="text" class="widefat" name="widgettitle" value="<?php echo stripslashes($widgettitle); ?>" />
	<br /><br />

	Description:<br />
	<textarea class="widefat" rows="5" name="description"><?php echo stripslashes($description); ?></textarea>
	<br /><br />

	Twitter profile (URL):<br />
	<input type="text" class="widefat" name="twitterurl" value="<?php echo stripslashes($twitterurl); ?>" />
	<br /><br />

	<input type="hidden" name="submitted" value="1" />
	<?php
}

Notes

  • Global. Array. $wp_registered_widget_controls The registered widget controls.
  • Global. Array. $wp_registered_widget_updates The registered widget updates.
  • Global. Array. $wp_registered_widgets The registered widgets.
  • Global. Array. $_wp_deprecated_widgets_callbacks

Changelog

Since 2.2.0 Introduced.
Since 5.3.0 Formalized the existing and already documented ...$params parameter by adding it to the function signature.

wp_register_widget_control() code WP 6.9

wp-includes/widgets.php 
function wp_register_widget_control( $id, $name, $control_callback, $options = array(), ...$params ) {
	global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;

	$id      = strtolower( $id );
	$id_base = _get_widget_id_base( $id );

	if ( empty( $control_callback ) ) {
		unset( $wp_registered_widget_controls[ $id ] );
		unset( $wp_registered_widget_updates[ $id_base ] );
		return;
	}

	if ( in_array( $control_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $control_callback ) ) {
		unset( $wp_registered_widgets[ $id ] );
		return;
	}

	if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) {
		return;
	}

	$defaults          = array(
		'width'  => 250,
		'height' => 200,
	); // Height is never used.
	$options           = wp_parse_args( $options, $defaults );
	$options['width']  = (int) $options['width'];
	$options['height'] = (int) $options['height'];

	$widget = array(
		'name'     => $name,
		'id'       => $id,
		'callback' => $control_callback,
		'params'   => $params,
	);
	$widget = array_merge( $widget, $options );

	$wp_registered_widget_controls[ $id ] = $widget;

	if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) {
		return;
	}

	if ( isset( $widget['params'][0]['number'] ) ) {
		$widget['params'][0]['number'] = -1;
	}

	unset( $widget['width'], $widget['height'], $widget['name'], $widget['id'] );
	$wp_registered_widget_updates[ $id_base ] = $widget;
}

Sidebar (widgets)

Widgets (sidebars)