Class: WP_Widget

Core base class extended to register widgets.

This class must be extended for each widget, and WP_Widget::widget() must be overridden.

If adding widget options, WP_Widget::update() and WP_Widget::form() should also be overridden.


Properties

Name Type(s) Default Value Summary
id_base mixed | string Root ID for all widgets of this type.
name string Name for this widget type.
option_name string Option name for this widget type.
alt_option_name string Alt option name for this widget type.
widget_options array Option array passed to wp_register_sidebar_widget().
control_options array Option array passed to wp_register_widget_control().
number boolean | integer Unique ID number of the current instance.
id boolean | string Unique ID string of the current instance (id_base-number).
updated boolean Whether the widget data has been updated.

Set to true when the data is updated after a POST submit - ensures it does not happen twice.


Methods

WP_Widget:: __construct( string $id_base, string $name, array $widget_options = array(), array $control_options = array() )

PHP5 constructor. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$id_base string

Optional Base ID for the widget, lowercase and unique. If left empty, a portion of the widget's class name will be used Has to be unique.

$name string

Name for the widget displayed on the configuration page.

$widget_options array

Optional. Widget options. See wp_register_sidebar_widget() for information on accepted arguments. Default empty array.

$control_options array

Optional. Widget control options. See wp_register_widget_control() for information on accepted arguments. Default empty array.


WP_Widget:: _get_display_callback( )

Retrieves the widget display callback. Since 2.8.0.

Returns

callable

Display callback.


WP_Widget:: _get_form_callback( )

Retrieves the form callback. Since 2.8.0.

Returns

callable

Form callback.


WP_Widget:: _get_update_callback( )

Retrieves the widget update callback. Since 2.8.0.

Returns

callable

Update callback.


WP_Widget:: _register( )

Register all widget instances of this widget class. Since 2.8.0.


WP_Widget:: _register_one( integer $number = -1 )

Registers an instance of the widget class. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$number integer

Optional. The unique order number of this widget instance compared to other instances of the same class. Default -1.


WP_Widget:: _set( integer $number )

Sets the internal order number for the widget instance. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$number integer

The unique order number of this widget instance compared to other instances of the same class.


WP_Widget:: display_callback( array $args, integer | array $widget_args = 1 )

Generates the actual widget content (Do NOT override). Since 2.8.0.

Finds the instance and calls WP_Widget::widget().

Arguments

Name Type(s) Default Value Description
$args array

Display arguments. See WP_Widget::widget() for information on accepted arguments.

$widget_args integer | array

{ Optional. Internal order number of the widget instance, or array of multi-widget arguments. Default 1.

@type int $number Number increment used for multiples of the same widget.

}


WP_Widget:: form( array $instance )

Outputs the settings update form. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$instance array

Current settings.

Returns

string

Default return is 'noform'.


WP_Widget:: form_callback( integer | array $widget_args = 1 )

Generates the widget control form (Do NOT override). Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$widget_args integer | array

{ Optional. Internal order number of the widget instance, or array of multi-widget arguments. Default 1.

@type int $number Number increment used for multiples of the same widget.

}

Returns

string | null


WP_Widget:: get_field_id( string $field_name )

Constructs id attributes for use in WP_Widget::form() fields. Since 2.8.0. Since 4.4.0.

This function should be used in form() methods to create id attributes for fields to be saved by WP_Widget::update().

Arguments

Name Type(s) Default Value Description
$field_name string

Field name.

Returns

string

ID attribute for $field_name.


WP_Widget:: get_field_name( string $field_name )

Constructs name attributes for use in form() fields Since 2.8.0. Since 4.4.0.

This function should be used in form() methods to create name attributes for fields to be saved by update()

Arguments

Name Type(s) Default Value Description
$field_name string

Field name

Returns

string

Name attribute for $field_name


WP_Widget:: get_settings( )

Retrieves the settings for all instances of the widget class. Since 2.8.0.

Returns

array

Multi-dimensional array of widget instance settings.


WP_Widget:: is_preview( )

Determines whether the current request is inside the Customizer preview. Since 3.9.0.

If true -- the current request is inside the Customizer preview, then the object cache gets suspended and widgets should check this to decide whether they should store anything persistently to the object cache, to transients, or anywhere else.

Returns

boolean

True if within the Customizer preview, false if not.


WP_Widget:: save_settings( array $settings )

Saves the settings for all instances of the widget class. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$settings array

Multi-dimensional array of widget instance settings.


WP_Widget:: update( array $new_instance, array $old_instance )

Updates a particular instance of a widget. Since 2.8.0.

This function should check that $new_instance is set correctly. The newly-calculated value of $instance should be returned. If false is returned, the instance won't be saved/updated.

Arguments

Name Type(s) Default Value Description
$new_instance array

New settings for this instance as input by the user via WP_Widget::form().

$old_instance array

Old settings for this instance.

Returns

array

Settings to save or bool false to cancel saving.


WP_Widget:: update_callback( integer $deprecated = 1 )

Handles changed settings (Do NOT override). Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$deprecated integer

Not used.


WP_Widget:: widget( array $args, array $instance )

Echoes the widget content. Since 2.8.0.

Sub-classes should over-ride this function to generate their widget code.

Arguments

Name Type(s) Default Value Description
$args array

Display arguments including 'before_title', 'after_title', 'before_widget', and 'after_widget'.

$instance array

The settings for the particular instance of the widget.


WP_Widget:: WP_Widget( string $id_base, string $name, array $widget_options = array(), array $control_options = array() )

PHP4 constructor. Since 2.8.0.

Arguments

Name Type(s) Default Value Description
$id_base string

Optional Base ID for the widget, lowercase and unique. If left empty, a portion of the widget's class name will be used Has to be unique.

$name string

Name for the widget displayed on the configuration page.

$widget_options array

Optional. Widget options. See wp_register_sidebar_widget() for information on accepted arguments. Default empty array.

$control_options array

Optional. Widget control options. See wp_register_widget_control() for information on accepted arguments. Default empty array.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.