[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> widgets.php (summary)

Core Widgets API This API is used for creating dynamic sidebar without hardcoding functionality into themes

File Size: 1758 lines (58 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 32 functions

  register_widget()
  unregister_widget()
  register_sidebars()
  register_sidebar()
  unregister_sidebar()
  is_registered_sidebar()
  wp_register_sidebar_widget()
  wp_widget_description()
  wp_sidebar_description()
  wp_unregister_sidebar_widget()
  wp_register_widget_control()
  _register_widget_update_callback()
  _register_widget_form_callback()
  wp_unregister_widget_control()
  dynamic_sidebar()
  is_active_widget()
  is_dynamic_sidebar()
  is_active_sidebar()
  wp_get_sidebars_widgets()
  wp_set_sidebars_widgets()
  wp_get_widget_defaults()
  wp_convert_widget_settings()
  the_widget()
  _get_widget_id_base()
  _wp_sidebars_changed()
  retrieve_widgets()
  wp_map_sidebars_widgets()
  _wp_remove_unregistered_widgets()
  wp_widget_rss_output()
  wp_widget_rss_form()
  wp_widget_rss_process()
  wp_widgets_init()

Functions
Functions that are not part of a class:

register_widget( $widget )   X-Ref
Register a widget

Registers a WP_Widget widget

since: 2.8.0
since: 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
param: string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.

unregister_widget( $widget )   X-Ref
Unregisters a widget.

Unregisters a WP_Widget widget. Useful for un-registering default widgets.
Run within a function hooked to the {@see 'widgets_init'} action.

since: 2.8.0
since: 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
param: string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.

register_sidebars( $number = 1, $args = array()   X-Ref
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.

since: 2.2.0
param: int          $number Optional. Number of sidebars to create. Default 1.
param: array|string $args {

register_sidebar( $args = array()   X-Ref
Builds the definition for a single sidebar and returns the ID.

Accepts either a string or an array and then parses that against a set
of default arguments for the new sidebar. WordPress will automatically
generate a sidebar ID and name based on the current number of registered
sidebars if those arguments are not included.

When allowing for automatic generation of the name and ID parameters, keep
in mind that the incrementor for your sidebar can change over time depending
on what other plugins and themes are installed.

If theme support for 'widgets' has not yet been added when this function is
called, it will be automatically enabled through the use of add_theme_support()

return: string Sidebar ID added to $wp_registered_sidebars global.
since: 2.2.0
param: array|string $args {

unregister_sidebar( $sidebar_id )   X-Ref
Removes a sidebar from the list.

since: 2.2.0
param: string|int $sidebar_id The ID of the sidebar when it was registered.

is_registered_sidebar( $sidebar_id )   X-Ref
Checks if a sidebar is registered.

return: bool True if the sidebar is registered, false otherwise.
since: 4.4.0
param: string|int $sidebar_id The ID of the sidebar when it was registered.

wp_register_sidebar_widget( $id, $name, $output_callback, $options = array()   X-Ref
Register an instance of a widget.

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

The function can also be used to un-register widgets when `$output_callback`
parameter is an empty string.

since: 2.2.0
param: int|string $id              Widget ID.
param: string     $name            Widget display title.
param: callable   $output_callback Run when widget is called.
param: array      $options {
param: mixed      ...$params       Optional additional parameters to pass to the callback function when it's called.

wp_widget_description( $id )   X-Ref
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: string|void Widget description, if available.
since: 2.5.0
param: int|string $id Widget ID.

wp_sidebar_description( $id )   X-Ref
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: string|void Sidebar description, if available.
since: 2.9.0
param: string $id sidebar ID.

wp_unregister_sidebar_widget( $id )   X-Ref
Remove widget from sidebar.

since: 2.2.0
param: int|string $id Widget ID.

wp_register_widget_control( $id, $name, $control_callback, $options = array()   X-Ref
Registers widget control callback for customizing options.

since: 2.2.0
param: int|string $id               Sidebar ID.
param: string     $name             Sidebar display name.
param: callable   $control_callback Run when sidebar is displayed.
param: array      $options {
param: mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.

_register_widget_update_callback( $id_base, $update_callback, $options = array()   X-Ref
Registers the update callback for a widget.

since: 2.8.0
param: string   $id_base         The base ID of a widget created by extending WP_Widget.
param: callable $update_callback Update callback method for the widget.
param: array    $options         Optional. Widget control options. See wp_register_widget_control().
param: mixed    ...$params       Optional additional parameters to pass to the callback function when it's called.

_register_widget_form_callback( $id, $name, $form_callback, $options = array()   X-Ref
Registers the form callback for a widget.

since: 2.8.0
param: int|string $id            Widget ID.
param: string     $name          Name attribute for the widget.
param: callable   $form_callback Form callback.
param: array      $options       Optional. Widget control options. See wp_register_widget_control().
param: mixed      ...$params     Optional additional parameters to pass to the callback function when it's called.

wp_unregister_widget_control( $id )   X-Ref
Remove control callback for widget.

since: 2.2.0
param: int|string $id Widget ID.

dynamic_sidebar( $index = 1 )   X-Ref
Display dynamic sidebar.

By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or
'name' parameter for its registered sidebars you can pass an id or name as the $index parameter.
Otherwise, you can pass in a numerical index to display the sidebar at that index.

return: bool True, if widget sidebar was found and called. False if not found or not called.
since: 2.2.0
param: int|string $index Optional, default is 1. Index, name or ID of dynamic sidebar.

is_active_widget( $callback = false, $widget_id = false, $id_base = false, $skip_inactive = true )   X-Ref
Determines whether a given 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 {@see 'init'} or later.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

return: string|false False if widget is not active or id of sidebar in which the widget is active.
since: 2.2.0
param: string|false $callback      Optional, Widget callback to check. Default false.
param: int|false    $widget_id     Optional. Widget ID. Optional, but needed for checking. Default false.
param: string|false $id_base       Optional. The base ID of a widget created by extending WP_Widget. Default false.
param: bool         $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true.

is_dynamic_sidebar()   X-Ref
Determines whether the dynamic sidebar is enabled and used by the theme.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

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

is_active_sidebar( $index )   X-Ref
Determines whether a sidebar is in use.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

return: bool true if the sidebar is in use, false otherwise.
since: 2.8.0
param: string|int $index Sidebar name, id or number to check.

wp_get_sidebars_widgets( $deprecated = true )   X-Ref
Retrieve full list of sidebars and their widget instance IDs.

Will upgrade sidebar widget list, if needed. Will also save updated list, if
needed.

return: array Upgraded list of widgets to version 3 array format when called from the admin.
since: 2.2.0
param: bool $deprecated Not used (argument deprecated).

wp_set_sidebars_widgets( $sidebars_widgets )   X-Ref
Set the sidebar widget option to update sidebars.

since: 2.2.0
param: array $sidebars_widgets Sidebar widgets and their settings.

wp_get_widget_defaults()   X-Ref
Retrieve default registered sidebars list.

return: array
since: 2.2.0

wp_convert_widget_settings( $base_name, $option_name, $settings )   X-Ref
Convert the widget settings from single to multi-widget format.

return: array
since: 2.8.0
param: string $base_name
param: string $option_name
param: array  $settings

the_widget( $widget, $instance = array()   X-Ref
Output an arbitrary widget as a template tag.

since: 2.8.0
param: string $widget   The widget's PHP class name (see class-wp-widget.php).
param: array  $instance Optional. The widget's instance settings. Default empty array.
param: array  $args {

_get_widget_id_base( $id )   X-Ref
Retrieves the widget ID base value.

return: string Widget ID base.
since: 2.8.0
param: string $id Widget ID.

_wp_sidebars_changed()   X-Ref
Handle sidebars config after theme change

since: 3.3.0

retrieve_widgets( $theme_changed = false )   X-Ref
Look for "lost" widgets, this has to run at least on each theme change.

return: array Updated sidebars widgets.
since: 2.8.0
param: string|bool $theme_changed Whether the theme was changed as a boolean. A value

wp_map_sidebars_widgets( $existing_sidebars_widgets )   X-Ref
Compares a list of sidebars with their widgets against a whitelist.

return: array Mapped sidebars widgets.
since: 4.9.0
since: 4.9.2 Always tries to restore widget assignments from previous data, not just if sidebars needed mapping.
param: array $existing_sidebars_widgets List of sidebars and their widget instance IDs.

_wp_remove_unregistered_widgets( $sidebars_widgets, $whitelist = array()   X-Ref
Compares a list of sidebars with their widgets against a whitelist.

return: array Sidebars with whitelisted widgets.
since: 4.9.0
param: array $sidebars_widgets List of sidebars and their widget instance IDs.
param: array $whitelist        Optional. List of widget IDs to compare against. Default: Registered widgets.

wp_widget_rss_output( $rss, $args = array()   X-Ref
Display the RSS entries in a list.

since: 2.5.0
param: string|array|object $rss RSS url.
param: array $args Widget arguments.

wp_widget_rss_form( $args, $inputs = null )   X-Ref
Display RSS widget options form.

The options for what fields are displayed for the RSS form are all booleans
and are as follows: 'url', 'title', 'items', 'show_summary', 'show_author',
'show_date'.

since: 2.5.0
param: array|string $args Values for input fields.
param: array $inputs Override default display options.

wp_widget_rss_process( $widget_rss, $check_feed = true )   X-Ref
Process RSS feed widget data and optionally retrieve feed items.

The feed widget can not have more than 20 items or it will reset back to the
default, which is 10.

The resulting array has the feed title, feed url, feed link (from channel),
feed items, error (if any), and whether to show summary, author, and date.
All respectively in the order of the array elements.

return: array
since: 2.5.0
param: array $widget_rss RSS widget feed data. Expects unescaped data.
param: bool $check_feed Optional, default is true. Whether to check feed for errors.

wp_widgets_init()   X-Ref
Registers all of the default WordPress widgets on startup.

Calls {@see 'widgets_init'} action after all of the WordPress widgets have been registered.

since: 2.2.0



Generated: Wed Sep 18 01:00:03 2019 Cross-referenced by PHPXref 0.7.1