wp_register_widget_control() WordPress Function

The wp_register_widget_control() function allows you to display and manage controls for a widget. This function is typically used in conjunction with the_widget() function.

wp_register_widget_control( int|string $id, string $name, callable $control_callback, array $options = array(), mixed $params ) #

Registers widget control callback for customizing options.


Parameters

$id

(int|string)(Required)Sidebar ID.

$name

(string)(Required)Sidebar display name.

$control_callback

(callable)(Required)Run when sidebar is displayed.

$options

(array)(Optional)Array or string of control options.

  • 'height'
    (int) Never used. Default 200.
  • 'width'
    (int) Width of the fully expanded control form (but try hard to use the default width). Default 250.
  • 'id_base'
    (int|string) Required for multi-widgets, i.e widgets that allow multiple instances such as the text widget. The widget ID will end up looking like {$id_base}-{$unique_number}.

Default value: array()

$params

(mixed)(Optional)additional parameters to pass to the callback function when it's called.


Top ↑

Source

File: 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;
}


Top ↑

Changelog

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

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.