[ 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: 1766 lines (59 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

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

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.

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

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.

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

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()

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

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

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

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

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

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.

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.
since: 2.2.0
since: 5.3.0 Formalized the existing and already documented `...$params` parameter

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.

param: int|string $id Widget ID.
return: string|void Widget description, if available.
since: 2.5.0

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.

param: string $id sidebar ID.
return: string|void Sidebar description, if available.
since: 2.9.0

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

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

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

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.
since: 2.2.0
since: 5.3.0 Formalized the existing and already documented `...$params` parameter

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

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.
since: 2.8.0
since: 5.3.0 Formalized the existing and already documented `...$params` parameter

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

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.
since: 2.8.0
since: 5.3.0 Formalized the existing and already documented `...$params` parameter

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

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

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.

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

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.

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.
return: string|false False if widget is not active or id of sidebar in which the widget is active.
since: 2.2.0

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.

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

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.

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

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

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

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.

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

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

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 {
since: 2.8.0

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

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

_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.

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

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

param: array $existing_sidebars_widgets List of sidebars and their widget instance IDs.
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.

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

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.
return: array Sidebars with whitelisted widgets.
since: 4.9.0

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

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

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'.

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

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.

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.
return: array
since: 2.5.0

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 Nov 20 01:00:03 2019 Cross-referenced by PHPXref 0.7.1