Outputs an arbitrary widget as a template tag.
Parameters
$widgetstringrequired- The widget’s PHP class name (see class-wp-widget.php).
$instancearrayoptional- The widget’s instance settings.
Default:
array() $argsarrayoptional- Array of arguments to configure the display of the widget.
before_widgetstringHTML content that will be prepended to the widget’s HTML output.
Default<div class="widget %s">, where%sis the widget’s class name.after_widgetstringHTML content that will be appended to the widget’s HTML output.
Default</div>.before_titlestringHTML content that will be prepended to the widget’s title when displayed.
Default<h2 class="widgettitle">.after_titlestringHTML content that will be appended to the widget’s title when displayed.
Default</h2>.
Default:
array()
Source
function the_widget( $widget, $instance = array(), $args = array() ) {
global $wp_widget_factory;
if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: %s: register_widget() */
__( 'Widgets need to be registered using %s, before they can be displayed.' ),
'<code>register_widget()</code>'
),
'4.9.0'
);
return;
}
$widget_obj = $wp_widget_factory->widgets[ $widget ];
if ( ! ( $widget_obj instanceof WP_Widget ) ) {
return;
}
$default_args = array(
'before_widget' => '<div class="widget %s">',
'after_widget' => '</div>',
'before_title' => '<h2 class="widgettitle">',
'after_title' => '</h2>',
);
$args = wp_parse_args( $args, $default_args );
$args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] );
$instance = wp_parse_args( $instance );
/** This filter is documented in wp-includes/class-wp-widget.php */
$instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args );
if ( false === $instance ) {
return;
}
/**
* Fires before rendering the requested widget.
*
* @since 3.0.0
*
* @param string $widget The widget's class name.
* @param array $instance The current widget instance's settings.
* @param array $args An array of the widget's sidebar arguments.
*/
do_action( 'the_widget', $widget, $instance, $args );
$widget_obj->_set( -1 );
$widget_obj->widget( $args, $instance );
}
Hooks
- do_action( ‘the_widget’,
string $widget ,array $instance ,array $args ) Fires before rendering the requested widget.
- apply_filters( ‘widget_display_callback’,
array $instance ,WP_Widget $widget ,array $args ) Filters the settings for a particular widget instance.
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
Show widget with default settings:
Show widget with settings:
Show widget with custom arguments:
Example:
This function will be showing error in the log file “Widgets need to be registered using register_widget() , before they can be displayed” if the specified widget name is not exists.
The widgets on this page can be removed by some ways even they are core widgets.
To prevent this, you need to check before call
the_widget()that widget is really regietered/exists.But sadly, currently there is no function to check it easily. However, the code below can help.
function check_widget_registered(string $widget_class_name) {
global $wp_widget_factory;
if ( ! empty( $wp_widget_factory->widgets ) && array_key_exists( $widget_class_name, $wp_widget_factory->widgets ) ) {
return true;
} else {
return false;
}
}
The code above generated by Gemini.
To use,
if (check_widget_registered('WP_Widget_Recent_Posts')) {
the_widget('WP_Widget_Recent_Posts');
}