Docs for page widgets.php

/wp-includes/widgets.php

Description

API for creating dynamic sidebar without hardcoding functionality into themes. Includes both internal WordPress routines and theme use routines.

This functionality was found in a plugin before WordPress 2.2 release which included it in the core from that point on.

Classes

Class	Description
WP_Widget	This class must be extended for each widget and WP_Widget::widget(), WP_Widget::update() and WP_Widget::form() need to be over-ridden.
WP_Widget_Factory	Singleton that registers and instantiates WP_Widget classes.

Variables

array $wp_registered_sidebars (line 361)

Stores the sidebars, since many themes can have more than one.

since: 2.2.0
usedby: unregister_sidebar() - Stores the new sidebar in this array by sidebar ID.
usedby: register_sidebar() - Stores the new sidebar in this array by sidebar ID.

array $wp_registered_widgets (line 369)

Stores the registered widgets.

since: 2.2.0
usedby: wp_register_sidebar_widget() - Uses stored registered widgets.

array $wp_registered_widget_controls (line 377)

Stores the registered widget control (options).

since: 2.2.0

Functions

dynamic_sidebar (line 841)

Display dynamic sidebar.

By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is not named by the theme, the actual name is '1', but 'sidebar-' is added to the registered sidebars for the name. If you named your sidebar 'after-post', then the parameter $index will still be 'after-post', but the lookup will be for 'sidebar-after-post'.

It is confusing for the $index parameter, but just know that it should just work. When you register the sidebar in the theme, you will use the same name for this function or "Pay no heed to the man behind the curtain." Just accept it as an oddity of WordPress sidebar register and display.

return: True, if widget sidebar was found and called. False if not found or not called.
since: 2.2.0

bool dynamic_sidebar ([int|string $index = 1])

int|string $index: Optional, default is 1. Name or ID of dynamic sidebar.

is_active_sidebar (line 973)

Whether a sidebar is in use.

return: true if the sidebar is in use, false otherwise.
since: 2.8

bool is_active_sidebar (mixed $index)

mixed $index: Sidebar name, id or number to check.

is_active_widget (line 922)

Whether widget is displayed on the front-end.

Either $callback or $id_base can be used $id_base is the first argument when extending WP_Widget class Without the optional $widget_id parameter, returns the ID of the first sidebar in which the first instance of the widget with the given callback or $id_base is found. With the $widget_id parameter, returns the ID of the sidebar where the widget with that callback/$id_base AND that ID is found.

NOTE: $widget_id and $id_base are the same for single widgets. To be effective this function has to run after widgets have initialized, at action 'init' or later.

return: false if widget is not active or id of sidebar in which the widget is active.
since: 2.2.0

mixed is_active_widget ([string $callback = false], [int $widget_id = false], [string $id_base = false], [bool $skip_inactive = true])

string $callback: Optional, Widget callback to check.
int $widget_id: Optional, but needed for checking. Widget ID.
string $id_base: Optional, the base ID of a widget created by extending WP_Widget.
bool $skip_inactive: Optional, whether to check in 'wp_inactive_widgets'.

is_dynamic_sidebar (line 952)

Whether the dynamic sidebar is enabled and used by theme.

return: True, if using widgets. False, if not using widgets.
since: 2.2.0

bool is_dynamic_sidebar ()

register_sidebar (line 541)

Builds the definition for a single sidebar and returns the ID.

The $args parameter takes either a string or an array with 'name' and 'id' contained in either usage. It will be noted that the values will be applied to all sidebars, so if creating more than one, it will be advised to allow for WordPress to create the defaults for you.

Example for string would be

'name=whatever;id=whatever1'

and for the array it would be

array(
'name' => 'whatever',
'id' => 'whatever1')

name - The name of the sidebar, which presumably the title which will be displayed. id - The unique identifier by which the sidebar will be called by. before_widget - The content that will prepended to the widgets when they are displayed. after_widget - The content that will be appended to the widgets when they are displayed. before_title - The content that will be prepended to the title when displayed. after_title - the content that will be appended to the title when displayed.

<em>Content</em> is assumed to be HTML and should be formatted as such, but doesn't have to be.

return: The sidebar id that was added.
since: 2.2.0
usedby: register_sidebars() - Sends single sidebar information [name, id] to this function to handle building the sidebar.
uses: $wp_registered_sidebars - Stores the new sidebar in this array by sidebar ID.
usedby: twentyten_widgets_init()

string register_sidebar ([string|array $args = array()])

string|array $args: Builds Sidebar based off of 'name' and 'id' values

register_sidebars (line 477)

Creates multiple sidebars.

If you wanted to quickly create multiple sidebars for a theme or internally. This function will allow you to do so. If you don't pass the 'name' and/or 'id' in $args, then they will be built for you.

The default for the name is "Sidebar #", with '#' being replaced with the number the sidebar is currently when greater than one. If first sidebar, the name will be just "Sidebar". The default for id is "sidebar-" followed by the number the sidebar creation is currently at. If the id is provided, and multiple sidebars are being defined, the id will have "-2" appended, and so on.

