| [ 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 control (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 ID's 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 * 223 * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID. 224 * 225 * @param array|string $args { 226 * Optional. Array or string of arguments for the sidebar being registered. 227 * 228 * @type string $name The name or title of the sidebar displayed in the Widgets 229 * interface. Default 'Sidebar $instance'. 230 * @type string $id The unique identifier by which the sidebar will be called. 231 * Default 'sidebar-$instance'. 232 * @type string $description Description of the sidebar, displayed in the Widgets interface. 233 * Default empty string. 234 * @type string $class Extra CSS class to assign to the sidebar in the Widgets interface. 235 * Default empty. 236 * @type string $before_widget HTML content to prepend to each widget's HTML output when 237 * assigned to this sidebar. Default is an opening list item element. 238 * @type string $after_widget HTML content to append to each widget's HTML output when 239 * assigned to this sidebar. Default is a closing list item element. 240 * @type string $before_title HTML content to prepend to the sidebar title when displayed. 241 * Default is an opening h2 element. 242 * @type string $after_title HTML content to append to the sidebar title when displayed. 243 * Default is a closing h2 element. 244 * } 245 * @return string Sidebar ID added to $wp_registered_sidebars global. 246 */ 247 function register_sidebar( $args = array() ) { 248 global $wp_registered_sidebars; 249 250 $i = count( $wp_registered_sidebars ) + 1; 251 252 $id_is_empty = empty( $args['id'] ); 253 254 $defaults = array( 255 /* translators: %d: Sidebar number. */ 256 'name' => sprintf( __( 'Sidebar %d' ), $i ), 257 'id' => "sidebar-$i", 258 'description' => '', 259 'class' => '', 260 'before_widget' => '<li id="%1$s" class="widget %2$s">', 261 'after_widget' => "</li>\n", 262 'before_title' => '<h2 class="widgettitle">', 263 'after_title' => "</h2>\n", 264 ); 265 266 /** 267 * Filters the sidebar default arguments. 268 * 269 * @since 5.3.0 270 * 271 * @see register_sidebar() 272 * 273 * @param array $defaults The default sidebar arguments. 274 */ 275 $sidebar = wp_parse_args( $args, apply_filters( 'register_sidebar_defaults', $defaults ) ); 276 277 if ( $id_is_empty ) { 278 _doing_it_wrong( 279 __FUNCTION__, 280 sprintf( 281 /* translators: 1: The 'id' argument, 2: Sidebar name, 3: Recommended 'id' value. */ 282 __( '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.' ), 283 '<code>id</code>', 284 $sidebar['name'], 285 $sidebar['id'] 286 ), 287 '4.2.0' 288 ); 289 } 290 291 $wp_registered_sidebars[ $sidebar['id'] ] = $sidebar; 292 293 add_theme_support( 'widgets' ); 294 295 /** 296 * Fires once a sidebar has been registered. 297 * 298 * @since 3.0.0 299 * 300 * @param array $sidebar Parsed arguments for the registered sidebar. 301 */ 302 do_action( 'register_sidebar', $sidebar ); 303 304 return $sidebar['id']; 305 } 306 307 /** 308 * Removes a sidebar from the list. 309 * 310 * @since 2.2.0 311 * 312 * @global array $wp_registered_sidebars Removes the sidebar from this array by sidebar ID. 313 * 314 * @param string|int $sidebar_id The ID of the sidebar when it was registered. 315 */ 316 function unregister_sidebar( $sidebar_id ) { 317 global $wp_registered_sidebars; 318 319 unset( $wp_registered_sidebars[ $sidebar_id ] ); 320 } 321 322 /** 323 * Checks if a sidebar is registered. 324 * 325 * @since 4.4.0 326 * 327 * @global array $wp_registered_sidebars Registered sidebars. 328 * 329 * @param string|int $sidebar_id The ID of the sidebar when it was registered. 330 * @return bool True if the sidebar is registered, false otherwise. 331 */ 332 function is_registered_sidebar( $sidebar_id ) { 333 global $wp_registered_sidebars; 334 335 return isset( $wp_registered_sidebars[ $sidebar_id ] ); 336 } 337 338 /** 339 * Register an instance of a widget. 340 * 341 * The default widget option is 'classname' that can be overridden. 342 * 343 * The function can also be used to un-register widgets when `$output_callback` 344 * parameter is an empty string. 345 * 346 * @since 2.2.0 347 * 348 * @global array $wp_registered_widgets Uses stored registered widgets. 349 * @global array $wp_registered_widget_controls Stores the registered widget controls (options). 350 * @global array $wp_registered_widget_updates 351 * @global array $_wp_deprecated_widgets_callbacks 352 * 353 * @param int|string $id Widget ID. 354 * @param string $name Widget display title. 355 * @param callable $output_callback Run when widget is called. 356 * @param array $options { 357 * Optional. An array of supplementary widget options for the instance. 358 * 359 * @type string $classname Class name for the widget's HTML container. Default is a shortened 360 * version of the output callback name. 361 * @type string $description Widget description for display in the widget administration 362 * panel and/or theme. 363 * } 364 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 365 */ 366 function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) { 367 global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks; 368 369 $id = strtolower( $id ); 370 371 if ( empty( $output_callback ) ) { 372 unset( $wp_registered_widgets[ $id ] ); 373 return; 374 } 375 376 $id_base = _get_widget_id_base( $id ); 377 if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) { 378 unset( $wp_registered_widget_controls[ $id ] ); 379 unset( $wp_registered_widget_updates[ $id_base ] ); 380 return; 381 } 382 383 $defaults = array( 'classname' => $output_callback ); 384 $options = wp_parse_args( $options, $defaults ); 385 $widget = array( 386 'name' => $name, 387 'id' => $id, 388 'callback' => $output_callback, 389 'params' => $params, 390 ); 391 $widget = array_merge( $widget, $options ); 392 393 if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) { 394 395 /** 396 * Fires once for each registered widget. 397 * 398 * @since 3.0.0 399 * 400 * @param array $widget An array of default widget arguments. 401 */ 402 do_action( 'wp_register_sidebar_widget', $widget ); 403 $wp_registered_widgets[ $id ] = $widget; 404 } 405 } 406 407 /** 408 * Retrieve description for widget. 409 * 410 * When registering widgets, the options can also include 'description' that 411 * describes the widget for display on the widget administration panel or 412 * in the theme. 413 * 414 * @since 2.5.0 415 * 416 * @global array $wp_registered_widgets 417 * 418 * @param int|string $id Widget ID. 419 * @return string|void Widget description, if available. 420 */ 421 function wp_widget_description( $id ) { 422 if ( ! is_scalar( $id ) ) { 423 return; 424 } 425 426 global $wp_registered_widgets; 427 428 if ( isset( $wp_registered_widgets[ $id ]['description'] ) ) { 429 return esc_html( $wp_registered_widgets[ $id ]['description'] ); 430 } 431 } 432 433 /** 434 * Retrieve description for a sidebar. 435 * 436 * When registering sidebars a 'description' parameter can be included that 437 * describes the sidebar for display on the widget administration panel. 438 * 439 * @since 2.9.0 440 * 441 * @global array $wp_registered_sidebars Registered sidebars. 442 * 443 * @param string $id sidebar ID. 444 * @return string|void Sidebar description, if available. 445 */ 446 function wp_sidebar_description( $id ) { 447 if ( ! is_scalar( $id ) ) { 448 return; 449 } 450 451 global $wp_registered_sidebars; 452 453 if ( isset( $wp_registered_sidebars[ $id ]['description'] ) ) { 454 return wp_kses( $wp_registered_sidebars[ $id ]['description'], 'sidebar_description' ); 455 } 456 } 457 458 /** 459 * Remove widget from sidebar. 460 * 461 * @since 2.2.0 462 * 463 * @param int|string $id Widget ID. 464 */ 465 function wp_unregister_sidebar_widget( $id ) { 466 467 /** 468 * Fires just before a widget is removed from a sidebar. 469 * 470 * @since 3.0.0 471 * 472 * @param int $id The widget ID. 473 */ 474 do_action( 'wp_unregister_sidebar_widget', $id ); 475 476 wp_register_sidebar_widget( $id, '', '' ); 477 wp_unregister_widget_control( $id ); 478 } 479 480 /** 481 * Registers widget control callback for customizing options. 482 * 483 * @since 2.2.0 484 * 485 * @global array $wp_registered_widget_controls 486 * @global array $wp_registered_widget_updates 487 * @global array $wp_registered_widgets 488 * @global array $_wp_deprecated_widgets_callbacks 489 * 490 * @param int|string $id Sidebar ID. 491 * @param string $name Sidebar display name. 492 * @param callable $control_callback Run when sidebar is displayed. 493 * @param array $options { 494 * Optional. Array or string of control options. Default empty array. 495 * 496 * @type int $height Never used. Default 200. 497 * @type int $width Width of the fully expanded control form (but try hard to use the default width). 498 * Default 250. 499 * @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the 500 * text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`. 501 * } 502 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 503 */ 504 function wp_register_widget_control( $id, $name, $control_callback, $options = array(), ...$params ) { 505 global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks; 506 507 $id = strtolower( $id ); 508 $id_base = _get_widget_id_base( $id ); 509 510 if ( empty( $control_callback ) ) { 511 unset( $wp_registered_widget_controls[ $id ] ); 512 unset( $wp_registered_widget_updates[ $id_base ] ); 513 return; 514 } 515 516 if ( in_array( $control_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $control_callback ) ) { 517 unset( $wp_registered_widgets[ $id ] ); 518 return; 519 } 520 521 if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) { 522 return; 523 } 524 525 $defaults = array( 526 'width' => 250, 527 'height' => 200, 528 ); // height is never used 529 $options = wp_parse_args( $options, $defaults ); 530 $options['width'] = (int) $options['width']; 531 $options['height'] = (int) $options['height']; 532 533 $widget = array( 534 'name' => $name, 535 'id' => $id, 536 'callback' => $control_callback, 537 'params' => $params, 538 ); 539 $widget = array_merge( $widget, $options ); 540 541 $wp_registered_widget_controls[ $id ] = $widget; 542 543 if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) { 544 return; 545 } 546 547 if ( isset( $widget['params'][0]['number'] ) ) { 548 $widget['params'][0]['number'] = -1; 549 } 550 551 unset( $widget['width'], $widget['height'], $widget['name'], $widget['id'] ); 552 $wp_registered_widget_updates[ $id_base ] = $widget; 553 } 554 555 /** 556 * Registers the update callback for a widget. 557 * 558 * @since 2.8.0 559 * 560 * @global array $wp_registered_widget_updates 561 * 562 * @param string $id_base The base ID of a widget created by extending WP_Widget. 563 * @param callable $update_callback Update callback method for the widget. 564 * @param array $options Optional. Widget control options. See wp_register_widget_control(). 565 * Default empty array. 566 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 567 */ 568 function _register_widget_update_callback( $id_base, $update_callback, $options = array(), ...$params ) { 569 global $wp_registered_widget_updates; 570 571 if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) { 572 if ( empty( $update_callback ) ) { 573 unset( $wp_registered_widget_updates[ $id_base ] ); 574 } 575 return; 576 } 577 578 $widget = array( 579 'callback' => $update_callback, 580 'params' => $params, 581 ); 582 583 $widget = array_merge( $widget, $options ); 584 $wp_registered_widget_updates[ $id_base ] = $widget; 585 } 586 587 /** 588 * Registers the form callback for a widget. 589 * 590 * @since 2.8.0 591 * 592 * @global array $wp_registered_widget_controls 593 * 594 * @param int|string $id Widget ID. 595 * @param string $name Name attribute for the widget. 596 * @param callable $form_callback Form callback. 597 * @param array $options Optional. Widget control options. See wp_register_widget_control(). 598 * Default empty array. 599 * @param mixed ...$params Optional additional parameters to pass to the callback function when it's called. 600 */ 601 602 function _register_widget_form_callback( $id, $name, $form_callback, $options = array(), ...$params ) { 603 global $wp_registered_widget_controls; 604 605 $id = strtolower( $id ); 606 607 if ( empty( $form_callback ) ) { 608 unset( $wp_registered_widget_controls[ $id ] ); 609 return; 610 } 611 612 if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) { 613 return; 614 } 615 616 $defaults = array( 617 'width' => 250, 618 'height' => 200, 619 ); 620 $options = wp_parse_args( $options, $defaults ); 621 $options['width'] = (int) $options['width']; 622 $options['height'] = (int) $options['height']; 623 624 $widget = array( 625 'name' => $name, 626 'id' => $id, 627 'callback' => $form_callback, 628 'params' => $params, 629 ); 630 $widget = array_merge( $widget, $options ); 631 632 $wp_registered_widget_controls[ $id ] = $widget; 633 } 634 635 /** 636 * Remove control callback for widget. 637 * 638 * @since 2.2.0 639 * 640 * @param int|string $id Widget ID. 641 */ 642 function wp_unregister_widget_control( $id ) { 643 wp_register_widget_control( $id, '', '' ); 644 } 645 646 /** 647 * Display dynamic sidebar. 648 * 649 * By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or 650 * 'name' parameter for its registered sidebars you can pass an id or name as the $index parameter. 651 * Otherwise, you can pass in a numerical index to display the sidebar at that index. 652 * 653 * @since 2.2.0 654 * 655 * @global array $wp_registered_sidebars Registered sidebars. 656 * @global array $wp_registered_widgets 657 * 658 * @param int|string $index Optional, default is 1. Index, name or ID of dynamic sidebar. 659 * @return bool True, if widget sidebar was found and called. False if not found or not called. 660 */ 661 function dynamic_sidebar( $index = 1 ) { 662 global $wp_registered_sidebars, $wp_registered_widgets; 663 664 if ( is_int( $index ) ) { 665 $index = "sidebar-$index"; 666 } else { 667 $index = sanitize_title( $index ); 668 foreach ( (array) $wp_registered_sidebars as $key => $value ) { 669 if ( sanitize_title( $value['name'] ) == $index ) { 670 $index = $key; 671 break; 672 } 673 } 674 } 675 676 $sidebars_widgets = wp_get_sidebars_widgets(); 677 if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { 678 /** This action is documented in wp-includes/widget.php */ 679 do_action( 'dynamic_sidebar_before', $index, false ); 680 /** This action is documented in wp-includes/widget.php */ 681 do_action( 'dynamic_sidebar_after', $index, false ); 682 /** This filter is documented in wp-includes/widget.php */ 683 return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); 684 } 685 686 /** 687 * Fires before widgets are rendered in a dynamic sidebar. 688 * 689 * Note: The action also fires for empty sidebars, and on both the front end 690 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 691 * 692 * @since 3.9.0 693 * 694 * @param int|string $index Index, name, or ID of the dynamic sidebar. 695 * @param bool $has_widgets Whether the sidebar is populated with widgets. 696 * Default true. 697 */ 698 do_action( 'dynamic_sidebar_before', $index, true ); 699 $sidebar = $wp_registered_sidebars[ $index ]; 700 701 $did_one = false; 702 foreach ( (array) $sidebars_widgets[ $index ] as $id ) { 703 704 if ( ! isset( $wp_registered_widgets[ $id ] ) ) { 705 continue; 706 } 707 708 $params = array_merge( 709 array( 710 array_merge( 711 $sidebar, 712 array( 713 'widget_id' => $id, 714 'widget_name' => $wp_registered_widgets[ $id ]['name'], 715 ) 716 ), 717 ), 718 (array) $wp_registered_widgets[ $id ]['params'] 719 ); 720 721 // Substitute HTML id and class attributes into before_widget 722 $classname_ = ''; 723 foreach ( (array) $wp_registered_widgets[ $id ]['classname'] as $cn ) { 724 if ( is_string( $cn ) ) { 725 $classname_ .= '_' . $cn; 726 } elseif ( is_object( $cn ) ) { 727 $classname_ .= '_' . get_class( $cn ); 728 } 729 } 730 $classname_ = ltrim( $classname_, '_' ); 731 $params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $id, $classname_ ); 732 733 /** 734 * Filters the parameters passed to a widget's display callback. 735 * 736 * Note: The filter is evaluated on both the front end and back end, 737 * including for the Inactive Widgets sidebar on the Widgets screen. 738 * 739 * @since 2.5.0 740 * 741 * @see register_sidebar() 742 * 743 * @param array $params { 744 * @type array $args { 745 * An array of widget display arguments. 746 * 747 * @type string $name Name of the sidebar the widget is assigned to. 748 * @type string $id ID of the sidebar the widget is assigned to. 749 * @type string $description The sidebar description. 750 * @type string $class CSS class applied to the sidebar container. 751 * @type string $before_widget HTML markup to prepend to each widget in the sidebar. 752 * @type string $after_widget HTML markup to append to each widget in the sidebar. 753 * @type string $before_title HTML markup to prepend to the widget title when displayed. 754 * @type string $after_title HTML markup to append to the widget title when displayed. 755 * @type string $widget_id ID of the widget. 756 * @type string $widget_name Name of the widget. 757 * } 758 * @type array $widget_args { 759 * An array of multi-widget arguments. 760 * 761 * @type int $number Number increment used for multiples of the same widget. 762 * } 763 * } 764 */ 765 $params = apply_filters( 'dynamic_sidebar_params', $params ); 766 767 $callback = $wp_registered_widgets[ $id ]['callback']; 768 769 /** 770 * Fires before a widget's display callback is called. 771 * 772 * Note: The action fires on both the front end and back end, including 773 * for widgets in the Inactive Widgets sidebar on the Widgets screen. 774 * 775 * The action is not fired for empty sidebars. 776 * 777 * @since 3.0.0 778 * 779 * @param array $widget_id { 780 * An associative array of widget arguments. 781 * 782 * @type string $name Name of the widget. 783 * @type string $id Widget ID. 784 * @type array|callable $callback When the hook is fired on the front end, $callback is an array 785 * containing the widget object. Fired on the back end, $callback 786 * is 'wp_widget_control', see $_callback. 787 * @type array $params An associative array of multi-widget arguments. 788 * @type string $classname CSS class applied to the widget container. 789 * @type string $description The widget description. 790 * @type array $_callback When the hook is fired on the back end, $_callback is populated 791 * with an array containing the widget object, see $callback. 792 * } 793 */ 794 do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); 795 796 if ( is_callable( $callback ) ) { 797 call_user_func_array( $callback, $params ); 798 $did_one = true; 799 } 800 } 801 802 /** 803 * Fires after widgets are rendered in a dynamic sidebar. 804 * 805 * Note: The action also fires for empty sidebars, and on both the front end 806 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 807 * 808 * @since 3.9.0 809 * 810 * @param int|string $index Index, name, or ID of the dynamic sidebar. 811 * @param bool $has_widgets Whether the sidebar is populated with widgets. 812 * Default true. 813 */ 814 do_action( 'dynamic_sidebar_after', $index, true ); 815 816 /** 817 * Filters whether a sidebar has widgets. 818 * 819 * Note: The filter is also evaluated for empty sidebars, and on both the front end 820 * and back end, including the Inactive Widgets sidebar on the Widgets screen. 821 * 822 * @since 3.9.0 823 * 824 * @param bool $did_one Whether at least one widget was rendered in the sidebar. 825 * Default false. 826 * @param int|string $index Index, name, or ID of the dynamic sidebar. 827 */ 828 return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index ); 829 } 830 831 /** 832 * Determines whether a given widget is displayed on the front end. 833 * 834 * Either $callback or $id_base can be used 835 * $id_base is the first argument when extending WP_Widget class 836 * Without the optional $widget_id parameter, returns the ID of the first sidebar 837 * in which the first instance of the widget with the given callback or $id_base is found. 838 * With the $widget_id parameter, returns the ID of the sidebar where 839 * the widget with that callback/$id_base AND that ID is found. 840 * 841 * NOTE: $widget_id and $id_base are the same for single widgets. To be effective 842 * this function has to run after widgets have initialized, at action {@see 'init'} or later. 843 * 844 * For more information on this and similar theme functions, check out 845 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 846 * Conditional Tags} article in the Theme Developer Handbook. 847 * 848 * @since 2.2.0 849 * 850 * @global array $wp_registered_widgets 851 * 852 * @param string|false $callback Optional, Widget callback to check. Default false. 853 * @param int|false $widget_id Optional. Widget ID. Optional, but needed for checking. Default false. 854 * @param string|false $id_base Optional. The base ID of a widget created by extending WP_Widget. Default false. 855 * @param bool $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true. 856 * @return string|false False if widget is not active or id of sidebar in which the widget is active. 857 */ 858 function is_active_widget( $callback = false, $widget_id = false, $id_base = false, $skip_inactive = true ) { 859 global $wp_registered_widgets; 860 861 $sidebars_widgets = wp_get_sidebars_widgets(); 862 863 if ( is_array( $sidebars_widgets ) ) { 864 foreach ( $sidebars_widgets as $sidebar => $widgets ) { 865 if ( $skip_inactive && ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) ) { 866 continue; 867 } 868 869 if ( is_array( $widgets ) ) { 870 foreach ( $widgets as $widget ) { 871 if ( ( $callback && isset( $wp_registered_widgets[ $widget ]['callback'] ) && $wp_registered_widgets[ $widget ]['callback'] == $callback ) || ( $id_base && _get_widget_id_base( $widget ) == $id_base ) ) { 872 if ( ! $widget_id || $widget_id == $wp_registered_widgets[ $widget ]['id'] ) { 873 return $sidebar; 874 } 875 } 876 } 877 } 878 } 879 } 880 return false; 881 } 882 883 /** 884 * Determines whether the dynamic sidebar is enabled and used by the theme. 885 * 886 * For more information on this and similar theme functions, check out 887 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 888 * Conditional Tags} article in the Theme Developer Handbook. 889 * 890 * @since 2.2.0 891 * 892 * @global array $wp_registered_widgets 893 * @global array $wp_registered_sidebars Registered sidebars. 894 * 895 * @return bool True, if using widgets. False, if not using widgets. 896 */ 897 function is_dynamic_sidebar() { 898 global $wp_registered_widgets, $wp_registered_sidebars; 899 $sidebars_widgets = get_option( 'sidebars_widgets' ); 900 foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) { 901 if ( ! empty( $sidebars_widgets[ $index ] ) ) { 902 foreach ( (array) $sidebars_widgets[ $index ] as $widget ) { 903 if ( array_key_exists( $widget, $wp_registered_widgets ) ) { 904 return true; 905 } 906 } 907 } 908 } 909 return false; 910 } 911 912 /** 913 * Determines whether a sidebar is in use. 914 * 915 * For more information on this and similar theme functions, check out 916 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 917 * Conditional Tags} article in the Theme Developer Handbook. 918 * 919 * @since 2.8.0 920 * 921 * @param string|int $index Sidebar name, id or number to check. 922 * @return bool true if the sidebar is in use, false otherwise. 923 */ 924 function is_active_sidebar( $index ) { 925 $index = ( is_int( $index ) ) ? "sidebar-$index" : sanitize_title( $index ); 926 $sidebars_widgets = wp_get_sidebars_widgets(); 927 $is_active_sidebar = ! empty( $sidebars_widgets[ $index ] ); 928 929 /** 930 * Filters whether a dynamic sidebar is considered "active". 931 * 932 * @since 3.9.0 933 * 934 * @param bool $is_active_sidebar Whether or not the sidebar should be considered "active". 935 * In other words, whether the sidebar contains any widgets. 936 * @param int|string $index Index, name, or ID of the dynamic sidebar. 937 */ 938 return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index ); 939 } 940 941 // 942 // Internal Functions 943 // 944 945 /** 946 * Retrieve full list of sidebars and their widget instance IDs. 947 * 948 * Will upgrade sidebar widget list, if needed. Will also save updated list, if 949 * needed. 950 * 951 * @since 2.2.0 952 * @access private 953 * 954 * @global array $_wp_sidebars_widgets 955 * @global array $sidebars_widgets 956 * 957 * @param bool $deprecated Not used (argument deprecated). 958 * @return array Upgraded list of widgets to version 3 array format when called from the admin. 959 */ 960 function wp_get_sidebars_widgets( $deprecated = true ) { 961 if ( $deprecated !== true ) { 962 _deprecated_argument( __FUNCTION__, '2.8.1' ); 963 } 964 965 global $_wp_sidebars_widgets, $sidebars_widgets; 966 967 // If loading from front page, consult $_wp_sidebars_widgets rather than options 968 // to see if wp_convert_widget_settings() has made manipulations in memory. 969 if ( ! is_admin() ) { 970 if ( empty( $_wp_sidebars_widgets ) ) { 971 $_wp_sidebars_widgets = get_option( 'sidebars_widgets', array() ); 972 } 973 974 $sidebars_widgets = $_wp_sidebars_widgets; 975 } else { 976 $sidebars_widgets = get_option( 'sidebars_widgets', array() ); 977 } 978 979 if ( is_array( $sidebars_widgets ) && isset( $sidebars_widgets['array_version'] ) ) { 980 unset( $sidebars_widgets['array_version'] ); 981 } 982 983 /** 984 * Filters the list of sidebars and their widgets. 985 * 986 * @since 2.7.0 987 * 988 * @param array $sidebars_widgets An associative array of sidebars and their widgets. 989 */ 990 return apply_filters( 'sidebars_widgets', $sidebars_widgets ); 991 } 992 993 /** 994 * Set the sidebar widget option to update sidebars. 995 * 996 * @since 2.2.0 997 * @access private 998 * 999 * @global array $_wp_sidebars_widgets 1000 * @param array $sidebars_widgets Sidebar widgets and their settings. 1001 */ 1002 function wp_set_sidebars_widgets( $sidebars_widgets ) { 1003 global $_wp_sidebars_widgets; 1004 1005 // Clear cached value used in wp_get_sidebars_widgets(). 1006 $_wp_sidebars_widgets = null; 1007 1008 if ( ! isset( $sidebars_widgets['array_version'] ) ) { 1009 $sidebars_widgets['array_version'] = 3; 1010 } 1011 1012 update_option( 'sidebars_widgets', $sidebars_widgets ); 1013 } 1014 1015 /** 1016 * Retrieve default registered sidebars list. 1017 * 1018 * @since 2.2.0 1019 * @access private 1020 * 1021 * @global array $wp_registered_sidebars Registered sidebars. 1022 * 1023 * @return array 1024 */ 1025 function wp_get_widget_defaults() { 1026 global $wp_registered_sidebars; 1027 1028 $defaults = array(); 1029 1030 foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) { 1031 $defaults[ $index ] = array(); 1032 } 1033 1034 return $defaults; 1035 } 1036 1037 /** 1038 * Convert the widget settings from single to multi-widget format. 1039 * 1040 * @since 2.8.0 1041 * 1042 * @global array $_wp_sidebars_widgets 1043 * 1044 * @param string $base_name 1045 * @param string $option_name 1046 * @param array $settings 1047 * @return array 1048 */ 1049 function wp_convert_widget_settings( $base_name, $option_name, $settings ) { 1050 // This test may need expanding. 1051 $single = false; 1052 $changed = false; 1053 if ( empty( $settings ) ) { 1054 $single = true; 1055 } else { 1056 foreach ( array_keys( $settings ) as $number ) { 1057 if ( 'number' == $number ) { 1058 continue; 1059 } 1060 if ( ! is_numeric( $number ) ) { 1061 $single = true; 1062 break; 1063 } 1064 } 1065 } 1066 1067 if ( $single ) { 1068 $settings = array( 2 => $settings ); 1069 1070 // If loading from the front page, update sidebar in memory but don't save to options 1071 if ( is_admin() ) { 1072 $sidebars_widgets = get_option( 'sidebars_widgets' ); 1073 } else { 1074 if ( empty( $GLOBALS['_wp_sidebars_widgets'] ) ) { 1075 $GLOBALS['_wp_sidebars_widgets'] = get_option( 'sidebars_widgets', array() ); 1076 } 1077 $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets']; 1078 } 1079 1080 foreach ( (array) $sidebars_widgets as $index => $sidebar ) { 1081 if ( is_array( $sidebar ) ) { 1082 foreach ( $sidebar as $i => $name ) { 1083 if ( $base_name == $name ) { 1084 $sidebars_widgets[ $index ][ $i ] = "$name-2"; 1085 $changed = true; 1086 break 2; 1087 } 1088 } 1089 } 1090 } 1091 1092 if ( is_admin() && $changed ) { 1093 update_option( 'sidebars_widgets', $sidebars_widgets ); 1094 } 1095 } 1096 1097 $settings['_multiwidget'] = 1; 1098 if ( is_admin() ) { 1099 update_option( $option_name, $settings ); 1100 } 1101 1102 return $settings; 1103 } 1104 1105 /** 1106 * Output an arbitrary widget as a template tag. 1107 * 1108 * @since 2.8.0 1109 * 1110 * @global WP_Widget_Factory $wp_widget_factory 1111 * 1112 * @param string $widget The widget's PHP class name (see class-wp-widget.php). 1113 * @param array $instance Optional. The widget's instance settings. Default empty array. 1114 * @param array $args { 1115 * Optional. Array of arguments to configure the display of the widget. 1116 * 1117 * @type string $before_widget HTML content that will be prepended to the widget's HTML output. 1118 * Default `<div class="widget %s">`, where `%s` is the widget's class name. 1119 * @type string $after_widget HTML content that will be appended to the widget's HTML output. 1120 * Default `</div>`. 1121 * @type string $before_title HTML content that will be prepended to the widget's title when displayed. 1122 * Default `<h2 class="widgettitle">`. 1123 * @type string $after_title HTML content that will be appended to the widget's title when displayed. 1124 * Default `</h2>`. 1125 * } 1126 */ 1127 function the_widget( $widget, $instance = array(), $args = array() ) { 1128 global $wp_widget_factory; 1129 1130 if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) { 1131 _doing_it_wrong( 1132 __FUNCTION__, 1133 sprintf( 1134 /* translators: %s: register_widget() */ 1135 __( 'Widgets need to be registered using %s, before they can be displayed.' ), 1136 '<code>register_widget()</code>' 1137 ), 1138 '4.9.0' 1139 ); 1140 return; 1141 } 1142 1143 $widget_obj = $wp_widget_factory->widgets[ $widget ]; 1144 if ( ! ( $widget_obj instanceof WP_Widget ) ) { 1145 return; 1146 } 1147 1148 $default_args = array( 1149 'before_widget' => '<div class="widget %s">', 1150 'after_widget' => '</div>', 1151 'before_title' => '<h2 class="widgettitle">', 1152 'after_title' => '</h2>', 1153 ); 1154 $args = wp_parse_args( $args, $default_args ); 1155 $args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] ); 1156 1157 $instance = wp_parse_args( $instance ); 1158 1159 /** This filter is documented in wp-includes/class-wp-widget.php */ 1160 $instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args ); 1161 1162 if ( false === $instance ) { 1163 return; 1164 } 1165 1166 /** 1167 * Fires before rendering the requested widget. 1168 * 1169 * @since 3.0.0 1170 * 1171 * @param string $widget The widget's class name. 1172 * @param array $instance The current widget instance's settings. 1173 * @param array $args An array of the widget's sidebar arguments. 1174 */ 1175 do_action( 'the_widget', $widget, $instance, $args ); 1176 1177 $widget_obj->_set( -1 ); 1178 $widget_obj->widget( $args, $instance ); 1179 } 1180 1181 /** 1182 * Retrieves the widget ID base value. 1183 * 1184 * @since 2.8.0 1185 * 1186 * @param string $id Widget ID. 1187 * @return string Widget ID base. 1188 */ 1189 function _get_widget_id_base( $id ) { 1190 return preg_replace( '/-[0-9]+$/', '', $id ); 1191 } 1192 1193 /** 1194 * Handle sidebars config after theme change 1195 * 1196 * @access private 1197 * @since 3.3.0 1198 * 1199 * @global array $sidebars_widgets 1200 */ 1201 function _wp_sidebars_changed() { 1202 global $sidebars_widgets; 1203 1204 if ( ! is_array( $sidebars_widgets ) ) { 1205 $sidebars_widgets = wp_get_sidebars_widgets(); 1206 } 1207 1208 retrieve_widgets( true ); 1209 } 1210 1211 /** 1212 * Look for "lost" widgets, this has to run at least on each theme change. 1213 * 1214 * @since 2.8.0 1215 * 1216 * @global array $wp_registered_sidebars Registered sidebars. 1217 * @global array $sidebars_widgets 1218 * @global array $wp_registered_widgets 1219 * 1220 * @param string|bool $theme_changed Whether the theme was changed as a boolean. A value 1221 * of 'customize' defers updates for the Customizer. 1222 * @return array Updated sidebars widgets. 1223 */ 1224 function retrieve_widgets( $theme_changed = false ) { 1225 global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets; 1226 1227 $registered_sidebars_keys = array_keys( $wp_registered_sidebars ); 1228 $registered_widgets_ids = array_keys( $wp_registered_widgets ); 1229 1230 if ( ! is_array( get_theme_mod( 'sidebars_widgets' ) ) ) { 1231 if ( empty( $sidebars_widgets ) ) { 1232 return array(); 1233 } 1234 1235 unset( $sidebars_widgets['array_version'] ); 1236 1237 $sidebars_widgets_keys = array_keys( $sidebars_widgets ); 1238 sort( $sidebars_widgets_keys ); 1239 sort( $registered_sidebars_keys ); 1240 1241 if ( $sidebars_widgets_keys === $registered_sidebars_keys ) { 1242 $sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids ); 1243 1244 return $sidebars_widgets; 1245 } 1246 } 1247 1248 // Discard invalid, theme-specific widgets from sidebars. 1249 $sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids ); 1250 $sidebars_widgets = wp_map_sidebars_widgets( $sidebars_widgets ); 1251 1252 // Find hidden/lost multi-widget instances. 1253 $shown_widgets = call_user_func_array( 'array_merge', $sidebars_widgets ); 1254 $lost_widgets = array_diff( $registered_widgets_ids, $shown_widgets ); 1255 1256 foreach ( $lost_widgets as $key => $widget_id ) { 1257 $number = preg_replace( '/.+?-([0-9]+)$/', '$1', $widget_id ); 1258 1259 // Only keep active and default widgets. 1260 if ( is_numeric( $number ) && (int) $number < 2 ) { 1261 unset( $lost_widgets[ $key ] ); 1262 } 1263 } 1264 $sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets'] ); 1265 1266 if ( 'customize' !== $theme_changed ) { 1267 wp_set_sidebars_widgets( $sidebars_widgets ); 1268 } 1269 1270 return $sidebars_widgets; 1271 } 1272 1273 /** 1274 * Compares a list of sidebars with their widgets against a whitelist. 1275 * 1276 * @since 4.9.0 1277 * @since 4.9.2 Always tries to restore widget assignments from previous data, not just if sidebars needed mapping. 1278 * 1279 * @param array $existing_sidebars_widgets List of sidebars and their widget instance IDs. 1280 * @return array Mapped sidebars widgets. 1281 */ 1282 function wp_map_sidebars_widgets( $existing_sidebars_widgets ) { 1283 global $wp_registered_sidebars; 1284 1285 $new_sidebars_widgets = array( 1286 'wp_inactive_widgets' => array(), 1287 ); 1288 1289 // Short-circuit if there are no sidebars to map. 1290 if ( ! is_array( $existing_sidebars_widgets ) || empty( $existing_sidebars_widgets ) ) { 1291 return $new_sidebars_widgets; 1292 } 1293 1294 foreach ( $existing_sidebars_widgets as $sidebar => $widgets ) { 1295 if ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { 1296 $new_sidebars_widgets['wp_inactive_widgets'] = array_merge( $new_sidebars_widgets['wp_inactive_widgets'], (array) $widgets ); 1297 unset( $existing_sidebars_widgets[ $sidebar ] ); 1298 } 1299 } 1300 1301 // If old and new theme have just one sidebar, map it and we're done. 1302 if ( 1 === count( $existing_sidebars_widgets ) && 1 === count( $wp_registered_sidebars ) ) { 1303 $new_sidebars_widgets[ key( $wp_registered_sidebars ) ] = array_pop( $existing_sidebars_widgets ); 1304 1305 return $new_sidebars_widgets; 1306 } 1307 1308 // Map locations with the same slug. 1309 $existing_sidebars = array_keys( $existing_sidebars_widgets ); 1310 1311 foreach ( $wp_registered_sidebars as $sidebar => $name ) { 1312 if ( in_array( $sidebar, $existing_sidebars, true ) ) { 1313 $new_sidebars_widgets[ $sidebar ] = $existing_sidebars_widgets[ $sidebar ]; 1314 unset( $existing_sidebars_widgets[ $sidebar ] ); 1315 } elseif ( ! array_key_exists( $sidebar, $new_sidebars_widgets ) ) { 1316 $new_sidebars_widgets[ $sidebar ] = array(); 1317 } 1318 } 1319 1320 // If there are more sidebars, try to map them. 1321 if ( ! empty( $existing_sidebars_widgets ) ) { 1322 1323 /* 1324 * If old and new theme both have sidebars that contain phrases 1325 * from within the same group, make an educated guess and map it. 1326 */ 1327 $common_slug_groups = array( 1328 array( 'sidebar', 'primary', 'main', 'right' ), 1329 array( 'second', 'left' ), 1330 array( 'sidebar-2', 'footer', 'bottom' ), 1331 array( 'header', 'top' ), 1332 ); 1333 1334 // Go through each group... 1335 foreach ( $common_slug_groups as $slug_group ) { 1336 1337 // ...and see if any of these slugs... 1338 foreach ( $slug_group as $slug ) { 1339 1340 // ...and any of the new sidebars... 1341 foreach ( $wp_registered_sidebars as $new_sidebar => $args ) { 1342 1343 // ...actually match! 1344 if ( false === stripos( $new_sidebar, $slug ) && false === stripos( $slug, $new_sidebar ) ) { 1345 continue; 1346 } 1347 1348 // Then see if any of the existing sidebars... 1349 foreach ( $existing_sidebars_widgets as $sidebar => $widgets ) { 1350 1351 // ...and any slug in the same group... 1352 foreach ( $slug_group as $slug ) { 1353 1354 // ... have a match as well. 1355 if ( false === stripos( $sidebar, $slug ) && false === stripos( $slug, $sidebar ) ) { 1356 continue; 1357 } 1358 1359 // Make sure this sidebar wasn't mapped and removed previously. 1360 if ( ! empty( $existing_sidebars_widgets[ $sidebar ] ) ) { 1361 1362 // We have a match that can be mapped! 1363 $new_sidebars_widgets[ $new_sidebar ] = array_merge( $new_sidebars_widgets[ $new_sidebar ], $existing_sidebars_widgets[ $sidebar ] ); 1364 1365 // Remove the mapped sidebar so it can't be mapped again. 1366 unset( $existing_sidebars_widgets[ $sidebar ] ); 1367 1368 // Go back and check the next new sidebar. 1369 continue 3; 1370 } 1371 } // endforeach ( $slug_group as $slug ) 1372 } // endforeach ( $existing_sidebars_widgets as $sidebar => $widgets ) 1373 } // endforeach foreach ( $wp_registered_sidebars as $new_sidebar => $args ) 1374 } // endforeach ( $slug_group as $slug ) 1375 } // endforeach ( $common_slug_groups as $slug_group ) 1376 } 1377 1378 // Move any left over widgets to inactive sidebar. 1379 foreach ( $existing_sidebars_widgets as $widgets ) { 1380 if ( is_array( $widgets ) && ! empty( $widgets ) ) { 1381 $new_sidebars_widgets['wp_inactive_widgets'] = array_merge( $new_sidebars_widgets['wp_inactive_widgets'], $widgets ); 1382 } 1383 } 1384 1385 // Sidebars_widgets settings from when this theme was previously active. 1386 $old_sidebars_widgets = get_theme_mod( 'sidebars_widgets' ); 1387 $old_sidebars_widgets = isset( $old_sidebars_widgets['data'] ) ? $old_sidebars_widgets['data'] : false; 1388 1389 if ( is_array( $old_sidebars_widgets ) ) { 1390 1391 // Remove empty sidebars, no need to map those. 1392 $old_sidebars_widgets = array_filter( $old_sidebars_widgets ); 1393 1394 // Only check sidebars that are empty or have not been mapped to yet. 1395 foreach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ) { 1396 if ( array_key_exists( $new_sidebar, $old_sidebars_widgets ) && ! empty( $new_widgets ) ) { 1397 unset( $old_sidebars_widgets[ $new_sidebar ] ); 1398 } 1399 } 1400 1401 // Remove orphaned widgets, we're only interested in previously active sidebars. 1402 foreach ( $old_sidebars_widgets as $sidebar => $widgets ) { 1403 if ( 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) { 1404 unset( $old_sidebars_widgets[ $sidebar ] ); 1405 } 1406 } 1407 1408 $old_sidebars_widgets = _wp_remove_unregistered_widgets( $old_sidebars_widgets ); 1409 1410 if ( ! empty( $old_sidebars_widgets ) ) { 1411 1412 // Go through each remaining sidebar... 1413 foreach ( $old_sidebars_widgets as $old_sidebar => $old_widgets ) { 1414 1415 // ...and check every new sidebar... 1416 foreach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ) { 1417 1418 // ...for every widget we're trying to revive. 1419 foreach ( $old_widgets as $key => $widget_id ) { 1420 $active_key = array_search( $widget_id, $new_widgets, true ); 1421 1422 // If the widget is used elsewhere... 1423 if ( false !== $active_key ) { 1424 1425 // ...and that elsewhere is inactive widgets... 1426 if ( 'wp_inactive_widgets' === $new_sidebar ) { 1427 1428 // ...remove it from there and keep the active version... 1429 unset( $new_sidebars_widgets['wp_inactive_widgets'][ $active_key ] ); 1430 } else { 1431 1432 // ...otherwise remove it from the old sidebar and keep it in the new one. 1433 unset( $old_sidebars_widgets[ $old_sidebar ][ $key ] ); 1434 } 1435 } // endif ( $active_key ) 1436 } // endforeach ( $old_widgets as $key => $widget_id ) 1437 } // endforeach ( $new_sidebars_widgets as $new_sidebar => $new_widgets ) 1438 } // endforeach ( $old_sidebars_widgets as $old_sidebar => $old_widgets ) 1439 } // endif ( ! empty( $old_sidebars_widgets ) ) 1440 1441 // Restore widget settings from when theme was previously active. 1442 $new_sidebars_widgets = array_merge( $new_sidebars_widgets, $old_sidebars_widgets ); 1443 } 1444 1445 return $new_sidebars_widgets; 1446 } 1447 1448 /** 1449 * Compares a list of sidebars with their widgets against a whitelist. 1450 * 1451 * @since 4.9.0 1452 * 1453 * @param array $sidebars_widgets List of sidebars and their widget instance IDs. 1454 * @param array $whitelist Optional. List of widget IDs to compare against. Default: Registered widgets. 1455 * @return array Sidebars with whitelisted widgets. 1456 */ 1457 function _wp_remove_unregistered_widgets( $sidebars_widgets, $whitelist = array() ) { 1458 if ( empty( $whitelist ) ) { 1459 $whitelist = array_keys( $GLOBALS['wp_registered_widgets'] ); 1460 } 1461 1462 foreach ( $sidebars_widgets as $sidebar => $widgets ) { 1463 if ( is_array( $widgets ) ) { 1464 $sidebars_widgets[ $sidebar ] = array_intersect( $widgets, $whitelist ); 1465 } 1466 } 1467 1468 return $sidebars_widgets; 1469 } 1470 1471 /** 1472 * Display the RSS entries in a list. 1473 * 1474 * @since 2.5.0 1475 * 1476 * @param string|array|object $rss RSS url. 1477 * @param array $args Widget arguments. 1478 */ 1479 function wp_widget_rss_output( $rss, $args = array() ) { 1480 if ( is_string( $rss ) ) { 1481 $rss = fetch_feed( $rss ); 1482 } elseif ( is_array( $rss ) && isset( $rss['url'] ) ) { 1483 $args = $rss; 1484 $rss = fetch_feed( $rss['url'] ); 1485 } elseif ( ! is_object( $rss ) ) { 1486 return; 1487 } 1488 1489 if ( is_wp_error( $rss ) ) { 1490 if ( is_admin() || current_user_can( 'manage_options' ) ) { 1491 echo '<p><strong>' . __( 'RSS Error:' ) . '</strong> ' . $rss->get_error_message() . '</p>'; 1492 } 1493 return; 1494 } 1495 1496 $default_args = array( 1497 'show_author' => 0, 1498 'show_date' => 0, 1499 'show_summary' => 0, 1500 'items' => 0, 1501 ); 1502 $args = wp_parse_args( $args, $default_args ); 1503 1504 $items = (int) $args['items']; 1505 if ( $items < 1 || 20 < $items ) { 1506 $items = 10; 1507 } 1508 $show_summary = (int) $args['show_summary']; 1509 $show_author = (int) $args['show_author']; 1510 $show_date = (int) $args['show_date']; 1511 1512 if ( ! $rss->get_item_quantity() ) { 1513 echo '<ul><li>' . __( 'An error has occurred, which probably means the feed is down. Try again later.' ) . '</li></ul>'; 1514 $rss->__destruct(); 1515 unset( $rss ); 1516 return; 1517 } 1518 1519 echo '<ul>'; 1520 foreach ( $rss->get_items( 0, $items ) as $item ) { 1521 $link = $item->get_link(); 1522 while ( stristr( $link, 'http' ) != $link ) { 1523 $link = substr( $link, 1 ); 1524 } 1525 $link = esc_url( strip_tags( $link ) ); 1526 1527 $title = esc_html( trim( strip_tags( $item->get_title() ) ) ); 1528 if ( empty( $title ) ) { 1529 $title = __( 'Untitled' ); 1530 } 1531 1532 $desc = html_entity_decode( $item->get_description(), ENT_QUOTES, get_option( 'blog_charset' ) ); 1533 $desc = esc_attr( wp_trim_words( $desc, 55, ' […]' ) ); 1534 1535 $summary = ''; 1536 if ( $show_summary ) { 1537 $summary = $desc; 1538 1539 // Change existing [...] to […]. 1540 if ( '[...]' == substr( $summary, -5 ) ) { 1541 $summary = substr( $summary, 0, -5 ) . '[…]'; 1542 } 1543 1544 $summary = '<div class="rssSummary">' . esc_html( $summary ) . '</div>'; 1545 } 1546 1547 $date = ''; 1548 if ( $show_date ) { 1549 $date = $item->get_date( 'U' ); 1550 1551 if ( $date ) { 1552 $date = ' <span class="rss-date">' . date_i18n( get_option( 'date_format' ), $date ) . '</span>'; 1553 } 1554 } 1555 1556 $author = ''; 1557 if ( $show_author ) { 1558 $author = $item->get_author(); 1559 if ( is_object( $author ) ) { 1560 $author = $author->get_name(); 1561 $author = ' <cite>' . esc_html( strip_tags( $author ) ) . '</cite>'; 1562 } 1563 } 1564 1565 if ( $link == '' ) { 1566 echo "<li>$title{$date}{$summary}{$author}</li>"; 1567 } elseif ( $show_summary ) { 1568 echo "<li><a class='rsswidget' href='$link'>$title</a>{$date}{$summary}{$author}</li>"; 1569 } else { 1570 echo "<li><a class='rsswidget' href='$link'>$title</a>{$date}{$author}</li>"; 1571 } 1572 } 1573 echo '</ul>'; 1574 $rss->__destruct(); 1575 unset( $rss ); 1576 } 1577 1578 /** 1579 * Display RSS widget options form. 1580 * 1581 * The options for what fields are displayed for the RSS form are all booleans 1582 * and are as follows: 'url', 'title', 'items', 'show_summary', 'show_author', 1583 * 'show_date'. 1584 * 1585 * @since 2.5.0 1586 * 1587 * @param array|string $args Values for input fields. 1588 * @param array $inputs Override default display options. 1589 */ 1590 function wp_widget_rss_form( $args, $inputs = null ) { 1591 $default_inputs = array( 1592 'url' => true, 1593 'title' => true, 1594 'items' => true, 1595 'show_summary' => true, 1596 'show_author' => true, 1597 'show_date' => true, 1598 ); 1599 $inputs = wp_parse_args( $inputs, $default_inputs ); 1600 1601 $args['title'] = isset( $args['title'] ) ? $args['title'] : ''; 1602 $args['url'] = isset( $args['url'] ) ? $args['url'] : ''; 1603 $args['items'] = isset( $args['items'] ) ? (int) $args['items'] : 0; 1604 1605 if ( $args['items'] < 1 || 20 < $args['items'] ) { 1606 $args['items'] = 10; 1607 } 1608 1609 $args['show_summary'] = isset( $args['show_summary'] ) ? (int) $args['show_summary'] : (int) $inputs['show_summary']; 1610 $args['show_author'] = isset( $args['show_author'] ) ? (int) $args['show_author'] : (int) $inputs['show_author']; 1611 $args['show_date'] = isset( $args['show_date'] ) ? (int) $args['show_date'] : (int) $inputs['show_date']; 1612 1613 if ( ! empty( $args['error'] ) ) { 1614 echo '<p class="widget-error"><strong>' . __( 'RSS Error:' ) . '</strong> ' . $args['error'] . '</p>'; 1615 } 1616 1617 $esc_number = esc_attr( $args['number'] ); 1618 if ( $inputs['url'] ) : 1619 ?> 1620 <p><label for="rss-url-<?php echo $esc_number; ?>"><?php _e( 'Enter the RSS feed URL here:' ); ?></label> 1621 <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> 1622 <?php endif; if ( $inputs['title'] ) : ?> 1623 <p><label for="rss-title-<?php echo $esc_number; ?>"><?php _e( 'Give the feed a title (optional):' ); ?></label> 1624 <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> 1625 <?php endif; if ( $inputs['items'] ) : ?> 1626 <p><label for="rss-items-<?php echo $esc_number; ?>"><?php _e( 'How many items would you like to display?' ); ?></label> 1627 <select id="rss-items-<?php echo $esc_number; ?>" name="widget-rss[<?php echo $esc_number; ?>][items]"> 1628 <?php 1629 for ( $i = 1; $i <= 20; ++$i ) { 1630 echo "<option value='$i' " . selected( $args['items'], $i, false ) . ">$i</option>"; 1631 } 1632 ?> 1633 </select></p> 1634 <?php endif; if ( $inputs['show_summary'] ) : ?> 1635 <p><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'] ); ?> /> 1636 <label for="rss-show-summary-<?php echo $esc_number; ?>"><?php _e( 'Display item content?' ); ?></label></p> 1637 <?php endif; if ( $inputs['show_author'] ) : ?> 1638 <p><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'] ); ?> /> 1639 <label for="rss-show-author-<?php echo $esc_number; ?>"><?php _e( 'Display item author if available?' ); ?></label></p> 1640 <?php endif; if ( $inputs['show_date'] ) : ?> 1641 <p><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'] ); ?>/> 1642 <label for="rss-show-date-<?php echo $esc_number; ?>"><?php _e( 'Display item date?' ); ?></label></p> 1643 <?php 1644 endif; 1645 foreach ( array_keys( $default_inputs ) as $input ) : 1646 if ( 'hidden' === $inputs[ $input ] ) : 1647 $id = str_replace( '_', '-', $input ); 1648 ?> 1649 <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 ] ); ?>" /> 1650 <?php 1651 endif; 1652 endforeach; 1653 } 1654 1655 /** 1656 * Process RSS feed widget data and optionally retrieve feed items. 1657 * 1658 * The feed widget can not have more than 20 items or it will reset back to the 1659 * default, which is 10. 1660 * 1661 * The resulting array has the feed title, feed url, feed link (from channel), 1662 * feed items, error (if any), and whether to show summary, author, and date. 1663 * All respectively in the order of the array elements. 1664 * 1665 * @since 2.5.0 1666 * 1667 * @param array $widget_rss RSS widget feed data. Expects unescaped data. 1668 * @param bool $check_feed Optional, default is true. Whether to check feed for errors. 1669 * @return array 1670 */ 1671 function wp_widget_rss_process( $widget_rss, $check_feed = true ) { 1672 $items = (int) $widget_rss['items']; 1673 if ( $items < 1 || 20 < $items ) { 1674 $items = 10; 1675 } 1676 $url = esc_url_raw( strip_tags( $widget_rss['url'] ) ); 1677 $title = isset( $widget_rss['title'] ) ? trim( strip_tags( $widget_rss['title'] ) ) : ''; 1678 $show_summary = isset( $widget_rss['show_summary'] ) ? (int) $widget_rss['show_summary'] : 0; 1679 $show_author = isset( $widget_rss['show_author'] ) ? (int) $widget_rss['show_author'] : 0; 1680 $show_date = isset( $widget_rss['show_date'] ) ? (int) $widget_rss['show_date'] : 0; 1681 1682 if ( $check_feed ) { 1683 $rss = fetch_feed( $url ); 1684 $error = false; 1685 $link = ''; 1686 if ( is_wp_error( $rss ) ) { 1687 $error = $rss->get_error_message(); 1688 } else { 1689 $link = esc_url( strip_tags( $rss->get_permalink() ) ); 1690 while ( stristr( $link, 'http' ) != $link ) { 1691 $link = substr( $link, 1 ); 1692 } 1693 1694 $rss->__destruct(); 1695 unset( $rss ); 1696 } 1697 } 1698 1699 return compact( 'title', 'url', 'link', 'items', 'error', 'show_summary', 'show_author', 'show_date' ); 1700 } 1701 1702 /** 1703 * Registers all of the default WordPress widgets on startup. 1704 * 1705 * Calls {@see 'widgets_init'} action after all of the WordPress widgets have been registered. 1706 * 1707 * @since 2.2.0 1708 */ 1709 function wp_widgets_init() { 1710 if ( ! is_blog_installed() ) { 1711 return; 1712 } 1713 1714 register_widget( 'WP_Widget_Pages' ); 1715 1716 register_widget( 'WP_Widget_Calendar' ); 1717 1718 register_widget( 'WP_Widget_Archives' ); 1719 1720 if ( get_option( 'link_manager_enabled' ) ) { 1721 register_widget( 'WP_Widget_Links' ); 1722 } 1723 1724 register_widget( 'WP_Widget_Media_Audio' ); 1725 1726 register_widget( 'WP_Widget_Media_Image' ); 1727 1728 register_widget( 'WP_Widget_Media_Gallery' ); 1729 1730 register_widget( 'WP_Widget_Media_Video' ); 1731 1732 register_widget( 'WP_Widget_Meta' ); 1733 1734 register_widget( 'WP_Widget_Search' ); 1735 1736 register_widget( 'WP_Widget_Text' ); 1737 1738 register_widget( 'WP_Widget_Categories' ); 1739 1740 register_widget( 'WP_Widget_Recent_Posts' ); 1741 1742 register_widget( 'WP_Widget_Recent_Comments' ); 1743 1744 register_widget( 'WP_Widget_RSS' ); 1745 1746 register_widget( 'WP_Widget_Tag_Cloud' ); 1747 1748 register_widget( 'WP_Nav_Menu_Widget' ); 1749 1750 register_widget( 'WP_Widget_Custom_HTML' ); 1751 1752 /** 1753 * Fires after all default WordPress widgets have been registered. 1754 * 1755 * @since 2.2.0 1756 */ 1757 do_action( 'widgets_init' ); 1758 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Sep 17 01:00:03 2019 | Cross-referenced by PHPXref 0.7.1 |