| [ 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() param: array|string $args { return: string Sidebar ID added to $wp_registered_sidebars global. 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. 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 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. 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. 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. 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: 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, 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. param: string|int $index Sidebar name, id or number to check. return: bool True if the sidebar has widgets, 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_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. 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. 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. 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 |
| 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. 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. 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, $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. 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. Whether to check feed for errors. Default true. 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 |
| 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. param: string $id Widget ID. return: array Array containing a widget's id_base and number components. since: 5.8.0 |
| 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. 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. param: string $widget_id Widget ID. param: string $sidebar_id Sidebar ID. return: string since: 5.8.0 |
| 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 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: Sun Dec 22 01:00:02 2024 | Cross-referenced by PHPXref 0.7.1 |