see: register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
since: 2.2.0
uses: register_sidebar() - Sends single sidebar information [name, id] to this function to handle building the sidebar.
uses: parse_str() - Converts a string to an array to be used in the rest of the function.

void register_sidebars ([int $number = 1], [string|array $args = array()])

int $number: Number of sidebars to create.
string|array $args: Builds Sidebar based off of 'name' and 'id' values.

register_widget (line 428)

Registers a WP_Widget widget

see: WP_Widget_Factory
see: WP_Widget
since: 2.8.0
uses: WP_Widget_Factory

void register_widget (string $widget_class)

string $widget_class: The name of a class that extends WP_Widget

retrieve_widgets (line 1163)

void retrieve_widgets ([ $theme_changed = false])

$theme_changed

the_widget (line 1121)

Output an arbitrary widget as a template tag

since: 2.8

void the_widget (string $widget, [array $instance = array()], [array $args = array()])

string $widget: the widget's PHP class name (see default-widgets.php)
array $instance: the widget's instance settings
array $args: the widget's sidebar args

unregister_sidebar (line 577)

Removes a sidebar from the list.

since: 2.2.0
uses: $wp_registered_sidebars - Stores the new sidebar in this array by sidebar ID.

void unregister_sidebar (string $name)

string $name: The ID of the sidebar when it was added.

unregister_widget (line 448)

Unregister a widget

Unregisters a WP_Widget widget. Useful for unregistering default widgets. Run within a function hooked to the widgets_init action.

see: WP_Widget_Factory
see: WP_Widget
since: 2.8.0
uses: WP_Widget_Factory

void unregister_widget (string $widget_class)

string $widget_class: The name of a class that extends WP_Widget

wp_convert_widget_settings (line 1060)

Convert the widget settings from single to multi-widget format.

since: 2.8.0

array wp_convert_widget_settings ( $base_name, $option_name, $settings)

$base_name
$option_name
$settings

wp_register_sidebar_widget (line 604)

The default widget option is 'classname' that can be override.

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

return: Will return if $output_callback is empty after removing widget.
since: 2.2.0
uses: $wp_register_widget_defaults - Retrieves widget defaults.
uses: $wp_registered_widgets - Uses stored registered widgets.

null wp_register_sidebar_widget (int|string $id, string $name, callback $output_callback, [array|string $options = array()], mixed $params,...)

int|string $id: Widget ID.
string $name: Widget display title.
callback $output_callback: Run when widget is called.
array|string $options: Optional. Widget Options.
mixed $params,...: Widget parameters to add to widget.

wp_register_widget_control (line 716)

Registers widget control callback for customizing options.

The options contains the 'height', 'width', and 'id_base' keys. The 'height' option is never used. The 'width' option is the width of the fully expanded control form, but try hard to use the default width. The 'id_base' is for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided. The widget id will end up looking like {$id_base}-{$unique_number}.

since: 2.2.0
usedby: wp_unregister_widget_control() - Unregisters by using empty callback.

void wp_register_widget_control (int|string $id, string $name, callback $control_callback, [array|string $options = array()], mixed $params,...)

int|string $id: Sidebar ID.
string $name: Sidebar display name.
callback $control_callback: Run when sidebar is displayed.
array|string $options: Optional. Widget options. See above long description.
mixed $params,...: Optional. Additional parameters to add to widget.

wp_sidebar_description (line 674)

Retrieve description for a sidebar.

When registering sidebars a 'description' parameter can be included that describes the sidebar for display on the widget administration panel.

return: Sidebar description, if available. Null on failure to retrieve description.
since: 2.9.0

string wp_sidebar_description (int|string $id)

int|string $id: sidebar ID.

wp_unregister_sidebar_widget (line 691)

Remove widget from sidebar.

since: 2.2.0

void wp_unregister_sidebar_widget (int|string $id)

int|string $id: Widget ID.

wp_unregister_widget_control (line 818)

Remove control callback for widget.

since: 2.2.0
uses: wp_register_widget_control() - Unregisters by using empty callback.

void wp_unregister_widget_control (int|string $id)

int|string $id: Widget ID.

wp_widget_description (line 653)

Retrieve description for widget.

When registering widgets, the options can also include 'description' that describes the widget for display on the widget administration panel or in the theme.

return: Widget description, if available. Null on failure to retrieve description.
since: 2.5.0

string wp_widget_description (int|string $id)

int|string $id: Widget ID.

_get_widget_id_base (line 1143)

Private

void _get_widget_id_base ( $id)

_register_widget_form_callback (line 781)

void _register_widget_form_callback ( $id, $name, $form_callback, [ $options = array()])

$id
$name
$form_callback
$options

_register_widget_update_callback (line 763)

void _register_widget_update_callback ( $id_base, $update_callback, [ $options = array()])

$id_base
$update_callback
$options

Documentation generated on Tue, 15 May 2012 23:18:35 +0000 by phpDocumentor 1.4.1