[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

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: 2146 lines (71 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 42 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_get_sidebar()
  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()
  wp_setup_widgets_block_editor()
  wp_use_widgets_block_editor()
  wp_parse_widget_id()
  wp_find_widgets_sidebar()
  wp_assign_widget_to_sidebar()
  wp_render_widget()
  wp_render_widget_control()
  wp_check_widget_editor_deps()
  _wp_block_theme_register_classic_sidebars()

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.

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.

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 {

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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: callable|false $callback      Optional. Widget callback to check. Default false.
param: string|false   $widget_id     Optional. Widget ID. Optional, but needed for checking.
param: string|false   $id_base       Optional. The base ID of a widget created by extending WP_Widget.
param: bool           $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'.
return: string|false ID of the sidebar in which the widget is active,

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

is_active_sidebar( $index )   X-Ref
Determines whether a sidebar contains widgets.

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 has widgets, false otherwise.

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.

wp_get_sidebar( $id )   X-Ref
Retrieves the registered sidebar with the given ID.

param: string $id The sidebar ID.
return: array|null The discovered sidebar, or null if it is not registered.

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.

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

return: array

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

param: string $base_name   Root ID for all widgets of this type.
param: string $option_name Option name for this widget type.
param: array  $settings    The array of widget instance settings.
return: array The array of widget settings converted to multi-widget format.

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 {

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

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

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


retrieve_widgets( $theme_changed = false )   X-Ref
Validates and remaps any "orphaned" widgets to wp_inactive_widgets sidebar,
and saves the widget settings. This has to run at least on each theme change.

For example, let's say theme A has a "footer" sidebar, and theme B doesn't have one.
After switching from theme A to theme B, all the widgets previously assigned
to the footer would be inaccessible. This function detects this scenario, and
moves all the widgets previously assigned to the footer under wp_inactive_widgets.

Despite the word "retrieve" in the name, this function actually updates the database
and the global `$sidebars_widgets`. For that reason it should not be run on front end,
unless the `$theme_changed` value is 'customize' (to bypass the database write).

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

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

param: array $existing_sidebars_widgets List of sidebars and their widget instance IDs.
return: array Mapped sidebars widgets.

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

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

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.

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.

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. Whether to check feed for errors. Default true.
return: array

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.


wp_setup_widgets_block_editor()   X-Ref
Enables the widgets block editor. This is hooked into 'after_setup_theme' so
that the block editor is enabled by default but can be disabled by themes.


wp_use_widgets_block_editor()   X-Ref
Whether or not to use the block editor to manage widgets. Defaults to true
unless a theme has removed support for widgets-block-editor or a plugin has
filtered the return value of this function.

return: bool Whether to use the block editor to manage widgets.

wp_parse_widget_id( $id )   X-Ref
Converts a widget ID into its id_base and number components.

param: string $id Widget ID.
return: array Array containing a widget's id_base and number components.

wp_find_widgets_sidebar( $widget_id )   X-Ref
Finds the sidebar that a given widget belongs to.

param: string $widget_id The widget ID to look for.
return: string|null The found sidebar's ID, or null if it was not found.

wp_assign_widget_to_sidebar( $widget_id, $sidebar_id )   X-Ref
Assigns a widget to the given sidebar.

param: string $widget_id  The widget ID to assign.
param: string $sidebar_id The sidebar ID to assign to. If empty, the widget won't be added to any sidebar.

wp_render_widget( $widget_id, $sidebar_id )   X-Ref
Calls the render callback of a widget and returns the output.

param: string $widget_id Widget ID.
param: string $sidebar_id Sidebar ID.
return: string

wp_render_widget_control( $id )   X-Ref
Calls the control callback of a widget and returns the output.

param: string $id Widget ID.
return: string|null

wp_check_widget_editor_deps()   X-Ref
Displays a _doing_it_wrong() message for conflicting widget editor scripts.

The 'wp-editor' script module is exposed as window.wp.editor. This overrides
the legacy TinyMCE editor module which is required by the widgets editor.
Because of that conflict, these two shouldn't be enqueued together.
See https://core.trac.wordpress.org/ticket/53569.

There is also another conflict related to styles where the block widgets
editor is hidden if a block enqueues 'wp-edit-post' stylesheet.
See https://core.trac.wordpress.org/ticket/53569.


_wp_block_theme_register_classic_sidebars()   X-Ref
Registers the previous theme's sidebars for the block themes.




Generated : Thu Mar 28 08:20:01 2024 Cross-referenced by PHPXref