the_widget() WordPress Function
The the_widget() function is used to display a particular widget in a WordPress theme. The function takes two arguments: the id of the widget to be displayed, and an array of parameters. The parameters can be used to customize the widget's appearance and behavior.
the_widget( string $widget, array $instance = array(), array $args = array() ) #
Output an arbitrary widget as a template tag.
Contents
Parameters
- $widget
(string)(Required)The widget's PHP class name (see class-wp-widget.php).
- $instance
(array)(Optional) The widget's instance settings.
Default value: array()
- $args
(array)(Optional)Array of arguments to configure the display of the widget.
- 'before_widget'
(string) HTML content that will be prepended to the widget's HTML output. Default<div class="widget %s">, where%sis the widget's class name. - 'after_widget'
(string) HTML content that will be appended to the widget's HTML output. Default</div>. - 'before_title'
(string) HTML content that will be prepended to the widget's title when displayed. Default<h2 class="widgettitle">. - 'after_title'
(string) HTML content that will be appended to the widget's title when displayed. Default</h2>.
Default value: array()
- 'before_widget'
More Information
For parameter $widget, The classes for the widgets included with WordPress are:
- WP_Widget_Archives — Archives
- WP_Widget_Calendar — Calendar
- WP_Widget_Categories — Categories
- WP_Widget_Links — Links
- WP_Widget_Meta — Meta
- WP_Widget_Pages — Pages
- WP_Widget_Recent_Comments — Recent Comments
- WP_Widget_Recent_Posts — Recent Posts
- WP_Widget_RSS — RSS
- WP_Widget_Search — Search (a search from)
- WP_Widget_Tag_Cloud — Tag Cloud
- WP_Widget_Text — Text
- WP_Nav_Menu_Widget
Archives widget
Display a monthly archive list.
<?php the_widget( 'WP_Widget_Archives', $instance, $args ); ?>
- widget’s classname:
widget_archive - instance:
- title
- The title of archive list. Default:
__('Archives') - count
- Display number of posts in each archive (1). The show_post_count parameter of wp_get_archives. Default: 0 (hide)
- dropdown
- Display as drop-down list (1). Default: 0 (an unordered list)
Examples
Default usage:
<?php the_widget( 'WP_Widget_Archives' ); ?>
Display drop-down list:
<?php the_widget( 'WP_Widget_Archives', 'dropdown=1' ); ?>
Calendar widget
Displays a Calendar.
<?php the_widget( 'WP_Widget_Calendar', $instance, $args ); ?>
- widget’s classname:
widget_calendar - instance:
- title
- The title of calendar. Default:
Example
Default usage:
<?php the_widget( 'WP_Widget_Calendar' ); ?>
Categories widget
Displays a list of categories.
<?php the_widget( 'WP_Widget_Categories', $instance, $args ); ?>
- widget’s classname:
widget_categories - instance:
- title
- The title of categories list. Default:
__( 'Categories' ) - count
- Display number of posts in each category. The show_count parameter of wp_dropdown_categories or wp_list_categories. Default: 0 (hide)
- hierarchical
- Display sub-categories as nested items inside the parent category (1). Default: 0 (in-line)
- dropdown
- Display as dropdown list (1). Default: 0 (an unordered list)
Examples
Default usage:
<?php the_widget('WP_Widget_Categories'); ?>
Display a dropdown list with number of posts.
<?php the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' ); ?>
Custom HTML widget
Displays arbitrary HTML.
<?php the_widget( 'WP_Widget_Custom_HTML', $instance, $args ); ?>
- widget’s classname:
widget_custom_html - instance:
- title
- The title for the content. Default:
- content
- arbitrary HTML. Default:
Examples
Default usage:
<?php the_widget('WP_Widget_Custom_HTML', array('title' => 'Example', 'content' => '<p>Basic example.</p>')); ?>
Links widget
Displays a list of links (blogroll) in categories.
<?php the_widget( 'WP_Widget_Links', $instance, $args ); ?>
- widget’s classname:
- instance:
- title
- The title of the Links section.
- category
- Link category IDs , separated by commas, to display. The category parameter of wp_list_bookmarks. Default: false (display all of link categories)
- description
- Display description of link (1 – true). The show_description parameter. Default: false (hide)
- rating
- Display rating of link (1- true). The show_rating parameter. Default: false (hide)
- images
- Display image of link (1 – true). The show_images parameter. Default: true (show)
- name
- If display link image, output link name to the
altattribute. The show_name parameter. Default: false
Examples
Default usage:
<?php the_widget( 'WP_Widget_Links' ); ?>
Display lists in category IDs 2 or 3:
<?php the_widget( 'WP_Widget_Links', 'category=2,3' ); ?>
Meta widget
Display site meta. (Log in/out, admin, feed and WordPress links )
<?php the_widget( 'WP_Widget_Meta', $instance, $args ); ?>
- widget’s classname:
widget_meta - instance:
- title
- The title of meta section. Default:
__( 'Meta' )
Example
Default usage:
<?php the_widget( 'WP_Widget_Meta' ); ?>
Pages widget
Display a list of Pages.
<?php the_widget( 'WP_Widget_Pages', $instance, $args ); ?>
- widget’s classname:
widget_pages - instance:
- title
- The title of Pages list. Default:
__( 'Pages' ) - sortby
- The sort_column parameter of wp_list_pages. Default:
menu_order - exclude
- Page IDs, separated by commas, to be excluded from the list. Default: null (show all of Pages)
Examples
Default usage:
the_widget( 'WP_Widget_Pages' );
Contents
as the heading, sort by last modified date:
the_widget('WP_Widget_Pages', 'title=Contents&sortby=post_modified', 'before_title=<h3>&after_title=</h3>');Recent Comments widget
Display to a list of recent comments.
<?php the_widget( 'WP_Widget_Recent_Comments', $instance, $args ); ?>
- widget’s classname:
widget_recent_comments - instance:
- title
- The title of comment list. Default:
__( 'Recent Comments' ) - number
- Number of comments to show (at most 15). Default: 5
Example
Default usage:
<?php the_widget( 'WP_Widget_Recent_Comments' ); ?>
Recent Posts widget
Display to a list of recent posts.
<?php the_widget( 'WP_Widget_Recent_Posts', $instance, $args ); ?>
- widget’s classname:
widget_recent_entries - instance:
- title
- The title of post list. Default:
__('Recent Posts') - number
- Number of posts to show (at most 15). Default: 10
Example
Default usage:
<?php the_widget( 'WP_Widget_Recent_Posts' ); ?>
RSS widget
Display a list of entries from any RSS or Atom feed.
<?php the_widget( 'WP_Widget_RSS', $instance, $args ); ?>
- widget’s classname:
- instance :
- title
- The title of list
- Default: the title inherited from the RSS or Atom feed
- url
- RSS or Atom feed URL to include.
- items
- the number of RSS or Atom items to display
- show_summary
- show_author
- show_date
Example
Default usage:
<?php the_widget( 'WP_Widget_RSS' ); ?>
Search widget
<?php the_widget( 'WP_Widget_Search', $instance, $args ); ?>
- widget’s classname:
widget_search - instance:
- title
- The title of search form. Default: null
Example
Default usage:
<?php the_widget( 'WP_Widget_Search' ); ?>
Tag Cloud widget
<?php the_widget( 'WP_Widget_Tag_Cloud', $instance, $args ); ?>
- widget’s classname:
- instance:
- title
- The title of tag cloud. default:
__( 'Tags' ) - taxonomy
- The taxonomy the cloud will draw tags from. default:
post_tag
Example
Default usage:
<?php the_widget( 'WP_Widget_Tag_Cloud' ); ?>
Text widget
<?php the_widget( 'WP_Widget_Text', $instance, $args ); ?>
- widget’s classname:
widget_text - instance:
- title
- text
- filter
Example
Default usage:
<?php the_widget( 'WP_Widget_Text' ); ?>
Custom Widget
Display custom widget in template.
<?php the_widget( 'My_Custom_Widget', $instance, $args ); ?>
- widget’s classname: WIDGET CLASS NAME (for example see below)
- instance: (optional)
- arguments: (optional)
Example
Default usage:
class My_Custom_Widget extends WP_Widget
{
/* your code* /
}
<?php the_widget( 'My_Custom_Widget' ); ?>
Source
File: wp-includes/widgets.php
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 );
}
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |