X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/7688c6ba71852cd89123b62b2d57683535e4702a..refs/tags/wordpress-4.4.1:/wp-includes/widgets.php diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index 10d1e3d9..cfc5b93c 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -1,101 +1,354 @@ register($widget_class); +} -/* Template tags & API functions */ +/** + * Unregister a widget + * + * Unregisters a WP_Widget widget. Useful for unregistering default widgets. + * Run within a function hooked to the widgets_init action. + * + * @since 2.8.0 + * + * @see WP_Widget + * + * @global WP_Widget_Factory $wp_widget_factory + * + * @param string $widget_class The name of a class that extends WP_Widget + */ +function unregister_widget($widget_class) { + global $wp_widget_factory; + + $wp_widget_factory->unregister($widget_class); +} -function register_sidebars($number = 1, $args = array()) { +/** + * 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 + * + * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here. + * + * @global array $wp_registered_sidebars + * + * @param int $number Optional. Number of sidebars to create. Default 1. + * @param array|string $args { + * Optional. Array or string of arguments for building a sidebar. + * + * @type string $id The base string of the unique identifier for each sidebar. If provided, and multiple + * sidebars are being defined, the id will have "-2" appended, and so on. + * Default 'sidebar-' followed by the number the sidebar creation is currently at. + * @type string $name The name or title for the sidebars displayed in the admin dashboard. If registering + * more than one sidebar, include '%d' in the string as a placeholder for the uniquely + * assigned number for each sidebar. + * Default 'Sidebar' for the first sidebar, otherwise 'Sidebar %d'. + * } + */ +function register_sidebars( $number = 1, $args = array() ) { + global $wp_registered_sidebars; $number = (int) $number; if ( is_string($args) ) parse_str($args, $args); - $i = 1; - - while ( $i <= $number ) { + for ( $i = 1; $i <= $number; $i++ ) { $_args = $args; - if ( $number > 1 ) { - $_args['name'] = isset($args['name']) ? $args['name'] : sprintf(__('Sidebar %d'), $i); - } else { + + if ( $number > 1 ) + $_args['name'] = isset($args['name']) ? sprintf($args['name'], $i) : sprintf(__('Sidebar %d'), $i); + else $_args['name'] = isset($args['name']) ? $args['name'] : __('Sidebar'); + + // Custom specified ID's are suffixed if they exist already. + // Automatically generated sidebar names need to be suffixed regardless starting at -0 + if ( isset($args['id']) ) { + $_args['id'] = $args['id']; + $n = 2; // Start at -2 for conflicting custom ID's + while ( is_registered_sidebar( $_args['id'] ) ) { + $_args['id'] = $args['id'] . '-' . $n++; + } + } else { + $n = count( $wp_registered_sidebars ); + do { + $_args['id'] = 'sidebar-' . ++$n; + } while ( is_registered_sidebar( $_args['id'] ) ); } - $_args['id'] = isset($args['id']) ? $args['id'] : "sidebar-$i"; register_sidebar($_args); - ++$i; } } +/** + * 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() + * + * @since 2.2.0 + * + * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID. + * + * @param array|string $args { + * Optional. Array or string of arguments for the sidebar being registered. + * + * @type string $name The name or title of the sidebar displayed in the Widgets + * interface. Default 'Sidebar $instance'. + * @type string $id The unique identifier by which the sidebar will be called. + * Default 'sidebar-$instance'. + * @type string $description Description of the sidebar, displayed in the Widgets interface. + * Default empty string. + * @type string $class Extra CSS class to assign to the sidebar in the Widgets interface. + * Default empty. + * @type string $before_widget HTML content to prepend to each widget's HTML output when + * assigned to this sidebar. Default is an opening list item element. + * @type string $after_widget HTML content to append to each widget's HTML output when + * assigned to this sidebar. Default is a closing list item element. + * @type string $before_title HTML content to prepend to the sidebar title when displayed. + * Default is an opening h2 element. + * @type string $after_title HTML content to append to the sidebar title when displayed. + * Default is a closing h2 element. + * } + * @return string Sidebar ID added to $wp_registered_sidebars global. + */ function register_sidebar($args = array()) { global $wp_registered_sidebars; - if ( is_string($args) ) - parse_str($args, $args); - $i = count($wp_registered_sidebars) + 1; + $id_is_empty = empty( $args['id'] ); + $defaults = array( 'name' => sprintf(__('Sidebar %d'), $i ), 'id' => "sidebar-$i", + 'description' => '', + 'class' => '', 'before_widget' => '
  • ', 'after_widget' => "
    • \n", 'before_title' => '

    ', 'after_title' => "

    \n", ); - $sidebar = array_merge($defaults, $args); + $sidebar = wp_parse_args( $args, $defaults ); + + if ( $id_is_empty ) { + /* translators: 1: the id argument, 2: sidebar name, 3: recommended id value */ + _doing_it_wrong( __FUNCTION__, sprintf( __( 'No %1$s was set in the arguments array for the "%2$s" sidebar. Defaulting to "%3$s". Manually set the %1$s to "%3$s" to silence this notice and keep existing sidebar content.' ), 'id', $sidebar['name'], $sidebar['id'] ), '4.2.0' ); + } $wp_registered_sidebars[$sidebar['id']] = $sidebar; + add_theme_support('widgets'); + + /** + * Fires once a sidebar has been registered. + * + * @since 3.0.0 + * + * @param array $sidebar Parsed arguments for the registered sidebar. + */ + do_action( 'register_sidebar', $sidebar ); + return $sidebar['id']; } +/** + * Removes a sidebar from the list. + * + * @since 2.2.0 + * + * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID. + * + * @param string $name The ID of the sidebar when it was added. + */ function unregister_sidebar( $name ) { global $wp_registered_sidebars; - if ( isset( $wp_registered_sidebars[$name] ) ) - unset( $wp_registered_sidebars[$name] ); + unset( $wp_registered_sidebars[ $name ] ); } -function register_sidebar_widget($name, $output_callback, $classname = '') { - // Compat - if ( is_array($name) ) { - if ( count($name) == 3 ) - $name = sprintf($name[0], $name[2]); - else - $name = $name[0]; - } - - $id = sanitize_title($name); - $options = array(); - if ( !empty($classname) && is_string($classname) ) - $options['classname'] = $classname; - $params = array_slice(func_get_args(), 2); - $args = array($id, $name, $output_callback, $options); - if ( !empty($params) ) - $args = array_merge($args, $params); +/** + * Checks if a sidebar is registered. + * + * @since 4.4.0 + * + * @global array $wp_registered_sidebars Registered sidebars. + * + * @param string|int $sidebar_id The ID of the sidebar when it was registered. + * @return bool True if the sidebar is registered, false otherwise. + */ +function is_registered_sidebar( $sidebar_id ) { + global $wp_registered_sidebars; - call_user_func_array('wp_register_sidebar_widget', $args); + return isset( $wp_registered_sidebars[ $sidebar_id ] ); } -function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) { - - global $wp_registered_widgets, $wp_register_widget_defaults; - - $id = sanitize_title($id); +/** + * 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 + * + * @global array $wp_registered_widgets Uses stored registered widgets. + * @global array $wp_register_widget_defaults Retrieves widget defaults. + * @global array $wp_registered_widget_updates + * @global array $_wp_deprecated_widgets_callbacks + * + * @param int|string $id Widget ID. + * @param string $name Widget display title. + * @param callable $output_callback Run when widget is called. + * @param array $options { + * Optional. An array of supplementary widget options for the instance. + * + * @type string $classname Class name for the widget's HTML container. Default is a shortened + * version of the output callback name. + * @type string $description Widget description for display in the widget administration + * panel and/or theme. + * } + */ +function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array() ) { + global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks; + + $id = strtolower($id); if ( empty($output_callback) ) { unset($wp_registered_widgets[$id]); return; } + $id_base = _get_widget_id_base($id); + if ( in_array($output_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($output_callback) ) { + unset( $wp_registered_widget_controls[ $id ] ); + unset( $wp_registered_widget_updates[ $id_base ] ); + return; + } + $defaults = array('classname' => $output_callback); $options = wp_parse_args($options, $defaults); $widget = array( @@ -106,66 +359,215 @@ function wp_register_sidebar_widget($id, $name, $output_callback, $options = arr ); $widget = array_merge($widget, $options); - if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || !$wp_register_widget_defaults) ) + if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) { + + /** + * Fires once for each registered widget. + * + * @since 3.0.0 + * + * @param array $widget An array of default widget arguments. + */ + do_action( 'wp_register_sidebar_widget', $widget ); $wp_registered_widgets[$id] = $widget; + } +} + +/** + * 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. + * + * @since 2.5.0 + * + * @global array $wp_registered_widgets + * + * @param int|string $id Widget ID. + * @return string|void Widget description, if available. + */ +function wp_widget_description( $id ) { + if ( !is_scalar($id) ) + return; + + global $wp_registered_widgets; + + if ( isset($wp_registered_widgets[$id]['description']) ) + return esc_html( $wp_registered_widgets[$id]['description'] ); } -function unregister_sidebar_widget($id) { - return wp_unregister_sidebar_widget($id); +/** + * 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. + * + * @since 2.9.0 + * + * @global array $wp_registered_sidebars + * + * @param string $id sidebar ID. + * @return string|void Sidebar description, if available. + */ +function wp_sidebar_description( $id ) { + if ( !is_scalar($id) ) + return; + + global $wp_registered_sidebars; + + if ( isset($wp_registered_sidebars[$id]['description']) ) + return esc_html( $wp_registered_sidebars[$id]['description'] ); } +/** + * Remove widget from sidebar. + * + * @since 2.2.0 + * + * @param int|string $id Widget ID. + */ function wp_unregister_sidebar_widget($id) { + + /** + * Fires just before a widget is removed from a sidebar. + * + * @since 3.0.0 + * + * @param int $id The widget ID. + */ + do_action( 'wp_unregister_sidebar_widget', $id ); + wp_register_sidebar_widget($id, '', ''); wp_unregister_widget_control($id); } -function register_widget_control($name, $control_callback, $width = '', $height = '') { - // Compat - if ( is_array($name) ) { - if ( count($name) == 3 ) - $name = sprintf($name[0], $name[2]); - else - $name = $name[0]; +/** + * Registers widget control callback for customizing options. + * + * The options contains the 'height', 'width', and 'id_base' keys. The 'height' + * option is never used. The 'width' option is the width of the fully expanded + * control form, but try hard to use the default width. The 'id_base' is for + * multi-widgets (widgets which allow multiple instances such as the text + * widget), an id_base must be provided. The widget id will end up looking like + * `{$id_base}-{$unique_number}`. + * + * @since 2.2.0 + * + * @todo Document `$options` as a hash notation, re: WP_Widget::__construct() cross-reference. + * @todo `$params` parameter? + * + * @global array $wp_registered_widget_controls + * @global array $wp_registered_widget_updates + * @global array $wp_registered_widgets + * @global array $_wp_deprecated_widgets_callbacks + * + * @param int|string $id Sidebar ID. + * @param string $name Sidebar display name. + * @param callable $control_callback Run when sidebar is displayed. + * @param array|string $options Optional. Widget options. See description above. Default empty array. + */ +function wp_register_widget_control( $id, $name, $control_callback, $options = array() ) { + global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks; + + $id = strtolower($id); + $id_base = _get_widget_id_base($id); + + if ( empty($control_callback) ) { + unset($wp_registered_widget_controls[$id]); + unset($wp_registered_widget_updates[$id_base]); + return; } - $id = sanitize_title($name); - $options = array(); - if ( !empty($width) ) - $options['width'] = $width; - if ( !empty($height) ) - $options['height'] = $height; - $params = array_slice(func_get_args(), 4); - $args = array($id, $name, $control_callback, $options); - if ( !empty($params) ) - $args = array_merge($args, $params); - - call_user_func_array('wp_register_widget_control', $args); + if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) { + unset( $wp_registered_widgets[ $id ] ); + return; + } + + if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) ) + return; + + $defaults = array('width' => 250, 'height' => 200 ); // height is never used + $options = wp_parse_args($options, $defaults); + $options['width'] = (int) $options['width']; + $options['height'] = (int) $options['height']; + + $widget = array( + 'name' => $name, + 'id' => $id, + 'callback' => $control_callback, + 'params' => array_slice(func_get_args(), 4) + ); + $widget = array_merge($widget, $options); + + $wp_registered_widget_controls[$id] = $widget; + + if ( isset($wp_registered_widget_updates[$id_base]) ) + return; + + if ( isset($widget['params'][0]['number']) ) + $widget['params'][0]['number'] = -1; + + unset($widget['width'], $widget['height'], $widget['name'], $widget['id']); + $wp_registered_widget_updates[$id_base] = $widget; } -function wp_register_widget_control($id, $name, $control_callback, $options = array()) { - global $wp_registered_widget_controls, $wp_register_widget_defaults; +/** + * @global array $wp_registered_widget_updates + * + * @param string $id_base + * @param callable $update_callback + * @param array $options + */ +function _register_widget_update_callback($id_base, $update_callback, $options = array()) { + global $wp_registered_widget_updates; + + if ( isset($wp_registered_widget_updates[$id_base]) ) { + if ( empty($update_callback) ) + unset($wp_registered_widget_updates[$id_base]); + return; + } + + $widget = array( + 'callback' => $update_callback, + 'params' => array_slice(func_get_args(), 3) + ); - $id = sanitize_title($id); + $widget = array_merge($widget, $options); + $wp_registered_widget_updates[$id_base] = $widget; +} - if ( empty($control_callback) ) { +/** + * + * @global array $wp_registered_widget_controls + * + * @param int|string $id + * @param string $name + * @param callable $form_callback + * @param array $options + */ +function _register_widget_form_callback($id, $name, $form_callback, $options = array()) { + global $wp_registered_widget_controls; + + $id = strtolower($id); + + if ( empty($form_callback) ) { unset($wp_registered_widget_controls[$id]); return; } - if ( isset($wp_registered_widget_controls[$id]) && $wp_register_widget_defaults ) + if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) ) return; - $defaults = array('width' => 300, 'height' => 200); + $defaults = array('width' => 250, 'height' => 200 ); $options = wp_parse_args($options, $defaults); $options['width'] = (int) $options['width']; $options['height'] = (int) $options['height']; - $options['width'] = $options['width'] > 90 ? $options['width'] + 60 : 360; - $options['height'] = $options['height'] > 60 ? $options['height'] + 40 : 240; $widget = array( 'name' => $name, 'id' => $id, - 'callback' => $control_callback, + 'callback' => $form_callback, 'params' => array_slice(func_get_args(), 4) ); $widget = array_merge($widget, $options); @@ -173,23 +575,41 @@ function wp_register_widget_control($id, $name, $control_callback, $options = ar $wp_registered_widget_controls[$id] = $widget; } -function unregister_widget_control($id) { - return wp_unregister_widget_control($id); -} - +/** + * Remove control callback for widget. + * + * @since 2.2.0 + * + * @param int|string $id Widget ID. + */ function wp_unregister_widget_control($id) { - return wp_register_widget_control($id, '', ''); + wp_register_widget_control( $id, '', '' ); } -function dynamic_sidebar($index = 1) { +/** + * 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. + * + * @since 2.2.0 + * + * @global array $wp_registered_sidebars + * @global array $wp_registered_widgets + * + * @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. + */ +function dynamic_sidebar( $index = 1 ) { global $wp_registered_sidebars, $wp_registered_widgets; - if ( is_int($index) ) { + if ( is_int( $index ) ) { $index = "sidebar-$index"; } else { - $index = sanitize_title($index); - foreach ( $wp_registered_sidebars as $key => $value ) { - if ( sanitize_title($value['name']) == $index ) { + $index = sanitize_title( $index ); + foreach ( (array) $wp_registered_sidebars as $key => $value ) { + if ( sanitize_title( $value['name'] ) == $index ) { $index = $key; break; } @@ -197,17 +617,39 @@ function dynamic_sidebar($index = 1) { } $sidebars_widgets = wp_get_sidebars_widgets(); + if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { + /** This action is documented in wp-includes/widget.php */ + do_action( 'dynamic_sidebar_before', $index, false ); + /** This action is documented in wp-includes/widget.php */ + do_action( 'dynamic_sidebar_after', $index, false ); + /** This filter is documented in wp-includes/widget.php */ + return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); + } - if ( empty($wp_registered_sidebars[$index]) || !is_array($sidebars_widgets[$index]) || empty($sidebars_widgets[$index]) ) - return false; - + /** + * Fires before widgets are rendered in a dynamic sidebar. + * + * Note: The action also fires for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param int|string $index Index, name, or ID of the dynamic sidebar. + * @param bool $has_widgets Whether the sidebar is populated with widgets. + * Default true. + */ + do_action( 'dynamic_sidebar_before', $index, true ); $sidebar = $wp_registered_sidebars[$index]; $did_one = false; - foreach ( $sidebars_widgets[$index] as $id ) { - $callback = $wp_registered_widgets[$id]['callback']; + foreach ( (array) $sidebars_widgets[$index] as $id ) { + + if ( !isset($wp_registered_widgets[$id]) ) continue; - $params = array_merge(array($sidebar), (array) $wp_registered_widgets[$id]['params']); + $params = array_merge( + array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ), + (array) $wp_registered_widgets[$id]['params'] + ); // Substitute HTML id and class attributes into before_widget $classname_ = ''; @@ -220,34 +662,167 @@ function dynamic_sidebar($index = 1) { $classname_ = ltrim($classname_, '_'); $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_); + /** + * Filter the parameters passed to a widget's display callback. + * + * Note: The filter is evaluated on both the front-end and back-end, + * including for the Inactive Widgets sidebar on the Widgets screen. + * + * @since 2.5.0 + * + * @see register_sidebar() + * + * @param array $params { + * @type array $args { + * An array of widget display arguments. + * + * @type string $name Name of the sidebar the widget is assigned to. + * @type string $id ID of the sidebar the widget is assigned to. + * @type string $description The sidebar description. + * @type string $class CSS class applied to the sidebar container. + * @type string $before_widget HTML markup to prepend to each widget in the sidebar. + * @type string $after_widget HTML markup to append to each widget in the sidebar. + * @type string $before_title HTML markup to prepend to the widget title when displayed. + * @type string $after_title HTML markup to append to the widget title when displayed. + * @type string $widget_id ID of the widget. + * @type string $widget_name Name of the widget. + * } + * @type array $widget_args { + * An array of multi-widget arguments. + * + * @type int $number Number increment used for multiples of the same widget. + * } + * } + */ + $params = apply_filters( 'dynamic_sidebar_params', $params ); + + $callback = $wp_registered_widgets[$id]['callback']; + + /** + * Fires before a widget's display callback is called. + * + * Note: The action fires on both the front-end and back-end, including + * for widgets in the Inactive Widgets sidebar on the Widgets screen. + * + * The action is not fired for empty sidebars. + * + * @since 3.0.0 + * + * @param array $widget_id { + * An associative array of widget arguments. + * + * @type string $name Name of the widget. + * @type string $id Widget ID. + * @type array|callable $callback When the hook is fired on the front-end, $callback is an array + * containing the widget object. Fired on the back-end, $callback + * is 'wp_widget_control', see $_callback. + * @type array $params An associative array of multi-widget arguments. + * @type string $classname CSS class applied to the widget container. + * @type string $description The widget description. + * @type array $_callback When the hook is fired on the back-end, $_callback is populated + * with an array containing the widget object, see $callback. + * } + */ + do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); + if ( is_callable($callback) ) { call_user_func_array($callback, $params); $did_one = true; } } - return $did_one; + /** + * Fires after widgets are rendered in a dynamic sidebar. + * + * Note: The action also fires for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param int|string $index Index, name, or ID of the dynamic sidebar. + * @param bool $has_widgets Whether the sidebar is populated with widgets. + * Default true. + */ + do_action( 'dynamic_sidebar_after', $index, true ); + + /** + * Filter whether a sidebar has widgets. + * + * Note: The filter is also evaluated for empty sidebars, and on both the front-end + * and back-end, including the Inactive Widgets sidebar on the Widgets screen. + * + * @since 3.9.0 + * + * @param bool $did_one Whether at least one widget was rendered in the sidebar. + * Default false. + * @param int|string $index Index, name, or ID of the dynamic sidebar. + */ + return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index ); } -function is_active_widget($callback) { +/** + * Whether 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 'init' or later. + * + * @since 2.2.0 + * + * @global array $wp_registered_widgets + * + * @param string $callback Optional, Widget callback to check. + * @param int $widget_id Optional, but needed for checking. Widget ID. + * @param string $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 False if widget is not active or id of sidebar in which the widget is active. + */ +function is_active_widget($callback = false, $widget_id = false, $id_base = false, $skip_inactive = true) { global $wp_registered_widgets; - $sidebars_widgets = wp_get_sidebars_widgets(false); + $sidebars_widgets = wp_get_sidebars_widgets(); - if ( is_array($sidebars_widgets) ) foreach ( $sidebars_widgets as $sidebar => $widgets ) - if ( is_array($widgets) ) foreach ( $widgets as $widget ) - if ( $wp_registered_widgets[$widget]['callback'] == $callback ) - return true; + if ( is_array($sidebars_widgets) ) { + foreach ( $sidebars_widgets as $sidebar => $widgets ) { + if ( $skip_inactive && ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) ) { + continue; + } + if ( is_array($widgets) ) { + foreach ( $widgets as $widget ) { + if ( ( $callback && isset($wp_registered_widgets[$widget]['callback']) && $wp_registered_widgets[$widget]['callback'] == $callback ) || ( $id_base && _get_widget_id_base($widget) == $id_base ) ) { + if ( !$widget_id || $widget_id == $wp_registered_widgets[$widget]['id'] ) + return $sidebar; + } + } + } + } + } return false; } +/** + * Whether the dynamic sidebar is enabled and used by theme. + * + * @since 2.2.0 + * + * @global array $wp_registered_widgets + * @global array $wp_registered_sidebars + * + * @return bool True, if using widgets. False, if not using widgets. + */ function is_dynamic_sidebar() { global $wp_registered_widgets, $wp_registered_sidebars; $sidebars_widgets = get_option('sidebars_widgets'); - foreach ( $wp_registered_sidebars as $index => $sidebar ) { + foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) { if ( count($sidebars_widgets[$index]) ) { - foreach ( $sidebars_widgets[$index] as $widget ) + foreach ( (array) $sidebars_widgets[$index] as $widget ) if ( array_key_exists($widget, $wp_registered_widgets) ) return true; } @@ -255,915 +830,635 @@ function is_dynamic_sidebar() { return false; } -/* Internal Functions */ - -function wp_get_sidebars_widgets($update = true) { - global $wp_registered_widgets, $wp_registered_sidebars; - - $sidebars_widgets = get_option('sidebars_widgets'); - $_sidebars_widgets = array(); - - if ( !isset($sidebars_widgets['array_version']) ) - $sidebars_widgets['array_version'] = 1; - - switch ( $sidebars_widgets['array_version'] ) { - case 1 : - foreach ( $sidebars_widgets as $index => $sidebar ) - if ( is_array($sidebar) ) - foreach ( $sidebar as $i => $name ) { - $id = strtolower($name); - if ( isset($wp_registered_widgets[$id]) ) { - $_sidebars_widgets[$index][$i] = $id; - continue; - } - $id = sanitize_title($name); - if ( isset($wp_registered_widgets[$id]) ) { - $_sidebars_widgets[$index][$i] = $id; - continue; - } - unset($_sidebars_widgets[$index][$i]); - } - $_sidebars_widgets['array_version'] = 2; - $sidebars_widgets = $_sidebars_widgets; - unset($_sidebars_widgets); - - case 2 : - $sidebars = array_keys( $wp_registered_sidebars ); - if ( !empty( $sidebars ) ) { - // Move the known-good ones first - foreach ( $sidebars as $id ) { - if ( array_key_exists( $id, $sidebars_widgets ) ) { - $_sidebars_widgets[$id] = $sidebars_widgets[$id]; - unset($sidebars_widgets[$id], $sidebars[$id]); - } - } - - // Assign to each unmatched registered sidebar the first available orphan - unset( $sidebars_widgets[ 'array_version' ] ); - while ( ( $sidebar = array_shift( $sidebars ) ) && $widgets = array_shift( $sidebars_widgets ) ) - $_sidebars_widgets[ $sidebar ] = $widgets; - - $_sidebars_widgets['array_version'] = 3; - $sidebars_widgets = $_sidebars_widgets; - unset($_sidebars_widgets); - } +/** + * Whether a sidebar is in use. + * + * @since 2.8.0 + * + * @param string|int $index Sidebar name, id or number to check. + * @return bool true if the sidebar is in use, false otherwise. + */ +function is_active_sidebar( $index ) { + $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index); + $sidebars_widgets = wp_get_sidebars_widgets(); + $is_active_sidebar = ! empty( $sidebars_widgets[$index] ); + + /** + * Filter whether a dynamic sidebar is considered "active". + * + * @since 3.9.0 + * + * @param bool $is_active_sidebar Whether or not the sidebar should be considered "active". + * In other words, whether the sidebar contains any widgets. + * @param int|string $index Index, name, or ID of the dynamic sidebar. + */ + return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index ); +} - if ( $update ) - update_option('sidebars_widgets', $sidebars_widgets); +// +// Internal Functions +// + +/** + * Retrieve full list of sidebars and their widget instance IDs. + * + * Will upgrade sidebar widget list, if needed. Will also save updated list, if + * needed. + * + * @since 2.2.0 + * @access private + * + * @global array $_wp_sidebars_widgets + * @global array $sidebars_widgets + * + * @param bool $deprecated Not used (argument deprecated). + * @return array Upgraded list of widgets to version 3 array format when called from the admin. + */ +function wp_get_sidebars_widgets( $deprecated = true ) { + if ( $deprecated !== true ) + _deprecated_argument( __FUNCTION__, '2.8.1' ); + + global $_wp_sidebars_widgets, $sidebars_widgets; + + // If loading from front page, consult $_wp_sidebars_widgets rather than options + // to see if wp_convert_widget_settings() has made manipulations in memory. + if ( !is_admin() ) { + if ( empty($_wp_sidebars_widgets) ) + $_wp_sidebars_widgets = get_option('sidebars_widgets', array()); + + $sidebars_widgets = $_wp_sidebars_widgets; + } else { + $sidebars_widgets = get_option('sidebars_widgets', array()); } - unset($sidebars_widgets['array_version']); - - return $sidebars_widgets; + if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) ) + unset($sidebars_widgets['array_version']); + + /** + * Filter the list of sidebars and their widgets. + * + * @since 2.7.0 + * + * @param array $sidebars_widgets An associative array of sidebars and their widgets. + */ + return apply_filters( 'sidebars_widgets', $sidebars_widgets ); } +/** + * Set the sidebar widget option to update sidebars. + * + * @since 2.2.0 + * @access private + * + * @param array $sidebars_widgets Sidebar widgets and their settings. + */ function wp_set_sidebars_widgets( $sidebars_widgets ) { + if ( !isset( $sidebars_widgets['array_version'] ) ) + $sidebars_widgets['array_version'] = 3; update_option( 'sidebars_widgets', $sidebars_widgets ); } +/** + * Retrieve default registered sidebars list. + * + * @since 2.2.0 + * @access private + * + * @global array $wp_registered_sidebars + * + * @return array + */ function wp_get_widget_defaults() { global $wp_registered_sidebars; $defaults = array(); - foreach ( $wp_registered_sidebars as $index => $sidebar ) + foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) $defaults[$index] = array(); return $defaults; } -/* Default Widgets */ - -function wp_widget_pages( $args ) { - extract( $args ); - $options = get_option( 'widget_pages' ); - - $title = empty( $options['title'] ) ? __( 'Pages' ) : $options['title']; - $sortby = empty( $options['sortby'] ) ? 'menu_order' : $options['sortby']; - $exclude = empty( $options['exclude'] ) ? '' : $options['exclude']; - - if ( $sortby == 'menu_order' ) { - $sortby = 'menu_order, post_title'; - } - - $out = wp_list_pages( array('title_li' => '', 'echo' => 0, 'sort_column' => $sortby, 'exclude' => $exclude) ); - - if ( !empty( $out ) ) { -?> - - - - - $settings ); - if ( in_array( $sortby, array( 'post_title', 'menu_order', 'ID' ) ) ) { - $newoptions['sortby'] = $sortby; + // If loading from the front page, update sidebar in memory but don't save to options + if ( is_admin() ) { + $sidebars_widgets = get_option('sidebars_widgets'); } else { - $newoptions['sortby'] = 'menu_order'; + if ( empty($GLOBALS['_wp_sidebars_widgets']) ) + $GLOBALS['_wp_sidebars_widgets'] = get_option('sidebars_widgets', array()); + $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets']; } - $newoptions['exclude'] = strip_tags( stripslashes( $_POST['pages-exclude'] ) ); - } - if ( $options != $newoptions ) { - $options = $newoptions; - update_option('widget_pages', $options); - } - $title = attribute_escape($options['title']); - $exclude = attribute_escape( $options['exclude'] ); -?> -

    -

    -


    -

    - - $before_title, 'title_after' => $after_title, - 'category_before' => $before_widget, 'category_after' => $after_widget, - 'show_images' => true, 'class' => 'linkcat widget' - )); -} - -function wp_widget_search($args) { - extract($args); -?> - -
    -
    -
    - -
    -
    - - $sidebar ) { + if ( is_array($sidebar) ) { + foreach ( $sidebar as $i => $name ) { + if ( $base_name == $name ) { + $sidebars_widgets[$index][$i] = "$name-2"; + $changed = true; + break 2; + } + } + } + } - if($d) { -?> - - - - -

    -

    -

    - - - - - - - -

    - -'; - get_calendar(); - echo ''; - echo $after_widget; -} -function wp_widget_calendar_control() { - $options = $newoptions = get_option('widget_calendar'); - if ( $_POST["calendar-submit"] ) { - $newoptions['title'] = strip_tags(stripslashes($_POST["calendar-title"])); - } - if ( $options != $newoptions ) { - $options = $newoptions; - update_option('widget_calendar', $options); +/** + * Output an arbitrary widget as a template tag. + * + * @since 2.8.0 + * + * @global WP_Widget_Factory $wp_widget_factory + * + * @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 { + * Optional. Array of arguments to configure the display of the widget. + * + * @type string $before_widget HTML content that will be prepended to the widget's HTML output. + * Default `
    `, where `%s` is the widget's class name. + * @type string $after_widget HTML content that will be appended to the widget's HTML output. + * Default `
    `. + * @type string $before_title HTML content that will be prepended to the widget's title when displayed. + * Default `

    `. + * @type string $after_title HTML content that will be appended to the widget's title when displayed. + * Default `

    `. + * } + */ +function the_widget( $widget, $instance = array(), $args = array() ) { + global $wp_widget_factory; + + $widget_obj = $wp_widget_factory->widgets[$widget]; + if ( ! ( $widget_obj instanceof WP_Widget ) ) { + return; } - $title = attribute_escape($options['title']); -?> -

    - - - - -
    - - '
    ', + 'after_widget' => "
    ", + 'before_title' => '

    ', + 'after_title' => '

    ', + ); + $args = wp_parse_args( $args, $default_args ); + $args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] ); + + $instance = wp_parse_args($instance); + + /** + * Fires before rendering the requested widget. + * + * @since 3.0.0 + * + * @param string $widget The widget's class name. + * @param array $instance The current widget instance's settings. + * @param array $args An array of the widget's sidebar arguments. + */ + do_action( 'the_widget', $widget, $instance, $args ); + + $widget_obj->_set(-1); + $widget_obj->widget($args, $instance); } -function wp_widget_text_control($number) { - $options = $newoptions = get_option('widget_text'); - if ( !is_array($options) ) - $options = $newoptions = array(); - if ( $_POST["text-submit-$number"] ) { - $newoptions[$number]['title'] = strip_tags(stripslashes($_POST["text-title-$number"])); - $newoptions[$number]['text'] = stripslashes($_POST["text-text-$number"]); - if ( !current_user_can('unfiltered_html') ) - $newoptions[$number]['text'] = stripslashes(wp_filter_post_kses($newoptions[$number]['text'])); - } - if ( $options != $newoptions ) { - $options = $newoptions; - update_option('widget_text', $options); - } - $title = attribute_escape($options[$number]['title']); - $text = format_to_edit($options[$number]['text']); -?> - - - " name="text-submit-" value="1" /> - 9 ) $number = 9; - if ( $number < 1 ) $number = 1; - $newoptions['number'] = $number; - } - if ( $options != $newoptions ) { - $options = $newoptions; - update_option('widget_text', $options); - wp_widget_text_register($options['number']); - } +/** + * Handle sidebars config after theme change + * + * @access private + * @since 3.3.0 + * + * @global array $sidebars_widgets + */ +function _wp_sidebars_changed() { + global $sidebars_widgets; + + if ( ! is_array( $sidebars_widgets ) ) + $sidebars_widgets = wp_get_sidebars_widgets(); + + retrieve_widgets(true); } -function wp_widget_text_page() { - $options = $newoptions = get_option('widget_text'); -?> -
    -
    -

    -

    - -

    -
    -
    - 9 ) $number = 9; - $dims = array('width' => 460, 'height' => 350); - $class = array('classname' => 'widget_text'); - for ($i = 1; $i <= 9; $i++) { - $name = sprintf(__('Text %d'), $i); - $id = "text-$i"; // Never never never translate an id - wp_register_sidebar_widget($id, $name, $i <= $number ? 'wp_widget_text' : /* unregister */ '', $class, $i); - wp_register_widget_control($id, $name, $i <= $number ? 'wp_widget_text_control' : /* unregister */ '', $dims, $i); - } - add_action('sidebar_admin_setup', 'wp_widget_text_setup'); - add_action('sidebar_admin_page', 'wp_widget_text_page'); -} + foreach ( $_sidebars_widgets as $sidebar => $widgets ) { + if ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { + continue; + } -function wp_widget_categories($args, $number = 1) { - extract($args); - $options = get_option('widget_categories'); + if ( !in_array( $sidebar, $registered_sidebar_keys ) ) { + $_sidebars_widgets['orphaned_widgets_' . ++$orphaned] = $widgets; + unset( $_sidebars_widgets[$sidebar] ); + } + } + } else { + if ( empty( $sidebars_widgets ) ) + return; - $c = $options[$number]['count'] ? '1' : '0'; - $h = $options[$number]['hierarchical'] ? '1' : '0'; - $d = $options[$number]['dropdown'] ? '1' : '0'; + unset( $sidebars_widgets['array_version'] ); - $title = empty($options[$number]['title']) ? __('Categories') : $options[$number]['title']; + $old = array_keys($sidebars_widgets); + sort($old); + sort($registered_sidebar_keys); - echo $before_widget; - echo $before_title . $title . $after_title; + if ( $old == $registered_sidebar_keys ) + return; - $cat_args = "orderby=name&show_count={$c}&hierarchical={$h}"; + $_sidebars_widgets = array( + 'wp_inactive_widgets' => !empty( $sidebars_widgets['wp_inactive_widgets'] ) ? $sidebars_widgets['wp_inactive_widgets'] : array() + ); - if ( $d ) { - wp_dropdown_categories($cat_args . '&show_option_none= ' . __('Select Category')); -?> + unset( $sidebars_widgets['wp_inactive_widgets'] ); - - - - $widgets ) { + if ( !is_array($widgets) ) + continue; - if ( !is_array( $options ) ) { - $options = $newoptions = get_option( 'widget_categories' ); - } - - if ( $_POST['categories-submit-' . $number] ) { - $newoptions[$number]['count'] = isset($_POST['categories-count-' . $number]); - $newoptions[$number]['hierarchical'] = isset($_POST['categories-hierarchical-' . $number]); - $newoptions[$number]['dropdown'] = isset($_POST['categories-dropdown-' . $number]); - $newoptions[$number]['title'] = strip_tags(stripslashes($_POST['categories-title-' . $number])); - } + $_widgets = array(); + foreach ( $widgets as $widget ) { + if ( isset($wp_registered_widgets[$widget]) ) + $_widgets[] = $widget; + } - if ( $options != $newoptions ) { - $options = $newoptions; - update_option('widget_categories', $options); + $_sidebars_widgets[$sidebar] = $_widgets; + $shown_widgets = array_merge($shown_widgets, $_widgets); } - $title = attribute_escape( $options[$number]['title'] ); -?> -

    - -

    - -

    + $sidebars_widgets = $_sidebars_widgets; + unset($_sidebars_widgets, $_widgets); -

    + // find hidden/lost multi-widget instances + $lost_widgets = array(); + foreach ( $wp_registered_widgets as $key => $val ) { + if ( in_array($key, $shown_widgets, true) ) + continue; - - 9 ) { - $number = 9; - } elseif ( $number < 1 ) { - $number = 1; - } + if ( 2 > (int) $number ) + continue; - $newoptions['number'] = $number; + $lost_widgets[] = $key; } - if ( $newoptions != $options ) { - $options = $newoptions; - update_option( 'widget_categories', $options ); - wp_widget_categories_register( $options['number'] ); + $sidebars_widgets['wp_inactive_widgets'] = array_merge($lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets']); + if ( 'customize' !== $theme_changed ) { + wp_set_sidebars_widgets( $sidebars_widgets ); } -} -function wp_widget_categories_page() { - $options = get_option( 'widget_categories' ); -?> -
    -
    -

    -

    - - - - -

    -
    -
    - 1, 1 => $options ); - - update_option( 'widget_categories', $newoptions ); - - $sidebars_widgets = get_option( 'sidebars_widgets' ); - if ( is_array( $sidebars_widgets ) ) { - foreach ( $sidebars_widgets as $sidebar => $widgets ) { - if ( is_array( $widgets ) ) { - foreach ( $widgets as $widget ) - $new_widgets[$sidebar][] = ( $widget == 'categories' ) ? 'categories-1' : $widget; - } else { - $new_widgets[$sidebar] = $widgets; - } - } - if ( $new_widgets != $sidebars_widgets ) - update_option( 'sidebars_widgets', $new_widgets ); +/** + * Display the RSS entries in a list. + * + * @since 2.5.0 + * + * @param string|array|object $rss RSS url. + * @param array $args Widget arguments. + */ +function wp_widget_rss_output( $rss, $args = array() ) { + if ( is_string( $rss ) ) { + $rss = fetch_feed($rss); + } elseif ( is_array($rss) && isset($rss['url']) ) { + $args = $rss; + $rss = fetch_feed($rss['url']); + } elseif ( !is_object($rss) ) { + return; } - if ( isset( $_POST['categories-submit'] ) ) { - $_POST['categories-submit-1'] = $_POST['categories-submit']; - $_POST['categories-count-1'] = $_POST['categories-count']; - $_POST['categories-hierarchical-1'] = $_POST['categories-hierarchical']; - $_POST['categories-dropdown-1'] = $_POST['categories-dropdown']; - $_POST['categories-title-1'] = $_POST['categories-title']; - foreach ( $_POST as $k => $v ) - if ( substr($k, -5) == 'order' ) - $_POST[$k] = str_replace('categories', 'categories-1', $v); + if ( is_wp_error($rss) ) { + if ( is_admin() || current_user_can('manage_options') ) + echo '

    ' . sprintf( __('RSS Error: %s'), $rss->get_error_message() ) . '

    '; + return; } - return $newoptions; -} + $default_args = array( 'show_author' => 0, 'show_date' => 0, 'show_summary' => 0, 'items' => 0 ); + $args = wp_parse_args( $args, $default_args ); -function wp_widget_categories_register() { - $options = get_option( 'widget_categories' ); - if ( !isset($options['number']) ) - $options = wp_widget_categories_upgrade(); - $number = (int) $options['number']; + $items = (int) $args['items']; + if ( $items < 1 || 20 < $items ) + $items = 10; + $show_summary = (int) $args['show_summary']; + $show_author = (int) $args['show_author']; + $show_date = (int) $args['show_date']; - if ( $number > 9 ) { - $number = 9; - } elseif ( $number < 1 ) { - $number = 1; + if ( !$rss->get_item_quantity() ) { + echo ''; + $rss->__destruct(); + unset($rss); + return; } - $dims = array( 'width' => 350, 'height' => 170 ); - $class = array( 'classname' => 'widget_categories' ); + echo '