| [ Index ] |
PHP Cross Reference of WordPress |
[Source view] [Print] [Project Stats]
Core Widgets API This API is used for creating dynamic sidebar without hardcoding functionality into themes
| File Size: | 2107 lines (69 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
| 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() return: string Sidebar ID added to $wp_registered_sidebars global. param: array|string $args { since: 2.2.0 since: 5.6.0 Added the `before_sidebar` and `after_sidebar` arguments. since: 5.9.0 Added the `show_in_rest` argument. |
| 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. return: bool True if the sidebar is registered, false otherwise. param: string|int $sidebar_id The ID of the sidebar when it was registered. 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 since: 5.8.0 Added show_instance_in_rest option. |
| 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. param: int|string $id Widget ID. 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. return: string|void Sidebar description, if available. param: string $id sidebar ID. 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. return: bool True, if widget sidebar was found and called. False if not found or not called. param: int|string $index Optional. Index, name or ID of dynamic sidebar. Default 1. 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. return: string|false ID of the sidebar in which the widget is active, 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'. 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 otherwise. since: 2.2.0 |
| 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. return: bool True if the sidebar has widgets, false otherwise. param: string|int $index Sidebar name, id or number to check. 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. return: array Upgraded list of widgets to version 3 array format when called from the admin. param: bool $deprecated Not used (argument deprecated). since: 2.2.0 |
| wp_get_sidebar( $id ) X-Ref |
| Retrieves the registered sidebar with the given ID. return: array|null The discovered sidebar, or null if it is not registered. param: string $id The sidebar ID. since: 5.9.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 |
| Converts the widget settings from single to multi-widget format. return: array The array of widget settings converted 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. 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. return: string Widget ID base. param: string $id Widget ID. 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 |
| 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). return: array Updated sidebars widgets. param: string|bool $theme_changed Whether the theme was changed as a boolean. A value since: 2.8.0 |
| wp_map_sidebars_widgets( $existing_sidebars_widgets ) X-Ref |
| Compares a list of sidebars with their widgets against an allowed list. return: array Mapped sidebars widgets. param: array $existing_sidebars_widgets List of sidebars and their widget instance IDs. 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, $allowed_widget_ids = array() X-Ref |
| Compares a list of sidebars with their widgets against an allowed list. return: array Sidebars with allowed widgets. 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. 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. return: array param: array $widget_rss RSS widget feed data. Expects unescaped data. param: bool $check_feed Optional. Whether to check feed for errors. Default true. 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 |
| 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. since: 5.8.0 |
| 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. since: 5.8.0 |
| wp_parse_widget_id( $id ) X-Ref |
| Converts a widget ID into its id_base and number components. return: array Array containing a widget's id_base and number components. param: string $id Widget ID. since: 5.8.0 |
| wp_find_widgets_sidebar( $widget_id ) X-Ref |
| Finds the sidebar that a given widget belongs to. return: string|null The found sidebar's ID, or null if it was not found. param: string $widget_id The widget ID to look for. since: 5.8.0 |
| 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. since: 5.8.0 |
| wp_render_widget( $widget_id, $sidebar_id ) X-Ref |
| Calls the render callback of a widget and returns the output. return: string param: string $widget_id Widget ID. param: string $sidebar_id Sidebar ID. since: 5.8.0 |
| wp_render_widget_control( $id ) X-Ref |
| Calls the control callback of a widget and returns the output. return: string|null param: string $id Widget ID. since: 5.8.0 |
| 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. since: 5.8.0 |
| Generated: Thu Nov 21 01:00:03 2024 | Cross-referenced by PHPXref 0.7.1 |