| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core Widgets API 4 * 5 * This API is used for creating dynamic sidebar without hardcoding functionality into 6 * themes 7 * 8 * Includes both internal WordPress routines and theme-use routines. 9 * 10 * This functionality was found in a plugin before the WordPress 2.2 release, which 11 * included it in the core from that point on. 12 * 13 * @link https://wordpress.org/support/article/wordpress-widgets/ 14 * @link https://developer.wordpress.org/themes/functionality/widgets/ 15 * 16 * @package WordPress 17 * @subpackage Widgets 18 * @since 2.2.0 19 */ 20 21 // 22 // Global Variables. 23 // 24 25 /** @ignore */ 26 global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates; 27 28 /** 29 * Stores the sidebars, since many themes can have more than one. 30 * 31 * @global array $wp_registered_sidebars Registered sidebars. 32 * @since 2.2.0 33 */ 34 $wp_registered_sidebars = array(); 35 36 /** 37 * Stores the registered widgets. 38 * 39 * @global array $wp_registered_widgets 40 * @since 2.2.0 41 */ 42 $wp_registered_widgets = array(); 43 44 /** 45 * Stores the registered widget controls (options). 46 * 47 * @global array $wp_registered_widget_controls 48 * @since 2.2.0 49 */ 50 $wp_registered_widget_controls = array(); 51 /** 52 * @global array $wp_registered_widget_updates 53 */ 54 $wp_registered_widget_updates = array(); 55 56 /** 57 * Private 58 * 59 * @global array $_wp_sidebars_widgets 60 */ 61 $_wp_sidebars_widgets = array(); 62 63 /** 64 * Private 65 * 66 * @global array $_wp_deprecated_widgets_callbacks 67 */ 68 $GLOBALS['_wp_deprecated_widgets_callbacks'] = array( 69 'wp_widget_pages', 70 'wp_widget_pages_control', 71 'wp_widget_calendar', 72 'wp_widget_calendar_control', 73 'wp_widget_archives', 74 'wp_widget_archives_control', 75 'wp_widget_links', 76 'wp_widget_meta', 77 'wp_widget_meta_control', 78 'wp_widget_search', 79 'wp_widget_recent_entries', 80 'wp_widget_recent_entries_control', 81 'wp_widget_tag_cloud', 82 'wp_widget_tag_cloud_control', 83 'wp_widget_categories', 84 'wp_widget_categories_control', 85 'wp_widget_text', 86 'wp_widget_text_control', 87 'wp_widget_rss', 88 'wp_widget_rss_control', 89 'wp_widget_recent_comments', 90 'wp_widget_recent_comments_control', 91 ); 92 93 // 94 // Template tags & API functions. 95 // 96 97 /** 98 * Register a widget 99 * 100 * Registers a WP_Widget widget 101 * 102 * @since 2.8.0 103 * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object 104 * instead of simply a `WP_Widget` subclass name. 105 * 106 * @see WP_Widget 107 * 108 * @global WP_Widget_Factory $wp_widget_factory 109 * 110 * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass. 111 */ 112 function register_widget( $widget ) { 113 global $wp_widget_factory; 114 115 $wp_widget_factory->register( $widget ); 116 } 117 118 /** 119 * Unregisters a widget. 120 * 121 * Unregisters a WP_Widget widget. Useful for un-registering default widgets. 122 * Run within a function hooked to the {@see 'widgets_init'} action. 123 * 124 * @since 2.8.0 125 * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object 126 * instead of simply a `WP_Widget` subclass name. 127 * 128 * @see WP_Widget 129 * 130 * @global WP_Widget_Factory $wp_widget_factory 131 * 132 * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass. 133 */ 134 function unregister_widget( $widget ) { 135 global $wp_widget_factory; 136 137 $wp_widget_factory->unregister( $widget ); 138 } 139 140 /** 141 * Creates multiple sidebars. 142 * 143 * If you wanted to quickly create multiple sidebars for a theme or internally. 144 * This function will allow you to do so. If you don't pass the 'name' and/or 145 * 'id' in `$args`, then they will be built for you. 146 * 147 * @since 2.2.0 148 * 149 * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here. 150 * 151 * @global array $wp_registered_sidebars The new sidebars are stored in this array by sidebar ID. 152 * 153 * @param int $number Optional. Number of sidebars to create. Default 1. 154 * @param array|string $args { 155 * Optional. Array or string of arguments for building a sidebar. 156 * 157 * @type string $id The base string of the unique identifier for each sidebar. If provided, and multiple 158 * sidebars are being defined, the ID will have "-2" appended, and so on. 159 * Default 'sidebar-' followed by the number the sidebar creation is currently at. 160 * @type string $name The name or title for the sidebars displayed in the admin dashboard. If registering 161 * more than one sidebar, include '%d' in the string as a placeholder for the uniquely 162 * assigned number for each sidebar. 163 * Default 'Sidebar' for the first sidebar, otherwise 'Sidebar %d'. 164 * } 165 */ 166 function register_sidebars( $number = 1, $args = array() ) { 167 global $wp_registered_sidebars; 168 $number = (int) $number; 169 170 if ( is_string( $args ) ) { 171 parse_str( $args, $args ); 172 } 173 174 for ( $i = 1; $i <= $number; $i++ ) { 175 $_args = $args; 176 177 if ( $number > 1 ) { 178 if ( isset( $args['name'] ) ) { 179 $_args['name'] = sprintf( $args['name'], $i ); 180 } else { 181 /* translators: %d: Sidebar number. */ 182 $_args['name'] = sprintf( __( 'Sidebar %d' ), $i ); 183 } 184 } else { 185 $_args['name'] = isset( $args['name'] ) ? $args['name'] : __( 'Sidebar' ); 186 } 187 188 // Custom specified ID's are suffixed if they exist already. 189 // Automatically generated sidebar names need to be suffixed regardless starting at -0. 190 if ( isset( $args['id'] ) ) { 191 $_args['id'] = $args['id']; 192 $n = 2; // Start at -2 for conflicting custom IDs. 193 while ( is_registered_sidebar( $_args['id'] ) ) { 194 $_args['id'] = $args['id'] . '-' . $n++; 195 } 196 } else { 197 $n = count( $wp_registered_sidebars ); 198 do { 199 $_args['id'] = 'sidebar-' . ++$n; 200 } while ( is_registered_sidebar( $_args['id'] ) ); 201 } 202 register_sidebar( $_args ); 203 } 204 } 205 206 /** 207 * Builds the definition for a single sidebar and returns the ID. 208 * 209 * Accepts either a string or an array and then parses that against a set 210 * of default arguments for the new sidebar. WordPress will automatically 211 * generate a sidebar ID and name based on the current number of registered 212 * sidebars if those arguments are not included. 213 * 214 * When allowing for automatic generation of the name and ID parameters, keep 215 * in mind that the incrementor for your sidebar can change over time depending 216 * on what other plugins and themes are installed. 217 * 218 * If theme support for 'widgets' has not yet been added when this function is 219 * called, it will be automatically enabled through the use of add_theme_support() 220 * 221 * @since 2.2.0 222 * @since 5.6.0 Added the `before_sidebar` and `after_sidebar` arguments. 223 * 224 * @global array $wp_registered_sidebars Registered sidebars. 225 * 226 * @param array|string $args { 227 * Optional. Array or string of arguments for the sidebar being registered. 228 * 229 * @type string $name The name or title of the sidebar displayed in the Widgets 230 * interface. Default 'Sidebar $instance'. 231 * @type string $id The unique identifier by which the sidebar will be called. 232 * Default 'sidebar-$instance'. 233 * @type string $description Description of the sidebar, displayed in the Widgets interface. 234 * Default empty string. 235 * @type string $class Extra CSS class to assign to the sidebar in the Widgets interface. 236 * Default empty. 237 * @type string $before_widget HTML content to prepend to each widget's HTML output when assigned 238 * to this sidebar. Receives the widget's ID attribute as `%1$s` 239 * and class name as `%2$s`. Default is an opening list item element. 240 * @type string $after_widget HTML content to append to each widget's HTML output when assigned 241 * to this sidebar. Default is a closing list item element. 242 * @type string $before_title HTML content to prepend to the sidebar title when displayed. 243 * Default is an opening h2 element. 244 * @type string $after_title HTML content to append to the sidebar title when displayed. 245 * Default is a closing h2 element. 246 * @type string $before_sidebar HTML content to prepend to the sidebar when displayed. 247 * Receives the `$id` argument as `%1$s` and `$class` as `%2$s`. 248 * Outputs after the {@see 'dynamic_sidebar_before'} action. 249 * Default empty string. 250 * @type string $after_sidebar HTML content to append to the sidebar when displayed. 251 * Outputs before the {@see 'dynamic_sidebar_after'} action. 252 * Default empty string. 253 * } 254 * @return string Sidebar ID added to $wp_registered_sidebars global. 255 */ 256 function register_sidebar( $args = array() ) { 257 global $wp_registered_sidebars; 258 259 $i = count( $wp_registered_sidebars ) + 1; 260 261 $id_is_empty = empty( $args['id'] ); 262 263 $defaults = array( 264 /* translators: %d: Sidebar number. */ 265 'name' => sprintf( __( 'Sidebar %d' ), $i ), 266 'id' => "sidebar-$i", 267 'description' => '', 268 'class' => '', 269 'before_widget' => '<li id="%1$s" class="widget %2$s">', 270 'after_widget' => "</li>\n", 271 'before_title' => '<h2 class="widgettitle">', 272 'after_title' => "</h2>\n", 273 'before_sidebar' => '', 274 'after_sidebar' => '', 275 ); 276 277 /** 278 * Filters the sidebar default arguments. 279 * 280 * @since 5.3.0 281 * 282 * @see register_sidebar() 283 * 284 * @param array $defaults The default sidebar arguments. 285 */ 286 $sidebar = wp_parse_args( $args, apply_filters( 'register_sidebar_defaults', $defaults ) ); 287 288 if ( $id_is_empty ) { 289 _doing_it_wrong( 290 __FUNCTION__, 291 sprintf( 292 /* translators: 1: The 'id' argument, 2: Sidebar name, 3: Recommended 'id' value. */ 293 __( '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.' ), 294 '<code>id</code>', 295 $sidebar['name'], 296 $sidebar['id'] 297 ), 298 '4.2.0' 299 ); 300 } 301 302 $wp_registered_sidebars[ $sidebar['id'] ] = $sidebar; 303 304 add_theme_support( 'widgets' ); 305 306 /** 307 * Fires once a sidebar has been registered. 308 * 309 * @since 3.0.0 310 * 311 * @param array $sidebar Parsed arguments for the registered sidebar. 312 */ 313 do_action( 'register_sidebar', $sidebar ); 314 315 return $sidebar['id']; 316 } 317 318 /** 319 * Removes a sidebar from the list. 320 * 321 * @since 2.2.0 322 * 323 * @global array $wp_registered_sidebars Registered sidebars. 324 * 325 * @param string|int $sidebar_id The ID of the sidebar when it was registered. 326 */ 327 function unregister_sidebar( $sidebar_id ) { 328 global $wp_registered_sidebars; 329 330 unset( $wp_registered_sidebars[ $sidebar_id ] ); 331 } 332 333 /** 334 * Checks if a sidebar is registered. 335 * 336 * @since 4.4.0 337 * 338 * @global array $wp_registered_sidebars Registered sidebars. 339 * 340 * @param string|int $sidebar_id The ID of the sidebar when it was registered. 341 * @return bool True if the sidebar is registered, false otherwise. 342 */ 343 function is_registered_sidebar( $sidebar_id ) { 344 global $wp_registered_sidebars; 345 346 return isset( $wp_registered_sidebars[ $sidebar_id ] ); 347 } 348 349 /** 350 * Register an instance of a widget. 351 * 352 * The default widget option is 'classname' that can be overridden. 353 * 354 * The function can also be used to un-register widgets when `$output_callback` 355 * parameter is an empty string. 356 * 357 * @since 2.2.0 358 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter 359 * by adding it to the function signature. 360 * @since 5.8.0 Added show_instance_in_rest option. 361 * 362 * @global array $wp_registered_widgets Uses stored registered widgets. 363 * @global array $wp_registered_widget_controls Stores the registered widget controls (options). 364 * @global array $wp_registered_widget_updates 365 * @global array $_wp_deprecated_widgets_callbacks 366 * 367 * @param int|string $id Widget ID. 368 * @param string $name Widget display title. 369 * @param callable $output_callback Run when widget is called. 370 * @param array $options { 371 * Optional. An array of supplementary widget options for the instance. 372 * 373 * @type string $classname Class name for the widget's HTML container. Default is a shortened 374 * version of the output callback name. 375 * @type string $description Widget description for display in the widget administration 376 * panel and/or theme. 377 * @type bool $show_instance_in_rest Whether to show the widget's instance settings in the REST API. 378 * Only available for WP_Widget based widgets. 379 * } 380 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 381 */ 382 function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) { 383 global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks; 384 385 $id = strtolower( $id ); 386 387 if ( empty( $output_callback ) ) { 388 unset( $wp_registered_widgets[ $id ] ); 389 return; 390 } 391 392 $id_base = _get_widget_id_base( $id ); 393 if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) { 394 unset( $wp_registered_widget_controls[ $id ] ); 395 unset( $wp_registered_widget_updates[ $id_base ] ); 396 return; 397 } 398 399 $defaults = array( 'classname' => $output_callback ); 400 $options = wp_parse_args( $options, $defaults ); 401 $widget = array( 402 'name' => $name, 403 'id' => $id, 404 'callback' => $output_callback, 405 'params' => $params, 406 ); 407 $widget = array_merge( $widget, $options ); 408 409 if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) { 410 411 /** 412 * Fires once for each registered widget. 413 * 414 * @since 3.0.0 415 * 416 * @param array $widget An array of default widget arguments. 417 */ 418 do_action( 'wp_register_sidebar_widget', $widget ); 419 $wp_registered_widgets[ $id ] = $widget; 420 } 421 } 422 423 /** 424 * Retrieve description for widget. 425 * 426 * When registering widgets, the options can also include 'description' that 427 * describes the widget for display on the widget administration panel or 428 * in the theme. 429 * 430 * @since 2.5.0 431 * 432 * @global array $wp_registered_widgets 433 * 434 * @param int|string $id Widget ID. 435 * @return string|void Widget description, if available. 436 */ 437 function wp_widget_description( $id ) { 438 if ( ! is_scalar( $id ) ) { 439 return; 440 } 441 442 global $wp_registered_widgets; 443 444 if ( isset( $wp_registered_widgets[ $id ]['description'] ) ) { 445 return esc_html( $wp_registered_widgets[ $id ]['description'] ); 446 } 447 } 448 449 /** 450 * Retrieve description for a sidebar. 451 * 452 * When registering sidebars a 'description' parameter can be included that 453 * describes the sidebar for display on the widget administration panel. 454 * 455 * @since 2.9.0 456 * 457 * @global array $wp_registered_sidebars Registered sidebars. 458 * 459 * @param string $id sidebar ID. 460 * @return string|void Sidebar description, if available. 461 */ 462 function wp_sidebar_description( $id ) { 463 if ( ! is_scalar( $id ) ) { 464 return; 465 } 466 467 global $wp_registered_sidebars; 468 469 if ( isset( $wp_registered_sidebars[ $id ]['description'] ) ) { 470 return wp_kses( $wp_registered_sidebars[ $id ]['description'], 'sidebar_description' ); 471 } 472 } 473 474 /** 475 * Remove widget from sidebar. 476 * 477 * @since 2.2.0 478 * 479 * @param int|string $id Widget ID. 480 */ 481 function wp_unregister_sidebar_widget( $id ) { 482 483 /** 484 * Fires just before a widget is removed from a sidebar. 485 * 486 * @since 3.0.0 487 * 488 * @param int $id The widget ID. 489 */ 490 do_action( 'wp_unregister_sidebar_widget', $id ); 491 492 wp_register_sidebar_widget( $id, '', '' ); 493 wp_unregister_widget_control( $id ); 494 } 495 496 /** 497 * Registers widget control callback for customizing options. 498 * 499 * @since 2.2.0 500 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter 501 * by adding it to the function signature. 502 * 503 * @global array $wp_registered_widget_controls 504 * @global array $wp_registered_widget_updates 505 * @global array $wp_registered_widgets 506 * @global array $_wp_deprecated_widgets_callbacks 507 * 508 * @param int|string $id Sidebar ID. 509 * @param string $name Sidebar display name. 510 * @param callable $control_callback Run when sidebar is displayed. 511 * @param array $options { 512 * Optional. Array or string of control options. Default empty array. 513 * 514 * @type int $height Never used. Default 200. 515 * @type int $width Width of the fully expanded control form (but try hard to use the default width). 516 * Default 250. 517 * @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the 518 * text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`. 519 * } 520 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 521 */ 522 function wp_register_widget_control( $id, $name, $control_callback, $options = array(), ...$params ) { 523 global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks; 524 525 $id = strtolower( $id ); 526 $id_base = _get_widget_id_base( $id ); 527 528 if ( empty( $control_callback ) ) { 529 unset( $wp_registered_widget_controls[ $id ] ); 530 unset( $wp_registered_widget_updates[ $id_base ] ); 531 return; 532 } 533 534 if ( in_array( $control_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $control_callback ) ) { 535 unset( $wp_registered_widgets[ $id ] ); 536 return; 537 } 538 539 if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) { 540 return; 541 } 542 543 $defaults = array( 544 'width' => 250, 545 'height' => 200, 546 ); // Height is never used. 547 $options = wp_parse_args( $options, $defaults ); 548 $options['width'] = (int) $options['width']; 549 $options['height'] = (int) $options['height']; 550 551 $widget = array( 552 'name' => $name, 553 'id' => $id, 554 'callback' => $control_callback, 555 'params' => $params, 556 ); 557 $widget = array_merge( $widget, $options ); 558 559 $wp_registered_widget_controls[ $id ] = $widget; 560 561 if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) { 562 return; 563 } 564 565 if ( isset( $widget['params'][0]['number'] ) ) { 566 $widget['params'][0]['number'] = -1; 567 } 568 569 unset( $widget['width'], $widget['height'], $widget['name'], $widget['id'] ); 570 $wp_registered_widget_updates[ $id_base ] = $widget; 571 } 572 573 /** 574 * Registers the update callback for a widget. 575 * 576 * @since 2.8.0 577 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter 578 * by adding it to the function signature. 579 * 580 * @global array $wp_registered_widget_updates 581 * 582 * @param string $id_base The base ID of a widget created by extending WP_Widget. 583 * @param callable $update_callback Update callback method for the widget. 584 * @param array $options Optional. Widget control options. See wp_register_widget_control(). 585 * Default empty array. 586 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 587 */ 588 function _register_widget_update_callback( $id_base, $update_callback, $options = array(), ...$params ) { 589 global $wp_registered_widget_updates; 590 591 if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) { 592 if ( empty( $update_callback ) ) { 593 unset( $wp_registered_widget_updates[ $id_base ] ); 594 } 595 return; 596 } 597 598 $widget = array( 599 'callback' => $update_callback, 600 'params' => $params, 601 ); 602 603 $widget = array_merge( $widget, $options ); 604 $wp_registered_widget_updates[ $id_base ] = $widget; 605 } 606 607 /** 608 * Registers the form callback for a widget. 609 * 610 * @since 2.8.0 611 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter 612 * by adding it to the function signature. 613 * 614 * @global array $wp_registered_widget_controls 615 * 616 * @param int|string $id Widget ID. 617 * @param string $name Name attribute for the widget. 618 * @param callable $form_callback Form callback. 619 * @param array $options Optional. Widget control options. See wp_register_widget_control(). 620 * Default empty array. 621 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 622 */ 623 624 function _register_widget_form_callback( $id, $name, $form_callback, $options = array(), ...$params ) { 625 global $wp_registered_widget_controls; 626 627 $id = strtolower( $id ); 628 629 if ( empty( $form_callback ) ) { 630 unset( $wp_registered_widget_controls[ $id ] ); 631 return; 632 } 633 634 if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) { 635 return; 636 } 637 638 $defaults = array( 639 'width' => 250, 640 'height' => 200, 641 ); 642 $options = wp_parse_args( $options, $defaults ); 643 $options['width'] = (int) $options['width']; 644 $options['height'] = (int) $options['height']; 645 646 $widget = array( 647 'name' => $name, 648 'id' => $id, 649 'callback' => $form_callback, 650 'params' => $params, 651 ); 652 $widget = array_merge( $widget, $options ); 653 654 $wp_registered_widget_controls[ $id ] = $widget; 655 } 656 657 /** 658 * Remove control callback for widget. 659 * 660 * @since 2.2.0 661 * 662 * @param int|string $id Widget ID. 663 */ 664 function wp_unregister_widget_control( $id ) { 665 wp_register_widget_control( $id, '', '' ); 666 } 667 668 /** 669 * Display dynamic sidebar. 670 * 671 * By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or 672 * 'name' parameter for its registered sidebars you can pass an ID or name as the $index parameter. 673 * Otherwise, you can pass in a numerical index to display the sidebar at that index. 674 * 675 * @since 2.2.0 676 * 677 * @global array $wp_registered_sidebars Registered sidebars. 678 * @global array $wp_registered_widgets Registered widgets. 679 * 680 * @param int|string $index Optional. Index, name or ID of dynamic sidebar. Default 1. 681 * @return bool True, if widget sidebar was found and called. False if not found or not called. 682 */ 683 function dynamic_sidebar( $index = 1 ) { 684 global $wp_registered_sidebars, $wp_registered_widgets; 685 686 if ( is_int( $index ) ) { 687 $index = "sidebar-$index"; 688 } else { 689 $index = sanitize_title( $index ); 690 foreach ( (array) $wp_registered_sidebars as $key => $value ) { 691 if ( sanitize_title( $value['name'] ) === $index ) { 692 $index = $key; 693 break; 694 } 695 } 696 } 697 698 $sidebars_widgets = wp_get_sidebars_widgets(); 699 if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { 700 /** This action is documented in wp-includes/widget.php */ 701 do_action( 'dynamic_sidebar_before', $index, false ); 702 /** This action is documented in wp-includes/widget.php */ 703 do_action( 'dynamic_sidebar_after', $index, false ); 704 /** This filter is documented in wp-includes/widget.php */ 705 return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); 706 } 707 708 $sidebar = $wp_registered_sidebars[ $index ]; 709 710 $sidebar['before_sidebar'] = sprintf( $sidebar['before_sidebar'], $sidebar['id'], $sidebar['class'] ); 711 712 /** 713 * Fires before widgets are rendered in a dynamic sidebar. 714 * 715 * Note: The action also fires for empty sidebars, and on both the front end 716 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 717 * 718 * @since 3.9.0 719 * 720 * @param int|string $index Index, name, or ID of the dynamic sidebar. 721 * @param bool $has_widgets Whether the sidebar is populated with widgets. 722 * Default true. 723 */ 724 do_action( 'dynamic_sidebar_before', $index, true ); 725 726 if ( ! is_admin() && ! empty( $sidebar['before_sidebar'] ) ) { 727 echo $sidebar['before_sidebar']; 728 } 729 730 $did_one = false; 731 foreach ( (array) $sidebars_widgets[ $index ] as $id ) { 732 733 if ( ! isset( $wp_registered_widgets[ $id ] ) ) { 734 continue; 735 } 736 737 $params = array_merge( 738 array( 739 array_merge( 740 $sidebar, 741 array( 742 'widget_id' => $id, 743 'widget_name' => $wp_registered_widgets[ $id ]['name'], 744 ) 745 ), 746 ), 747 (array) $wp_registered_widgets[ $id ]['params'] 748 ); 749 750 // Substitute HTML `id` and `class` attributes into `before_widget`. 751 $classname_ = ''; 752 foreach ( (array) $wp_registered_widgets[ $id ]['classname'] as $cn ) { 753 if ( is_string( $cn ) ) { 754 $classname_ .= '_' . $cn; 755 } elseif ( is_object( $cn ) ) { 756 $classname_ .= '_' . get_class( $cn ); 757 } 758 } 759 $classname_ = ltrim( $classname_, '_' ); 760 761 $params[0]['before_widget'] = sprintf( 762 $params[0]['before_widget'], 763 str_replace( '\\', '_', $id ), 764 $classname_ 765 ); 766 767 /** 768 * Filters the parameters passed to a widget's display callback. 769 * 770 * Note: The filter is evaluated on both the front end and back end, 771 * including for the Inactive Widgets sidebar on the Widgets screen. 772 * 773 * @since 2.5.0 774 * 775 * @see register_sidebar() 776 * 777 * @param array $params { 778 * @type array $args { 779 * An array of widget display arguments. 780 * 781 * @type string $name Name of the sidebar the widget is assigned to. 782 * @type string $id ID of the sidebar the widget is assigned to. 783 * @type string $description The sidebar description. 784 * @type string $class CSS class applied to the sidebar container. 785 * @type string $before_widget HTML markup to prepend to each widget in the sidebar. 786 * @type string $after_widget HTML markup to append to each widget in the sidebar. 787 * @type string $before_title HTML markup to prepend to the widget title when displayed. 788 * @type string $after_title HTML markup to append to the widget title when displayed. 789 * @type string $widget_id ID of the widget. 790 * @type string $widget_name Name of the widget. 791 * } 792 * @type array $widget_args { 793 * An array of multi-widget arguments. 794 * 795 * @type int $number Number increment used for multiples of the same widget. 796 * } 797 * } 798 */ 799 $params = apply_filters( 'dynamic_sidebar_params', $params ); 800 801 $callback = $wp_registered_widgets[ $id ]['callback']; 802 803 /** 804 * Fires before a widget's display callback is called. 805 * 806 * Note: The action fires on both the front end and back end, including 807 * for widgets in the Inactive Widgets sidebar on the Widgets screen. 808 * 809 * The action is not fired for empty sidebars. 810 * 811 * @since 3.0.0 812 * 813 * @param array $widget { 814 * An associative array of widget arguments. 815 * 816 * @type string $name Name of the widget. 817 * @type string $id Widget ID. 818 * @type callable $callback When the hook is fired on the front end, `$callback` is an array 819 * containing the widget object. Fired on the back end, `$callback` 820 * is 'wp_widget_control', see `$_callback`. 821 * @type array $params An associative array of multi-widget arguments. 822 * @type string $classname CSS class applied to the widget container. 823 * @type string $description The widget description. 824 * @type array $_callback When the hook is fired on the back end, `$_callback` is populated 825 * with an array containing the widget object, see `$callback`. 826 * } 827 */ 828 do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); 829 830 if ( is_callable( $callback ) ) { 831 call_user_func_array( $callback, $params ); 832 $did_one = true; 833 } 834 } 835 836 if ( ! is_admin() && ! empty( $sidebar['after_sidebar'] ) ) { 837 echo $sidebar['after_sidebar']; 838 } 839 840 /** 841 * Fires after widgets are rendered in a dynamic sidebar. 842 * 843 * Note: The action also fires for empty sidebars, and on both the front end 844 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 845 * 846 * @since 3.9.0 847 * 848 * @param int|string $index Index, name, or ID of the dynamic sidebar. 849 * @param bool $has_widgets Whether the sidebar is populated with widgets. 850 * Default true. 851 */ 852 do_action( 'dynamic_sidebar_after', $index, true ); 853 854 /** 855 * Filters whether a sidebar has widgets. 856 * 857 * Note: The filter is also evaluated for empty sidebars, and on both the front end 858 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 859 * 860 * @since 3.9.0 861 * 862 * @param bool $did_one Whether at least one widget was rendered in the sidebar. 863 * Default false. 864 * @param int|string $index Index, name, or ID of the dynamic sidebar. 865 */ 866 return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index ); 867 } 868 869 /** 870 * Determines whether a given widget is displayed on the front end. 871 * 872 * Either $callback or $id_base can be used 873 * $id_base is the first argument when extending WP_Widget class 874 * Without the optional $widget_id parameter, returns the ID of the first sidebar 875 * in which the first instance of the widget with the given callback or $id_base is found. 876 * With the $widget_id parameter, returns the ID of the sidebar where 877 * the widget with that callback/$id_base AND that ID is found. 878 * 879 * NOTE: $widget_id and $id_base are the same for single widgets. To be effective 880 * this function has to run after widgets have initialized, at action {@see 'init'} or later. 881 * 882 * For more information on this and similar theme functions, check out 883 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 884 * Conditional Tags} article in the Theme Developer Handbook. 885 * 886 * @since 2.2.0 887 * 888 * @global array $wp_registered_widgets 889 * 890 * @param callable|false $callback Optional. Widget callback to check. Default false. 891 * @param string|false $widget_id Optional. Widget ID. Optional, but needed for checking. 892 * Default false. 893 * @param string|false $id_base Optional. The base ID of a widget created by extending WP_Widget. 894 * Default false. 895 * @param bool $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. 896 * Default true. 897 * @return string|false ID of the sidebar in which the widget is active, 898 * false if the widget is not active. 899 */ 900 function is_active_widget( $callback = false, $widget_id = false, $id_base = false, $skip_inactive = true ) { 901 global $wp_registered_widgets; 902 903 $sidebars_widgets = wp_get_sidebars_widgets(); 904 905 if ( is_array( $sidebars_widgets ) ) { 906 foreach ( $sidebars_widgets as $sidebar => $widgets ) { 907 if ( $skip_inactive && ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) ) { 908 continue; 909 } 910 911 if ( is_array( $widgets ) ) { 912 foreach ( $widgets as $widget ) { 913 if ( ( $callback && isset( $wp_registered_widgets[ $widget ]['callback'] ) && $wp_registered_widgets[ $widget ]['callback'] === $callback ) || ( $id_base && _get_widget_id_base( $widget ) === $id_base ) ) { 914 if ( ! $widget_id || $widget_id === $wp_registered_widgets[ $widget ]['id'] ) { 915 return $sidebar; 916 } 917 } 918 } 919 } 920 } 921 } 922 return false; 923 } 924 925 /** 926 * Determines whether the dynamic sidebar is enabled and used by the theme. 927 * 928 * For more information on this and similar theme functions, check out 929 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 930 * Conditional Tags} article in the Theme Developer Handbook. 931 * 932 * @since 2.2.0 933 * 934 * @global array $wp_registered_widgets Registered widgets. 935 * @global array $wp_registered_sidebars Registered sidebars. 936 * 937 * @return bool True if using widgets, false otherwise. 938 */ 939 function is_dynamic_sidebar() { 940 global $wp_registered_widgets, $wp_registered_sidebars; 941 942 $sidebars_widgets = get_option( 'sidebars_widgets' ); 943 944 foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) { 945 if ( ! empty( $sidebars_widgets[ $index ] ) ) { 946 foreach ( (array) $sidebars_widgets[ $index ] as $widget ) { 947 if ( array_key_exists( $widget, $wp_registered_widgets ) ) { 948 return true; 949 } 950 } 951 } 952 } 953 954 return false; 955 } 956 957 /** 958 * Determines whether a sidebar contains widgets. 959 * 960 * For more information on this and similar theme functions, check out 961 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 962 * Conditional Tags} article in the Theme Developer Handbook. 963 * 964 * @since 2.8.0 965 * 966 * @param string|int $index Sidebar name, id or number to check. 967 * @return bool True if the sidebar has widgets, false otherwise. 968 */ 969 function is_active_sidebar( $index ) { 970 $index = ( is_int( $index ) ) ? "sidebar-$index" : sanitize_title( $index ); 971 $sidebars_widgets = wp_get_sidebars_widgets(); 972 $is_active_sidebar = ! empty( $sidebars_widgets[ $index ] ); 973 974 /** 975 * Filters whether a dynamic sidebar is considered "active". 976 * 977 * @since 3.9.0 978 * 979 * @param bool $is_active_sidebar Whether or not the sidebar should be considered "active". 980 * In other words, whether the sidebar contains any widgets. 981 * @param int|string $index Index, name, or ID of the dynamic sidebar. 982 */ 983 return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index ); 984 } 985 986 // 987 // Internal Functions. 988 // 989 990 /** 991 * Retrieve full list of sidebars and their widget instance IDs. 992 * 993 * Will upgrade sidebar widget list, if needed. Will also save updated list, if 994 * needed. 995 * 996 * @since 2.2.0 997 * @access private 998 * 999 * @global array $_wp_sidebars_widgets 1000 * @global array $sidebars_widgets 1001 * 1002 * @param bool $deprecated Not used (argument deprecated). 1003 * @return array Upgraded list of widgets to version 3 array format when called from the admin. 1004 */ 1005 function wp_get_sidebars_widgets( $deprecated = true ) { 1006 if ( true !== $deprecated ) { 1007 _deprecated_argument( __FUNCTION__, '2.8.1' ); 1008 } 1009 1010 global $_wp_sidebars_widgets, $sidebars_widgets; 1011 1012 // If loading from front page, consult $_wp_sidebars_widgets rather than options 1013 // to see if wp_convert_widget_settings() has made manipulations in memory. 1014 if ( ! is_admin() ) { 1015 if ( empty( $_wp_sidebars_widgets ) ) { 1016 $_wp_sidebars_widgets = get_option( 'sidebars_widgets', array() ); 1017 } 1018 1019 $sidebars_widgets = $_wp_sidebars_widgets; 1020 } else { 1021 $sidebars_widgets = get_option( 'sidebars_widgets', array() ); 1022 } 1023 1024 if ( is_array( $sidebars_widgets ) && isset( $sidebars_widgets['array_version'] ) ) { 1025 unset( $sidebars_widgets['array_version'] ); 1026 } 1027 1028 /** 1029 * Filters the list of sidebars and their widgets. 1030 * 1031 * @since 2.7.0 1032 * 1033 * @param array $sidebars_widgets An associative array of sidebars and their widgets. 1034 */ 1035 return apply_filters( 'sidebars_widgets', $sidebars_widgets ); 1036 } 1037 1038 /** 1039 * Set the sidebar widget option to update sidebars. 1040 * 1041 * @since 2.2.0 1042 * @access private 1043 * 1044 * @global array $_wp_sidebars_widgets 1045 * @param array $sidebars_widgets Sidebar widgets and their settings. 1046 */ 1047 function wp_set_sidebars_widgets( $sidebars_widgets ) { 1048 global $_wp_sidebars_widgets; 1049 1050 // Clear cached value used in wp_get_sidebars_widgets(). 1051 $_wp_sidebars_widgets = null; 1052 1053 if ( ! isset( $sidebars_widgets['array_version'] ) ) { 1054 $sidebars_widgets['array_version'] = 3; 1055 } 1056 1057 update_option( 'sidebars_widgets', $sidebars_widgets ); 1058 } 1059 1060 /** 1061 * Retrieve default registered sidebars list. 1062 * 1063 * @since 2.2.0 1064 * @access private 1065 * 1066 * @global array $wp_registered_sidebars Registered sidebars. 1067 * 1068 * @return array 1069 */ 1070 function wp_get_widget_defaults() { 1071 global $wp_registered_sidebars; 1072 1073 $defaults = array(); 1074 1075 foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) { 1076 $defaults[ $index ] = array(); 1077 } 1078 1079 return $defaults; 1080 } 1081 1082 /** 1083 * Converts the widget settings from single to multi-widget format. 1084 * 1085 * @since 2.8.0 1086 * 1087 * @global array $_wp_sidebars_widgets 1088 * 1089 * @param string $base_name Root ID for all widgets of this type. 1090 * @param string $option_name Option name for this widget type. 1091 * @param array $settings The array of widget instance settings. 1092 * @return array The array of widget settings converted to multi-widget format. 1093 */ 1094 function wp_convert_widget_settings( $base_name, $option_name, $settings ) { 1095 // This test may need expanding. 1096 $single = false; 1097 $changed = false; 1098 1099 if ( empty( $settings ) ) { 1100 $single = true; 1101 } else { 1102 foreach ( array_keys( $settings ) as $number ) { 1103 if ( 'number' === $number ) { 1104 continue; 1105 } 1106 if ( ! is_numeric( $number ) ) { 1107 $single = true; 1108 break; 1109 } 1110 } 1111 } 1112 1113 if ( $single ) { 1114 $settings = array( 2 => $settings ); 1115 1116 // If loading from the front page, update sidebar in memory but don't save to options. 1117 if ( is_admin() ) { 1118 $sidebars_widgets = get_option( 'sidebars_widgets' ); 1119 } else { 1120 if ( empty( $GLOBALS['_wp_sidebars_widgets'] ) ) { 1121 $GLOBALS['_wp_sidebars_widgets'] = get_option( 'sidebars_widgets', array() ); 1122 } 1123 $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets']; 1124 } 1125 1126 foreach ( (array) $sidebars_widgets as $index => $sidebar ) { 1127 if ( is_array( $sidebar ) ) { 1128 foreach ( $sidebar as $i => $name ) { 1129 if ( $base_name === $name ) { 1130 $sidebars_widgets[ $index ][ $i ] = "$name-2"; 1131 $changed = true; 1132 break 2; 1133 } 1134 } 1135 } 1136 } 1137 1138 if ( is_admin() && $changed ) { 1139 update_option( 'sidebars_widgets', $sidebars_widgets ); 1140 } 1141 } 1142 1143 $settings['_multiwidget'] = 1; 1144 if ( is_admin() ) { 1145 update_option( $option_name, $settings ); 1146 } 1147 1148 return $settings; 1149 } 1150 1151 /** 1152 * Output an arbitrary widget as a template tag. 1153 * 1154 * @since 2.8.0 1155 * 1156 * @global WP_Widget_Factory $wp_widget_factory 1157 * 1158 * @param string $widget The widget's PHP class name (see class-wp-widget.php). 1159 * @param array $instance Optional. The widget's instance settings. Default empty array. 1160 * @param array $args { 1161 * Optional. Array of arguments to configure the display of the widget. 1162 * 1163 * @type string $before_widget HTML content that will be prepended to the widget's HTML output. 1164 * Default `<div class="widget %s">`, where `%s` is the widget's class name. 1165 * @type string $after_widget HTML content that will be appended to the widget's HTML output. 1166 * Default `</div>`. 1167 * @type string $before_title HTML content that will be prepended to the widget's title when displayed. 1168 * Default `<h2 class="widgettitle">`. 1169 * @type string $after_title HTML content that will be appended to the widget's title when displayed. 1170 * Default `</h2>`. 1171 * } 1172 */ 1173 function the_widget( $widget, $instance = array(), $args = array() ) { 1174 global $wp_widget_factory; 1175 1176 if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) { 1177 _doing_it_wrong( 1178 __FUNCTION__, 1179 sprintf( 1180 /* translators: %s: register_widget() */ 1181 __( 'Widgets need to be registered using %s, before they can be displayed.' ), 1182 '<code>register_widget()</code>' 1183 ), 1184 '4.9.0' 1185 ); 1186 return; 1187 } 1188 1189 $widget_obj = $wp_widget_factory->widgets[ $widget ]; 1190 if ( ! ( $widget_obj instanceof WP_Widget ) ) { 1191 return; 1192 } 1193 1194 $default_args = array( 1195 'before_widget' => '<div class="widget %s">', 1196 'after_widget' => '</div>', 1197 'before_title' => '<h2 class="widgettitle">', 1198 'after_title' => '</h2>', 1199 ); 1200 $args = wp_parse_args( $args, $default_args ); 1201 $args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] ); 1202 1203 $instance = wp_parse_args( $instance ); 1204 1205 /** This filter is documented in wp-includes/class-wp-widget.php */ 1206 $instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args ); 1207 1208 if ( false === $instance ) { 1209 return; 1210 } 1211 1212 /** 1213 * Fires before rendering the requested widget. 1214 * 1215 * @since 3.0.0 1216 * 1217 * @param string $widget The widget's class name. 1218 * @param array $instance The current widget instance's settings. 1219 * @param array $args An array of the widget's sidebar arguments. 1220 */ 1221 do_action( 'the_widget', $widget, $instance, $args ); 1222 1223 $widget_obj->_set( -1 ); 1224 $widget_obj->widget( $args, $instance ); 1225 } 1226 1227 /** 1228 * Retrieves the widget ID base value. 1229 * 1230 * @since 2.8.0 1231 * 1232 * @param string $id Widget ID. 1233 * @return string Widget ID base. 1234 */ 1235 function _get_widget_id_base( $id ) { 1236 return preg_replace( '/-[0-9]+$/', '', $id ); 1237 } 1238 1239 /** 1240 * Handle sidebars config after theme change 1241 * 1242 * @access private 1243 * @since 3.3.0 1244 * 1245 * @global array $sidebars_widgets 1246 */ 1247 function _wp_sidebars_changed() { 1248 global $sidebars_widgets; 1249 1250 if ( ! is_array( $sidebars_widgets ) ) { 1251 $sidebars_widgets = wp_get_sidebars_widgets(); 1252 } 1253 1254 retrieve_widgets( true ); 1255 } 1256 1257 /** 1258 * Validates and remaps any "orphaned" widgets to wp_inactive_widgets sidebar, 1259 * and saves the widget settings. This has to run at least on each theme change. 1260 * 1261 * For example, let's say theme A has a "footer" sidebar, and theme B doesn't have one. 1262 * After switching from theme A to theme B, all the widgets previously assigned 1263 * to the footer would be inaccessible. This function detects this scenario, and 1264 * moves all the widgets previously assigned to the footer under wp_inactive_widgets. 1265 * 1266 * Despite the word "retrieve" in the name, this function actually updates the database 1267 * and the global `$sidebars_widgets`. For that reason it should not be run on front end, 1268 * unless the `$theme_changed` value is 'customize' (to bypass the database write). 1269 * 1270 * @since 2.8.0 1271 * 1272 * @global array $wp_registered_sidebars Registered sidebars. 1273 * @global array $sidebars_widgets 1274 * @global array $wp_registered_widgets Registered widgets. 1275 * 1276 * @param string|bool $theme_changed Whether the theme was changed as a boolean. A value 1277 * of 'customize' defers updates for the Customizer. 1278 * @return array Updated sidebars widgets. 1279 */ 1280 function retrieve_widgets( $theme_changed = false ) { 1281 global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets; 1282 1283 $registered_sidebars_keys = array_keys( $wp_registered_sidebars ); 1284 $registered_widgets_ids = array_keys( $wp_registered_widgets ); 1285 1286 if ( ! is_array( get_theme_mod( 'sidebars_widgets' ) ) ) { 1287 if ( empty( $sidebars_widgets ) ) { 1288 return array(); 1289 } 1290 1291 unset( $sidebars_widgets['array_version'] ); 1292 1293 $sidebars_widgets_keys = array_keys( $sidebars_widgets ); 1294 sort( $sidebars_widgets_keys ); 1295 sort( $registered_sidebars_keys ); 1296 1297 if ( $sidebars_widgets_keys === $registered_sidebars_keys ) { 1298 $sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids ); 1299 1300 return $sidebars_widgets; 1301 } 1302 } 1303 1304 // Discard invalid, theme-specific widgets from sidebars. 1305 $sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids ); 1306 $sidebars_widgets = wp_map_sidebars_widgets( $sidebars_widgets ); 1307 1308 // Find hidden/lost multi-widget instances. 1309 $shown_widgets = array_merge( ...array_values( $sidebars_widgets ) ); 1310 $lost_widgets = array_diff( $registered_widgets_ids, $shown_widgets ); 1311 1312 foreach ( $lost_widgets as $key => $widget_id ) { 1313 $number = preg_replace( '/.+?-([0-9]+)$/', '$1', $widget_id ); 1314 1315 // Only keep active and default widgets. 1316 if ( is_numeric( $number ) && (int) $number < 2 ) { 1317 unset( $lost_widgets[ $key ] ); 1318 } 1319 } 1320 $sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets'] ); 1321 1322 if ( 'customize' !== $theme_changed ) { 1323 // Update the widgets settings in the database. 1324 wp_set_sidebars_widgets( $sidebars_widgets ); 1325 } 1326 1327 return $sidebars_widgets; 1328 } 1329 1330 /** 1331 * Compares a list of sidebars with their widgets against an allowed list. 1332 * 1333 * @since 4.9.0 1334 * @since 4.9.2 Always tries to restore widget assignments from previous data, not just if sidebars needed mapping. 1335 * 1336 * @param array $existing_sidebars_widgets List of sidebars and their widget instance IDs. 1337 * @return array Mapped sidebars widgets. 1338 */ 1339 function wp_map_sidebars_widgets( $existing_sidebars_widgets ) { 1340 global $wp_registered_sidebars; 1341 1342 $new_sidebars_widgets = array( 1343 'wp_inactive_widgets' => array(), 1344 ); 1345 1346 // Short-circuit if there are no sidebars to map. 1347 if ( ! is_array( $existing_sidebars_widgets ) || empty( $existing_sidebars_widgets ) ) { 1348 return $new_sidebars_widgets; 1349 } 1350 1351 foreach ( $existing_sidebars_widgets as $sidebar => $widgets ) { 1352 if ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { 1353 $new_sidebars_widgets['wp_inactive_widgets'] = array_merge( $new_sidebars_widgets['wp_inactive_widgets'], (array) $widgets ); 1354 unset( $existing_sidebars_widgets[ $sidebar ] ); 1355 } 1356 } 1357 1358 // If old and new theme have just one sidebar, map it and we're done. 1359 if ( 1 === count( $existing_sidebars_widgets ) && 1 === count( $wp_registered_sidebars ) ) { 1360 $new_sidebars_widgets[ key( $wp_registered_sidebars ) ] = array_pop( $existing_sidebars_widgets ); 1361 1362 return $new_sidebars_widgets; 1363 } 1364 1365 // Map locations with the same slug. 1366 $existing_sidebars = array_keys( $existing_sidebars_widgets ); 1367 1368 foreach ( $wp_registered_sidebars as $sidebar => $name ) { 1369 if ( in_array( $sidebar, $existing_sidebars, true ) ) { 1370 $new_sidebars_widgets[ $sidebar ] = $existing_sidebars_widgets[ $sidebar ]; 1371 unset( $existing_sidebars_widgets[ $sidebar ] ); 1372 } elseif ( ! array_key_exists( $sidebar, $new_sidebars_widgets ) ) { 1373 $new_sidebars_widgets[ $sidebar ] = array(); 1374 } 1375 } 1376 1377 // If there are more sidebars, try to map them. 1378 if ( ! empty( $existing_sidebars_widgets ) ) { 1379 1380 /* 1381 * If old and new theme both have sidebars that contain phrases 1382 * from within the same group, make an educated guess and map it. 1383 */ 1384 $common_slug_groups = array( 1385 array( 'sidebar', 'primary', 'main', 'right' ), 1386 array( 'second', 'left' ), 1387 array( 'sidebar-2', 'footer', 'bottom' ), 1388 array( 'header', 'top' ), 1389 ); 1390 1391 // Go through each group... 1392 foreach ( $common_slug_groups as $slug_group ) { 1393 1394 // ...and see if any of these slugs... 1395 foreach ( $slug_group as $slug ) { 1396 1397 // ...and any of the new sidebars... 1398 foreach ( $wp_registered_sidebars as $new_sidebar => $args ) { 1399 1400 // ...actually match! 1401 if ( false === stripos( $new_sidebar, $slug ) && false === stripos( $slug, $new_sidebar ) ) { 1402 continue; 1403 } 1404 1405 // Then see if any of the existing sidebars... 1406 foreach ( $existing_sidebars_widgets as $sidebar => $widgets ) { 1407 1408 // ...and any slug in the same group... 1409 foreach ( $slug_group as $slug ) { 1410 1411 // ... have a match as well. 1412 if ( false === stripos( $sidebar, $slug ) && false === stripos( $slug, $sidebar ) ) { 1413 continue; 1414 } 1415 1416 // Make sure this sidebar wasn't mapped and removed previously. 1417 if ( ! empty( $existing_sidebars_widgets[ $sidebar ] ) ) { 1418 1419 // We have a match that can be mapped! 1420 $new_sidebars_widgets[ $new_sidebar ] = array_merge( $new_sidebars_widgets[ $new_sidebar ], $existing_sidebars_widgets[ $sidebar ] ); 1421 1422 // Remove the mapped sidebar so it can't be mapped again. 1423 unset( $existing_sidebars_widgets[ $sidebar ] ); 1424 1425 // Go back and check the next new sidebar. 1426 continue 3; 1427 } 1428 } // End foreach ( $slug_group as $slug ). 1429 } // End foreach ( $existing_sidebars_widgets as $sidebar => $widgets ). 1430 } // End foreach ( $wp_registered_sidebars as $new_sidebar => $args ). 1431 } // End foreach ( $slug_group as $slug ). 1432 } // End foreach ( $common_slug_groups as $slug_group ). 1433 } 1434 1435 // Move any left over widgets to inactive sidebar. 1436 foreach ( $existing_sidebars_widgets as $widgets ) { 1437 if ( is_array( $widgets ) && ! empty( $widgets ) ) { 1438 $new_sidebars_widgets['wp_inactive_widgets'] = array_merge( $new_sidebars_widgets['wp_inactive_widgets'], $widgets ); 1439 } 1440 } 1441 1442 // Sidebars_widgets settings from when this theme was previously active. 1443 $old_sidebars_widgets = get_theme_mod( 'sidebars_widgets' ); 1444 $old_sidebars_widgets = isset( $old_sidebars_widgets['data'] ) ? $old_sidebars_widgets['data'] : false; 1445 1446 if ( is_array( $old_sidebars_widgets ) ) { 1447 1448 // Remove empty sidebars, no need to map those. 1449 $old_sidebars_widgets = array_filter( $old_sidebars_widgets ); 1450 1451 // Only check sidebars that are empty or have not been mapped to yet. 1452 foreach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ) { 1453 if ( array_key_exists( $new_sidebar, $old_sidebars_widgets ) && ! empty( $new_widgets ) ) { 1454 unset( $old_sidebars_widgets[ $new_sidebar ] ); 1455 } 1456 } 1457 1458 // Remove orphaned widgets, we're only interested in previously active sidebars. 1459 foreach ( $old_sidebars_widgets as $sidebar => $widgets ) { 1460 if ( 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { 1461 unset( $old_sidebars_widgets[ $sidebar ] ); 1462 } 1463 } 1464 1465 $old_sidebars_widgets = _wp_remove_unregistered_widgets( $old_sidebars_widgets ); 1466 1467 if ( ! empty( $old_sidebars_widgets ) ) { 1468 1469 // Go through each remaining sidebar... 1470 foreach ( $old_sidebars_widgets as $old_sidebar => $old_widgets ) { 1471 1472 // ...and check every new sidebar... 1473 foreach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ) { 1474 1475 // ...for every widget we're trying to revive. 1476 foreach ( $old_widgets as $key => $widget_id ) { 1477 $active_key = array_search( $widget_id, $new_widgets, true ); 1478 1479 // If the widget is used elsewhere... 1480 if ( false !== $active_key ) { 1481 1482 // ...and that elsewhere is inactive widgets... 1483 if ( 'wp_inactive_widgets' === $new_sidebar ) { 1484 1485 // ...remove it from there and keep the active version... 1486 unset( $new_sidebars_widgets['wp_inactive_widgets'][ $active_key ] ); 1487 } else { 1488 1489 // ...otherwise remove it from the old sidebar and keep it in the new one. 1490 unset( $old_sidebars_widgets[ $old_sidebar ][ $key ] ); 1491 } 1492 } // End if ( $active_key ). 1493 } // End foreach ( $old_widgets as $key => $widget_id ). 1494 } // End foreach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ). 1495 } // End foreach ( $old_sidebars_widgets as $old_sidebar => $old_widgets ). 1496 } // End if ( ! empty( $old_sidebars_widgets ) ). 1497 1498 // Restore widget settings from when theme was previously active. 1499 $new_sidebars_widgets = array_merge( $new_sidebars_widgets, $old_sidebars_widgets ); 1500 } 1501 1502 return $new_sidebars_widgets; 1503 } 1504 1505 /** 1506 * Compares a list of sidebars with their widgets against an allowed list. 1507 * 1508 * @since 4.9.0 1509 * 1510 * @param array $sidebars_widgets List of sidebars and their widget instance IDs. 1511 * @param array $allowed_widget_ids Optional. List of widget IDs to compare against. Default: Registered widgets. 1512 * @return array Sidebars with allowed widgets. 1513 */ 1514 function _wp_remove_unregistered_widgets( $sidebars_widgets, $allowed_widget_ids = array() ) { 1515 if ( empty( $allowed_widget_ids ) ) { 1516 $allowed_widget_ids = array_keys( $GLOBALS['wp_registered_widgets'] ); 1517 } 1518 1519 foreach ( $sidebars_widgets as $sidebar => $widgets ) { 1520 if ( is_array( $widgets ) ) { 1521 $sidebars_widgets[ $sidebar ] = array_intersect( $widgets, $allowed_widget_ids ); 1522 } 1523 } 1524 1525 return $sidebars_widgets; 1526 } 1527 1528 /** 1529 * Display the RSS entries in a list. 1530 * 1531 * @since 2.5.0 1532 * 1533 * @param string|array|object $rss RSS url. 1534 * @param array $args Widget arguments. 1535 */ 1536 function wp_widget_rss_output( $rss, $args = array() ) { 1537 if ( is_string( $rss ) ) { 1538 $rss = fetch_feed( $rss ); 1539 } elseif ( is_array( $rss ) && isset( $rss['url'] ) ) { 1540 $args = $rss; 1541 $rss = fetch_feed( $rss['url'] ); 1542 } elseif ( ! is_object( $rss ) ) { 1543 return; 1544 } 1545 1546 if ( is_wp_error( $rss ) ) { 1547 if ( is_admin() || current_user_can( 'manage_options' ) ) { 1548 echo '<p><strong>' . __( 'RSS Error:' ) . '</strong> ' . $rss->get_error_message() . '</p>'; 1549 } 1550 return; 1551 } 1552 1553 $default_args = array( 1554 'show_author' => 0, 1555 'show_date' => 0, 1556 'show_summary' => 0, 1557 'items' => 0, 1558 ); 1559 $args = wp_parse_args( $args, $default_args ); 1560 1561 $items = (int) $args['items']; 1562 if ( $items < 1 || 20 < $items ) { 1563 $items = 10; 1564 } 1565 $show_summary = (int) $args['show_summary']; 1566 $show_author = (int) $args['show_author']; 1567 $show_date = (int) $args['show_date']; 1568 1569 if ( ! $rss->get_item_quantity() ) { 1570 echo '<ul><li>' . __( 'An error has occurred, which probably means the feed is down. Try again later.' ) . '</li></ul>'; 1571 $rss->__destruct(); 1572 unset( $rss ); 1573 return; 1574 } 1575 1576 echo '<ul>'; 1577 foreach ( $rss->get_items( 0, $items ) as $item ) { 1578 $link = $item->get_link(); 1579 while ( ! empty( $link ) && stristr( $link, 'http' ) !== $link ) { 1580 $link = substr( $link, 1 ); 1581 } 1582 $link = esc_url( strip_tags( $link ) ); 1583 1584 $title = esc_html( trim( strip_tags( $item->get_title() ) ) ); 1585 if ( empty( $title ) ) { 1586 $title = __( 'Untitled' ); 1587 } 1588 1589 $desc = html_entity_decode( $item->get_description(), ENT_QUOTES, get_option( 'blog_charset' ) ); 1590 $desc = esc_attr( wp_trim_words( $desc, 55, ' […]' ) ); 1591 1592 $summary = ''; 1593 if ( $show_summary ) { 1594 $summary = $desc; 1595 1596 // Change existing [...] to […]. 1597 if ( '[...]' === substr( $summary, -5 ) ) { 1598 $summary = substr( $summary, 0, -5 ) . '[…]'; 1599 } 1600 1601 $summary = '<div class="rssSummary">' . esc_html( $summary ) . '</div>'; 1602 } 1603 1604 $date = ''; 1605 if ( $show_date ) { 1606 $date = $item->get_date( 'U' ); 1607 1608 if ( $date ) { 1609 $date = ' <span class="rss-date">' . date_i18n( get_option( 'date_format' ), $date ) . '</span>'; 1610 } 1611 } 1612 1613 $author = ''; 1614 if ( $show_author ) { 1615 $author = $item->get_author(); 1616 if ( is_object( $author ) ) { 1617 $author = $author->get_name(); 1618 $author = ' <cite>' . esc_html( strip_tags( $author ) ) . '</cite>'; 1619 } 1620 } 1621 1622 if ( '' === $link ) { 1623 echo "<li>$title{$date}{$summary}{$author}</li>"; 1624 } elseif ( $show_summary ) { 1625 echo "<li><a class='rsswidget' href='$link'>$title</a>{$date}{$summary}{$author}</li>"; 1626 } else { 1627 echo "<li><a class='rsswidget' href='$link'>$title</a>{$date}{$author}</li>"; 1628 } 1629 } 1630 echo '</ul>'; 1631 $rss->__destruct(); 1632 unset( $rss ); 1633 } 1634 1635 /** 1636 * Display RSS widget options form. 1637 * 1638 * The options for what fields are displayed for the RSS form are all booleans 1639 * and are as follows: 'url', 'title', 'items', 'show_summary', 'show_author', 1640 * 'show_date'. 1641 * 1642 * @since 2.5.0 1643 * 1644 * @param array|string $args Values for input fields. 1645 * @param array $inputs Override default display options. 1646 */ 1647 function wp_widget_rss_form( $args, $inputs = null ) { 1648 $default_inputs = array( 1649 'url' => true, 1650 'title' => true, 1651 'items' => true, 1652 'show_summary' => true, 1653 'show_author' => true, 1654 'show_date' => true, 1655 ); 1656 $inputs = wp_parse_args( $inputs, $default_inputs ); 1657 1658 $args['title'] = isset( $args['title'] ) ? $args['title'] : ''; 1659 $args['url'] = isset( $args['url'] ) ? $args['url'] : ''; 1660 $args['items'] = isset( $args['items'] ) ? (int) $args['items'] : 0; 1661 1662 if ( $args['items'] < 1 || 20 < $args['items'] ) { 1663 $args['items'] = 10; 1664 } 1665 1666 $args['show_summary'] = isset( $args['show_summary'] ) ? (int) $args['show_summary'] : (int) $inputs['show_summary']; 1667 $args['show_author'] = isset( $args['show_author'] ) ? (int) $args['show_author'] : (int) $inputs['show_author']; 1668 $args['show_date'] = isset( $args['show_date'] ) ? (int) $args['show_date'] : (int) $inputs['show_date']; 1669 1670 if ( ! empty( $args['error'] ) ) { 1671 echo '<p class="widget-error"><strong>' . __( 'RSS Error:' ) . '</strong> ' . $args['error'] . '</p>'; 1672 } 1673 1674 $esc_number = esc_attr( $args['number'] ); 1675 if ( $inputs['url'] ) : 1676 ?> 1677 <p><label for="rss-url-<?php echo $esc_number; ?>"><?php _e( 'Enter the RSS feed URL here:' ); ?></label> 1678 <input class="widefat" id="rss-url-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][url]" type="text" value="<?php echo esc_url( $args['url'] ); ?>" /></p> 1679 <?php endif; if ( $inputs['title'] ) : ?> 1680 <p><label for="rss-title-<?php echo $esc_number; ?>"><?php _e( 'Give the feed a title (optional):' ); ?></label> 1681 <input class="widefat" id="rss-title-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][title]" type="text" value="<?php echo esc_attr( $args['title'] ); ?>" /></p> 1682 <?php endif; if ( $inputs['items'] ) : ?> 1683 <p><label for="rss-items-<?php echo $esc_number; ?>"><?php _e( 'How many items would you like to display?' ); ?></label> 1684 <select id="rss-items-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][items]"> 1685 <?php 1686 for ( $i = 1; $i <= 20; ++$i ) { 1687 echo "<option value='$i' " . selected( $args['items'], $i, false ) . ">$i</option>"; 1688 } 1689 ?> 1690 </select></p> 1691 <?php endif; if ( $inputs['show_summary'] || $inputs['show_author'] || $inputs['show_date'] ) : ?> 1692 <p> 1693 <?php if ( $inputs['show_summary'] ) : ?> 1694 <input id="rss-show-summary-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][show_summary]" type="checkbox" value="1" <?php checked( $args['show_summary'] ); ?> /> 1695 <label for="rss-show-summary-<?php echo $esc_number; ?>"><?php _e( 'Display item content?' ); ?></label><br /> 1696 <?php endif; if ( $inputs['show_author'] ) : ?> 1697 <input id="rss-show-author-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][show_author]" type="checkbox" value="1" <?php checked( $args['show_author'] ); ?> /> 1698 <label for="rss-show-author-<?php echo $esc_number; ?>"><?php _e( 'Display item author if available?' ); ?></label><br /> 1699 <?php endif; if ( $inputs['show_date'] ) : ?> 1700 <input id="rss-show-date-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][show_date]" type="checkbox" value="1" <?php checked( $args['show_date'] ); ?>/> 1701 <label for="rss-show-date-<?php echo $esc_number; ?>"><?php _e( 'Display item date?' ); ?></label><br /> 1702 <?php endif; ?> 1703 </p> 1704 <?php 1705 endif; // End of display options. 1706 foreach ( array_keys( $default_inputs ) as $input ) : 1707 if ( 'hidden' === $inputs[ $input ] ) : 1708 $id = str_replace( '_', '-', $input ); 1709 ?> 1710 <input type="hidden" id="rss-<?php echo esc_attr( $id ); ?>-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][<?php echo esc_attr( $input ); ?>]" value="<?php echo esc_attr( $args[ $input ] ); ?>" /> 1711 <?php 1712 endif; 1713 endforeach; 1714 } 1715 1716 /** 1717 * Process RSS feed widget data and optionally retrieve feed items. 1718 * 1719 * The feed widget can not have more than 20 items or it will reset back to the 1720 * default, which is 10. 1721 * 1722 * The resulting array has the feed title, feed url, feed link (from channel), 1723 * feed items, error (if any), and whether to show summary, author, and date. 1724 * All respectively in the order of the array elements. 1725 * 1726 * @since 2.5.0 1727 * 1728 * @param array $widget_rss RSS widget feed data. Expects unescaped data. 1729 * @param bool $check_feed Optional. Whether to check feed for errors. Default true. 1730 * @return array 1731 */ 1732 function wp_widget_rss_process( $widget_rss, $check_feed = true ) { 1733 $items = (int) $widget_rss['items']; 1734 if ( $items < 1 || 20 < $items ) { 1735 $items = 10; 1736 } 1737 $url = esc_url_raw( strip_tags( $widget_rss['url'] ) ); 1738 $title = isset( $widget_rss['title'] ) ? trim( strip_tags( $widget_rss['title'] ) ) : ''; 1739 $show_summary = isset( $widget_rss['show_summary'] ) ? (int) $widget_rss['show_summary'] : 0; 1740 $show_author = isset( $widget_rss['show_author'] ) ? (int) $widget_rss['show_author'] : 0; 1741 $show_date = isset( $widget_rss['show_date'] ) ? (int) $widget_rss['show_date'] : 0; 1742 $error = false; 1743 $link = ''; 1744 1745 if ( $check_feed ) { 1746 $rss = fetch_feed( $url ); 1747 1748 if ( is_wp_error( $rss ) ) { 1749 $error = $rss->get_error_message(); 1750 } else { 1751 $link = esc_url( strip_tags( $rss->get_permalink() ) ); 1752 while ( stristr( $link, 'http' ) !== $link ) { 1753 $link = substr( $link, 1 ); 1754 } 1755 1756 $rss->__destruct(); 1757 unset( $rss ); 1758 } 1759 } 1760 1761 return compact( 'title', 'url', 'link', 'items', 'error', 'show_summary', 'show_author', 'show_date' ); 1762 } 1763 1764 /** 1765 * Registers all of the default WordPress widgets on startup. 1766 * 1767 * Calls {@see 'widgets_init'} action after all of the WordPress widgets have been registered. 1768 * 1769 * @since 2.2.0 1770 */ 1771 function wp_widgets_init() { 1772 if ( ! is_blog_installed() ) { 1773 return; 1774 } 1775 1776 register_widget( 'WP_Widget_Pages' ); 1777 1778 register_widget( 'WP_Widget_Calendar' ); 1779 1780 register_widget( 'WP_Widget_Archives' ); 1781 1782 if ( get_option( 'link_manager_enabled' ) ) { 1783 register_widget( 'WP_Widget_Links' ); 1784 } 1785 1786 register_widget( 'WP_Widget_Media_Audio' ); 1787 1788 register_widget( 'WP_Widget_Media_Image' ); 1789 1790 register_widget( 'WP_Widget_Media_Gallery' ); 1791 1792 register_widget( 'WP_Widget_Media_Video' ); 1793 1794 register_widget( 'WP_Widget_Meta' ); 1795 1796 register_widget( 'WP_Widget_Search' ); 1797 1798 register_widget( 'WP_Widget_Text' ); 1799 1800 register_widget( 'WP_Widget_Categories' ); 1801 1802 register_widget( 'WP_Widget_Recent_Posts' ); 1803 1804 register_widget( 'WP_Widget_Recent_Comments' ); 1805 1806 register_widget( 'WP_Widget_RSS' ); 1807 1808 register_widget( 'WP_Widget_Tag_Cloud' ); 1809 1810 register_widget( 'WP_Nav_Menu_Widget' ); 1811 1812 register_widget( 'WP_Widget_Custom_HTML' ); 1813 1814 register_widget( 'WP_Widget_Block' ); 1815 1816 /** 1817 * Fires after all default WordPress widgets have been registered. 1818 * 1819 * @since 2.2.0 1820 */ 1821 do_action( 'widgets_init' ); 1822 } 1823 1824 /** 1825 * Enables the widgets block editor. This is hooked into 'after_setup_theme' so 1826 * that the block editor is enabled by default but can be disabled by themes. 1827 * 1828 * @since 5.8.0 1829 * 1830 * @access private 1831 */ 1832 function wp_setup_widgets_block_editor() { 1833 add_theme_support( 'widgets-block-editor' ); 1834 } 1835 1836 /** 1837 * Whether or not to use the block editor to manage widgets. Defaults to true 1838 * unless a theme has removed support for widgets-block-editor or a plugin has 1839 * filtered the return value of this function. 1840 * 1841 * @since 5.8.0 1842 * 1843 * @return bool Whether to use the block editor to manage widgets. 1844 */ 1845 function wp_use_widgets_block_editor() { 1846 /** 1847 * Filters whether to use the block editor to manage widgets. 1848 * 1849 * @since 5.8.0 1850 * 1851 * @param bool $use_widgets_block_editor Whether to use the block editor to manage widgets. 1852 */ 1853 return apply_filters( 1854 'use_widgets_block_editor', 1855 get_theme_support( 'widgets-block-editor' ) 1856 ); 1857 } 1858 1859 /** 1860 * Converts a widget ID into its id_base and number components. 1861 * 1862 * @since 5.8.0 1863 * 1864 * @param string $id Widget ID. 1865 * @return array Array containing a widget's id_base and number components. 1866 */ 1867 function wp_parse_widget_id( $id ) { 1868 $parsed = array(); 1869 1870 if ( preg_match( '/^(.+)-(\d+)$/', $id, $matches ) ) { 1871 $parsed['id_base'] = $matches[1]; 1872 $parsed['number'] = (int) $matches[2]; 1873 } else { 1874 // Likely an old single widget. 1875 $parsed['id_base'] = $id; 1876 } 1877 1878 return $parsed; 1879 } 1880 1881 /** 1882 * Finds the sidebar that a given widget belongs to. 1883 * 1884 * @since 5.8.0 1885 * 1886 * @param string $widget_id The widget id to look for. 1887 * @return string|null The found sidebar's id, or null if it was not found. 1888 */ 1889 function wp_find_widgets_sidebar( $widget_id ) { 1890 foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) { 1891 foreach ( $widget_ids as $maybe_widget_id ) { 1892 if ( $maybe_widget_id === $widget_id ) { 1893 return (string) $sidebar_id; 1894 } 1895 } 1896 } 1897 1898 return null; 1899 } 1900 1901 /** 1902 * Assigns a widget to the given sidebar. 1903 * 1904 * @since 5.8.0 1905 * 1906 * @param string $widget_id The widget id to assign. 1907 * @param string $sidebar_id The sidebar id to assign to. If empty, the widget won't be added to any sidebar. 1908 */ 1909 function wp_assign_widget_to_sidebar( $widget_id, $sidebar_id ) { 1910 $sidebars = wp_get_sidebars_widgets(); 1911 1912 foreach ( $sidebars as $maybe_sidebar_id => $widgets ) { 1913 foreach ( $widgets as $i => $maybe_widget_id ) { 1914 if ( $widget_id === $maybe_widget_id && $sidebar_id !== $maybe_sidebar_id ) { 1915 unset( $sidebars[ $maybe_sidebar_id ][ $i ] ); 1916 // We could technically break 2 here, but continue looping in case the id is duplicated. 1917 continue 2; 1918 } 1919 } 1920 } 1921 1922 if ( $sidebar_id ) { 1923 $sidebars[ $sidebar_id ][] = $widget_id; 1924 } 1925 1926 wp_set_sidebars_widgets( $sidebars ); 1927 } 1928 1929 /** 1930 * Calls the render callback of a widget and returns the output. 1931 * 1932 * @since 5.8.0 1933 * 1934 * @param string $widget_id Widget ID. 1935 * @param string $sidebar_id Sidebar ID. 1936 * @return string 1937 */ 1938 function wp_render_widget( $widget_id, $sidebar_id ) { 1939 global $wp_registered_widgets, $wp_registered_sidebars; 1940 1941 if ( ! isset( $wp_registered_widgets[ $widget_id ] ) ) { 1942 return ''; 1943 } 1944 1945 if ( isset( $wp_registered_sidebars[ $sidebar_id ] ) ) { 1946 $sidebar = $wp_registered_sidebars[ $sidebar_id ]; 1947 } elseif ( 'wp_inactive_widgets' === $sidebar_id ) { 1948 $sidebar = array(); 1949 } else { 1950 return ''; 1951 } 1952 1953 $params = array_merge( 1954 array( 1955 array_merge( 1956 $sidebar, 1957 array( 1958 'widget_id' => $widget_id, 1959 'widget_name' => $wp_registered_widgets[ $widget_id ]['name'], 1960 ) 1961 ), 1962 ), 1963 (array) $wp_registered_widgets[ $widget_id ]['params'] 1964 ); 1965 1966 // Substitute HTML `id` and `class` attributes into `before_widget`. 1967 $classname_ = ''; 1968 foreach ( (array) $wp_registered_widgets[ $widget_id ]['classname'] as $cn ) { 1969 if ( is_string( $cn ) ) { 1970 $classname_ .= '_' . $cn; 1971 } elseif ( is_object( $cn ) ) { 1972 $classname_ .= '_' . get_class( $cn ); 1973 } 1974 } 1975 $classname_ = ltrim( $classname_, '_' ); 1976 $params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $widget_id, $classname_ ); 1977 1978 /** This filter is documented in wp-includes/widgets.php */ 1979 $params = apply_filters( 'dynamic_sidebar_params', $params ); 1980 1981 $callback = $wp_registered_widgets[ $widget_id ]['callback']; 1982 1983 ob_start(); 1984 1985 /** This filter is documented in wp-includes/widgets.php */ 1986 do_action( 'dynamic_sidebar', $wp_registered_widgets[ $widget_id ] ); 1987 1988 if ( is_callable( $callback ) ) { 1989 call_user_func_array( $callback, $params ); 1990 } 1991 1992 return ob_get_clean(); 1993 } 1994 1995 /** 1996 * Calls the control callback of a widget and returns the output. 1997 * 1998 * @since 5.8.0 1999 * 2000 * @param string $id Widget ID. 2001 * @return string|null 2002 */ 2003 function wp_render_widget_control( $id ) { 2004 global $wp_registered_widget_controls; 2005 2006 if ( ! isset( $wp_registered_widget_controls[ $id ]['callback'] ) ) { 2007 return null; 2008 } 2009 2010 $callback = $wp_registered_widget_controls[ $id ]['callback']; 2011 $params = $wp_registered_widget_controls[ $id ]['params']; 2012 2013 ob_start(); 2014 2015 if ( is_callable( $callback ) ) { 2016 call_user_func_array( $callback, $params ); 2017 } 2018 2019 return ob_get_clean(); 2020 } 2021 2022 /** 2023 * Displays a _doing_it_wrong() message for conflicting widget editor scripts. 2024 * 2025 * The 'wp-editor' script module is exposed as window.wp.editor. This overrides 2026 * the legacy TinyMCE editor module which is required by the widgets editor. 2027 * Because of that conflict, these two shouldn't be enqueued together. 2028 * See https://core.trac.wordpress.org/ticket/53569. 2029 * 2030 * There is also another conflict related to styles where the block widgets 2031 * editor is hidden if a block enqueues 'wp-edit-post' stylesheet. 2032 * See https://core.trac.wordpress.org/ticket/53569. 2033 * 2034 * @since 5.8.0 2035 * @access private 2036 * 2037 * @global WP_Scripts $wp_scripts 2038 * @global WP_Styles $wp_styles 2039 */ 2040 function wp_check_widget_editor_deps() { 2041 global $wp_scripts, $wp_styles; 2042 2043 if ( 2044 $wp_scripts->query( 'wp-edit-widgets', 'enqueued' ) || 2045 $wp_scripts->query( 'wp-customize-widgets', 'enqueued' ) 2046 ) { 2047 if ( $wp_scripts->query( 'wp-editor', 'enqueued' ) ) { 2048 _doing_it_wrong( 2049 'wp_enqueue_script()', 2050 sprintf( 2051 /* translators: 1: 'wp-editor', 2: 'wp-edit-widgets', 3: 'wp-customize-widgets'. */ 2052 __( '"%1$s" script should not be enqueued together with the new widgets editor (%2$s or %3$s).' ), 2053 'wp-editor', 2054 'wp-edit-widgets', 2055 'wp-customize-widgets' 2056 ), 2057 '5.8.0' 2058 ); 2059 } 2060 if ( $wp_styles->query( 'wp-edit-post', 'enqueued' ) ) { 2061 _doing_it_wrong( 2062 'wp_enqueue_style()', 2063 sprintf( 2064 /* translators: 1: 'wp-edit-post', 2: 'wp-edit-widgets', 3: 'wp-customize-widgets'. */ 2065 __( '"%1$s" style should not be enqueued together with the new widgets editor (%2$s or %3$s).' ), 2066 'wp-edit-post', 2067 'wp-edit-widgets', 2068 'wp-customize-widgets' 2069 ), 2070 '5.8.0' 2071 ); 2072 } 2073 } 2074 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Thu Sep 23 01:00:04 2021 | Cross-referenced by PHPXref 0.7.1 |