wp_register_sidebar_widget( int|string $id, string $name, callable $output_callback, array $options = array(), mixed $params )

Registers an instance of a widget.

Description

The default widget option is ‘classname’ that can be overridden.

The function can also be used to un-register widgets when $output_callback parameter is an empty string.

Parameters

$idint|stringrequired

Widget ID.

$namestringrequired

Widget display title.

$output_callbackcallablerequired

Run when widget is called.

$optionsarrayoptional

An array of supplementary widget options for the instance.

classname string
Class name for the widget’s HTML container. Default is a shortened version of the output callback name.
description string
Widget description for display in the widget administration panel and/or theme.
show_instance_in_rest bool
Whether to show the widget’s instance settings in the REST API.
Only available for WP_Widget based widgets.

Default:array()

$paramsmixedoptional

Optional additional parameters to pass to the callback function when it’s called.

Source

function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) {
	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;

	$id = strtolower( $id );

	if ( empty( $output_callback ) ) {
		unset( $wp_registered_widgets[ $id ] );
		return;
	}

	$id_base = _get_widget_id_base( $id );
	if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) {
		unset( $wp_registered_widget_controls[ $id ] );
		unset( $wp_registered_widget_updates[ $id_base ] );
		return;
	}

	$defaults = array( 'classname' => $output_callback );
	$options  = wp_parse_args( $options, $defaults );
	$widget   = array(
		'name'     => $name,
		'id'       => $id,
		'callback' => $output_callback,
		'params'   => $params,
	);
	$widget   = array_merge( $widget, $options );

	if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) {

		/**
		 * Fires once for each registered widget.
		 *
		 * @since 3.0.0
		 *
		 * @param array $widget An array of default widget arguments.
		 */
		do_action( 'wp_register_sidebar_widget', $widget );
		$wp_registered_widgets[ $id ] = $widget;
	}
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_register_sidebar_widget’, array $widget ): Fires once for each registered widget.

Uses	Description
did_action()`wp-includes/plugin.php`	Retrieves the number of times an action has been fired during the current request.
_get_widget_id_base()`wp-includes/widgets.php`	Retrieves the widget ID base value.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 2 more Show less

Used by	Description
register_sidebar_widget()`wp-includes/deprecated.php`	Register widget for sidebar with backward compatibility.
WP_Widget::_register_one()`wp-includes/class-wp-widget.php`	Registers an instance of the widget class.
wp_unregister_sidebar_widget()`wp-includes/widgets.php`	Remove widget from sidebar.

Changelog

Version	Description
5.8.0	Added show_instance_in_rest option.
5.3.0	Formalized the existing and already documented `...$params` parameter by adding it to the function signature.
2.2.0	Introduced.

User Contributed Notes

Skip to note 2 content

Codex 11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
Example
The following code will create a widget called “Wpdocs Widget” which will become available in the WordPress Administrative Panels. The widget can then be dragged to an available sidebar for display.

Note that this widget can only be used once in exactly 1 of the sidebars. For recursive widgets (widgets you can add to multiple times and add to multiple sidebars) please see the Register Widget function.
```
wp_register_sidebar_widget(
	'wpdocs_widget_1',		// wpdocs unique widget id
	'Wpdocs Widget',		// widget name
	'wpdocs_widget_display',	// callback function
	array(				// options
		'description' => 'Description of what the widget does'
	)
);

/**
 * Display the wpdocs widget
 */
function wpdocs_widget_display($args) {
   echo $args['before_widget'];
   echo $args['before_title'] . 'The Wpdocs Widget' .  $args['after_title'];
   echo $args['after_widget'];
   // Print some HTML for the widget to display here.
   echo __( 'Wpdocs Widget Test', 'textdomain' );
}
```
Log in to add feedback

You must log in before being able to contribute a note or feedback.