register_widget()WP 2.8.0

Register a widget Registers a WP_Widget widget

Registers a WP_Widget widget

No Hooks.

Return

null. Nothing (null).

Usage

register_widget( $widget );
$widget(string|WP_Widget) (required)
Either the name of a WP_Widget subclass or an instance of a WP_Widget subclass.

Examples

1

#1 Template for creating a widget

This code extends the WP_Widget base widget class and creates an additional widget that can be used repeatedly:

// Widget class registration
add_action( 'widgets_init', 'my_register_widgets' );

function my_register_widgets() {
	register_widget( 'My_Widget' );
}
// Widget class
class My_Widget extends WP_Widget {

	function __construct() {
		// Start the parent class
		parent::__construct(
			'widget_identifier', // widget ID, if not specified (leave ''), the ID will be equal to the name of the class in lowercase: my_widget
			'Widget name',
			array('description' => 'Widget description')
		);

		// script styles the widget only if it is active
		if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
			add_action('wp_enqueue_scripts', array( $this, 'add_my_widget_scripts' ));
			add_action('wp_head', array( $this, 'add_my_widget_style' ) );
		}
	}

	// Widget output
	function widget( $args, $instance ){
		$title = apply_filters( 'widget_title', $instance['title'] );

		echo $args['before_widget'];

		if( $title )
			echo $args['before_title'] . $title . $args['after_title'];

		echo 'Hi!';

		echo $args['after_widget'];
	}

	// Saving widget settings (clearing)
	function update( $new_instance, $old_instance ) {
	}

	// html form of widget settings in the admin panel
	function form( $instance ) {
	}

	// widget script
	function add_my_widget_scripts() {
		// filter so you can disable scripts
		if( ! apply_filters( 'show_my_widget_script', true, $this->id_base ) )
			return;

		$theme_url = get_stylesheet_directory_uri();

		wp_enqueue_script('my_widget_script', $theme_url .'/my_widget_script.js' );
	}

	// widget styles
	function add_my_widget_style() {
		// filter so you can disable styles
		if( ! apply_filters( 'show_my_widget_style', true, $this->id_base ) )
			return;
		?>
		<style>
			.my_widget a{ display:inline; }
		</style>
		<?php
	}
}
1

#2 Creating a widget with settings

This example creates a Foo_Widget widget with settings where you can specify the widget's title. Any settings can be added by analogy:

add_action( 'widgets_init', 'register_foo_widget' );

// register Foo_Widget in WordPress
function register_foo_widget() {
	register_widget( 'Foo_Widget' );
}
<?php
class Foo_Widget extends WP_Widget {

	// Widget registration using the main class
	function __construct() {
		// the constructor call looks like this:
		// __construct( $id_base, $name, $widget_options = array(), $control_options = array() )
		parent::__construct(
			'foo_widget', // widget ID, if not specified (leave ''), the ID will be equal to the class name in lowercase: foo_widget
			'Widget Header',
			('description' => 'Widget description', /*'classname' => 'my_widget',*/ )
		);

		// widget scripts/styles, only if it is active
		if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
			add_action('wp_enqueue_scripts', array( $this, 'add_my_widget_scripts' ));
			add_action('wp_head', array( $this, 'add_my_widget_style' ) );
		}
	}

	/**
	 * Widget output in the Front End
	 *
	 * @param array $args widget arguments.
	 * @param array $instance saved data from settings
	 */
	function widget( $args, $instance ) {
		$title = apply_filters( 'widget_title', $instance['title'] );

		echo $args['before_widget'];
		if ( ! empty( $title ) ) {
			echo $args['before_title'] . $title . $args['after_title'];
		}
		echo __( 'Hello, World!', 'text_domain' );
		echo $args['after_widget'];
	}

	/**
	 * The admin part of the widget
	 *
	 * @param array $instance saved data from settings
	 */
	function form( $instance ) {
		$title = @ $instance['title'] ?: 'Default title';

		?>
		<p>
			<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
			<input class="widefat" 
				id="<?php echo $this->get_field_id( 'title' ); ?>" 
				name="<?php echo $this->get_field_name( 'title' ); ?>" 
				type="text" value="<?php echo esc_attr( $title ); ?>"
			>
		</p>
		<?php
	}

	/**
	 * Saving the widget settings. Here the data must be cleared and returned to save it to the database.
	 *
	 * @see WP_Widget::update()
	 *
	 * @param array $new_instance new settings
	 * @param array $old_instance previous settings
	 *
	 * @return array data to be saved
	 */
	function update( $new_instance, $old_instance ) {
		$instance = array();
		$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';

		return $instance;
	}

	// widget script
	function add_my_widget_scripts() {
		// filter so you can disable scripts
		if( ! apply_filters( 'show_my_widget_script', true, $this->id_base ) )
			return;

		$theme_url = get_stylesheet_directory_uri();

		wp_enqueue_script('my_widget_script', $theme_url .'/my_widget_script.js' );
	}

	// widget styles
	function add_my_widget_style() {
		// filter so that you can disable styles
		if( ! apply_filters( 'show_my_widget_style', true, $this->id_base ) )
			return;
		?>
		<style type="text/css">
			.my_widget a{ display:inline; }
		</style>
		<?php
	}

}
0

#3 Popular posts widget

See here.

Notes

  • See: WP_Widget
  • Global. WP_Widget_Factory. $wp_widget_factory

Changelog

Since 2.8.0 Introduced.
Since 4.6.0 Updated the $widget parameter to also accept a WP_Widget instance object instead of simply a WP_Widget subclass name.

register_widget() code WP 6.4.3

function register_widget( $widget ) {
	global $wp_widget_factory;

	$wp_widget_factory->register( $widget );
}