[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * API for creating dynamic sidebar without hardcoding functionality into
   4   * themes. Includes both internal WordPress routines and theme use routines.
   5   *
   6   * This functionality was found in a plugin before WordPress 2.2 release which
   7   * included it in the core from that point on.
   8   *
   9   * @link http://codex.wordpress.org/Plugins/WordPress_Widgets WordPress Widgets
  10   * @link http://codex.wordpress.org/Plugins/WordPress_Widgets_Api Widgets API
  11   *
  12   * @package WordPress
  13   * @subpackage Widgets
  14   */
  15  
  16  /**
  17   * This class must be extended for each widget and WP_Widget::widget(), WP_Widget::update()
  18   * and WP_Widget::form() need to be over-ridden.
  19   *
  20   * @package WordPress
  21   * @subpackage Widgets
  22   * @since 2.8
  23   */
  24  class WP_Widget {
  25  
  26      var $id_base;            // Root id for all widgets of this type.
  27      var $name;                // Name for this widget type.
  28      var $widget_options;    // Option array passed to wp_register_sidebar_widget()
  29      var $control_options;    // Option array passed to wp_register_widget_control()
  30  
  31      var $number = false;    // Unique ID number of the current instance.
  32      var $id = false;        // Unique ID string of the current instance (id_base-number)
  33      var $updated = false;    // Set true when we update the data after a POST submit - makes sure we don't do it twice.
  34  
  35      // Member functions that you must over-ride.
  36  
  37      /** Echo the widget content.
  38       *
  39       * Subclasses should over-ride this function to generate their widget code.
  40       *
  41       * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
  42       * @param array $instance The settings for the particular instance of the widget
  43       */
  44  	function widget($args, $instance) {
  45          die('function WP_Widget::widget() must be over-ridden in a sub-class.');
  46      }
  47  
  48      /** Update a particular instance.
  49       *
  50       * This function should check that $new_instance is set correctly.
  51       * The newly calculated value of $instance should be returned.
  52       * If "false" is returned, the instance won't be saved/updated.
  53       *
  54       * @param array $new_instance New settings for this instance as input by the user via form()
  55       * @param array $old_instance Old settings for this instance
  56       * @return array Settings to save or bool false to cancel saving
  57       */
  58  	function update($new_instance, $old_instance) {
  59          return $new_instance;
  60      }
  61  
  62      /** Echo the settings update form
  63       *
  64       * @param array $instance Current settings
  65       */
  66  	function form($instance) {
  67          echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>';
  68          return 'noform';
  69      }
  70  
  71      // Functions you'll need to call.
  72  
  73      /**
  74       * PHP4 constructor
  75       */
  76  	function WP_Widget( $id_base = false, $name, $widget_options = array(), $control_options = array() ) {
  77          WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );
  78      }
  79  
  80      /**
  81       * PHP5 constructor
  82       *
  83       * @param string $id_base Optional Base ID for the widget, lower case,
  84       * if left empty a portion of the widget's class name will be used. Has to be unique.
  85       * @param string $name Name for the widget displayed on the configuration page.
  86       * @param array $widget_options Optional Passed to wp_register_sidebar_widget()
  87       *     - description: shown on the configuration page
  88       *     - classname
  89       * @param array $control_options Optional Passed to wp_register_widget_control()
  90       *     - width: required if more than 250px
  91       *     - height: currently not used but may be needed in the future
  92       */
  93  	function __construct( $id_base = false, $name, $widget_options = array(), $control_options = array() ) {
  94          $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);
  95          $this->name = $name;
  96          $this->option_name = 'widget_' . $this->id_base;
  97          $this->widget_options = wp_parse_args( $widget_options, array('classname' => $this->option_name) );
  98          $this->control_options = wp_parse_args( $control_options, array('id_base' => $this->id_base) );
  99      }
 100  
 101      /**
 102       * Constructs name attributes for use in form() fields
 103       *
 104       * This function should be used in form() methods to create name attributes for fields to be saved by update()
 105       *
 106       * @param string $field_name Field name
 107       * @return string Name attribute for $field_name
 108       */
 109  	function get_field_name($field_name) {
 110          return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']';
 111      }
 112  
 113      /**
 114       * Constructs id attributes for use in form() fields
 115       *
 116       * This function should be used in form() methods to create id attributes for fields to be saved by update()
 117       *
 118       * @param string $field_name Field name
 119       * @return string ID attribute for $field_name
 120       */
 121  	function get_field_id($field_name) {
 122          return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
 123      }
 124  
 125      // Private Functions. Don't worry about these.
 126  
 127  	function _register() {
 128          $settings = $this->get_settings();
 129          $empty = true;
 130  
 131          if ( is_array($settings) ) {
 132              foreach ( array_keys($settings) as $number ) {
 133                  if ( is_numeric($number) ) {
 134                      $this->_set($number);
 135                      $this->_register_one($number);
 136                      $empty = false;
 137                  }
 138              }
 139          }
 140  
 141          if ( $empty ) {
 142              // If there are none, we register the widget's existance with a
 143              // generic template
 144              $this->_set(1);
 145              $this->_register_one();
 146          }
 147      }
 148  
 149  	function _set($number) {
 150          $this->number = $number;
 151          $this->id = $this->id_base . '-' . $number;
 152      }
 153  
 154  	function _get_display_callback() {
 155          return array(&$this, 'display_callback');
 156      }
 157  
 158  	function _get_update_callback() {
 159          return array(&$this, 'update_callback');
 160      }
 161  
 162  	function _get_form_callback() {
 163          return array(&$this, 'form_callback');
 164      }
 165  
 166      /** Generate the actual widget content.
 167       *    Just finds the instance and calls widget().
 168       *    Do NOT over-ride this function. */
 169  	function display_callback( $args, $widget_args = 1 ) {
 170          if ( is_numeric($widget_args) )
 171              $widget_args = array( 'number' => $widget_args );
 172  
 173          $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
 174          $this->_set( $widget_args['number'] );
 175          $instance = $this->get_settings();
 176  
 177          if ( array_key_exists( $this->number, $instance ) ) {
 178              $instance = $instance[$this->number];
 179              // filters the widget's settings, return false to stop displaying the widget
 180              $instance = apply_filters('widget_display_callback', $instance, $this, $args);
 181              if ( false !== $instance )
 182                  $this->widget($args, $instance);
 183          }
 184      }
 185  
 186      /** Deal with changed settings.
 187       *    Do NOT over-ride this function. */
 188  	function update_callback( $widget_args = 1 ) {
 189          global $wp_registered_widgets;
 190  
 191          if ( is_numeric($widget_args) )
 192              $widget_args = array( 'number' => $widget_args );
 193  
 194          $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
 195          $all_instances = $this->get_settings();
 196  
 197          // We need to update the data
 198          if ( $this->updated )
 199              return;
 200  
 201          $sidebars_widgets = wp_get_sidebars_widgets();
 202  
 203          if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) {
 204              // Delete the settings for this instance of the widget
 205              if ( isset($_POST['the-widget-id']) )
 206                  $del_id = $_POST['the-widget-id'];
 207              else
 208                  return;
 209  
 210              if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) {
 211                  $number = $wp_registered_widgets[$del_id]['params'][0]['number'];
 212  
 213                  if ( $this->id_base . '-' . $number == $del_id )
 214                      unset($all_instances[$number]);
 215              }
 216          } else {
 217              if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) {
 218                  $settings = $_POST['widget-' . $this->id_base];
 219              } elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) {
 220                  $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];
 221                  $settings = array( $num => array() );
 222              } else {
 223                  return;
 224              }
 225  
 226              foreach ( $settings as $number => $new_instance ) {
 227                  $new_instance = stripslashes_deep($new_instance);
 228                  $this->_set($number);
 229  
 230                  $old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array();
 231  
 232                  $instance = $this->update($new_instance, $old_instance);
 233  
 234                  // filters the widget's settings before saving, return false to cancel saving (keep the old settings if updating)
 235                  $instance = apply_filters('widget_update_callback', $instance, $new_instance, $old_instance, $this);
 236                  if ( false !== $instance )
 237                      $all_instances[$number] = $instance;
 238  
 239                  break; // run only once
 240              }
 241          }
 242  
 243          $this->save_settings($all_instances);
 244          $this->updated = true;
 245      }
 246  
 247      /** Generate the control form.
 248       *    Do NOT over-ride this function. */
 249  	function form_callback( $widget_args = 1 ) {
 250          if ( is_numeric($widget_args) )
 251              $widget_args = array( 'number' => $widget_args );
 252  
 253          $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
 254          $all_instances = $this->get_settings();
 255  
 256          if ( -1 == $widget_args['number'] ) {
 257              // We echo out a form where 'number' can be set later
 258              $this->_set('__i__');
 259              $instance = array();
 260          } else {
 261              $this->_set($widget_args['number']);
 262              $instance = $all_instances[ $widget_args['number'] ];
 263          }
 264  
 265          // filters the widget admin form before displaying, return false to stop displaying it
 266          $instance = apply_filters('widget_form_callback', $instance, $this);
 267  
 268          $return = null;
 269          if ( false !== $instance ) {
 270              $return = $this->form($instance);
 271              // add extra fields in the widget form - be sure to set $return to null if you add any
 272              // if the widget has no form the text echoed from the default form method can be hidden using css
 273              do_action_ref_array( 'in_widget_form', array(&$this, &$return, $instance) );
 274          }
 275          return $return;
 276      }
 277  
 278      /** Helper function: Registers a single instance. */
 279  	function _register_one($number = -1) {
 280          wp_register_sidebar_widget(    $this->id, $this->name,    $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
 281          _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
 282          _register_widget_form_callback(    $this->id, $this->name,    $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
 283      }
 284  
 285  	function save_settings($settings) {
 286          $settings['_multiwidget'] = 1;
 287          update_option( $this->option_name, $settings );
 288      }
 289  
 290  	function get_settings() {
 291          $settings = get_option($this->option_name);
 292  
 293          if ( false === $settings && isset($this->alt_option_name) )
 294              $settings = get_option($this->alt_option_name);
 295  
 296          if ( !is_array($settings) )
 297              $settings = array();
 298  
 299          if ( !array_key_exists('_multiwidget', $settings) ) {
 300              // old format, conver if single widget
 301              $settings = wp_convert_widget_settings($this->id_base, $this->option_name, $settings);
 302          }
 303  
 304          unset($settings['_multiwidget'], $settings['__i__']);
 305          return $settings;
 306      }
 307  }
 308  
 309  /**
 310   * Singleton that registers and instantiates WP_Widget classes.
 311   *
 312   * @package WordPress
 313   * @subpackage Widgets
 314   * @since 2.8
 315   */
 316  class WP_Widget_Factory {
 317      var $widgets = array();
 318  
 319  	function WP_Widget_Factory() {
 320          add_action( 'widgets_init', array( &$this, '_register_widgets' ), 100 );
 321      }
 322  
 323  	function register($widget_class) {
 324          $this->widgets[$widget_class] = & new $widget_class();
 325      }
 326  
 327  	function unregister($widget_class) {
 328          if ( isset($this->widgets[$widget_class]) )
 329              unset($this->widgets[$widget_class]);
 330      }
 331  
 332  	function _register_widgets() {
 333          global $wp_registered_widgets;
 334          $keys = array_keys($this->widgets);
 335          $registered = array_keys($wp_registered_widgets);
 336          $registered = array_map('_get_widget_id_base', $registered);
 337  
 338          foreach ( $keys as $key ) {
 339              // don't register new widget if old widget with the same id is already registered
 340              if ( in_array($this->widgets[$key]->id_base, $registered, true) ) {
 341                  unset($this->widgets[$key]);
 342                  continue;
 343              }
 344  
 345              $this->widgets[$key]->_register();
 346          }
 347      }
 348  }
 349  
 350  /* Global Variables */
 351  
 352  /** @ignore */
 353  global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates;
 354  
 355  /**
 356   * Stores the sidebars, since many themes can have more than one.
 357   *
 358   * @global array $wp_registered_sidebars
 359   * @since 2.2.0
 360   */
 361  $wp_registered_sidebars = array();
 362  
 363  /**
 364   * Stores the registered widgets.
 365   *
 366   * @global array $wp_registered_widgets
 367   * @since 2.2.0
 368   */
 369  $wp_registered_widgets = array();
 370  
 371  /**
 372   * Stores the registered widget control (options).
 373   *
 374   * @global array $wp_registered_widget_controls
 375   * @since 2.2.0
 376   */
 377  $wp_registered_widget_controls = array();
 378  $wp_registered_widget_updates = array();
 379  
 380  /**
 381   * Private
 382   */
 383  $_wp_sidebars_widgets = array();
 384  
 385  /**
 386   * Private
 387   */
 388   $_wp_deprecated_widgets_callbacks = array(
 389       'wp_widget_pages',
 390      'wp_widget_pages_control',
 391      'wp_widget_calendar',
 392      'wp_widget_calendar_control',
 393      'wp_widget_archives',
 394      'wp_widget_archives_control',
 395      'wp_widget_links',
 396      'wp_widget_meta',
 397      'wp_widget_meta_control',
 398      'wp_widget_search',
 399      'wp_widget_recent_entries',
 400      'wp_widget_recent_entries_control',
 401      'wp_widget_tag_cloud',
 402      'wp_widget_tag_cloud_control',
 403      'wp_widget_categories',
 404      'wp_widget_categories_control',
 405      'wp_widget_text',
 406      'wp_widget_text_control',
 407      'wp_widget_rss',
 408      'wp_widget_rss_control',
 409      'wp_widget_recent_comments',
 410      'wp_widget_recent_comments_control'
 411   );
 412  
 413  /* Template tags & API functions */
 414  
 415  /**
 416   * Register a widget
 417   *
 418   * Registers a WP_Widget widget
 419   *
 420   * @since 2.8.0
 421   *
 422   * @see WP_Widget
 423   * @see WP_Widget_Factory
 424   * @uses WP_Widget_Factory
 425   *
 426   * @param string $widget_class The name of a class that extends WP_Widget
 427   */
 428  function register_widget($widget_class) {
 429      global $wp_widget_factory;
 430  
 431      $wp_widget_factory->register($widget_class);
 432  }
 433  
 434  /**
 435   * Unregister a widget
 436   *
 437   * Unregisters a WP_Widget widget. Useful for unregistering default widgets.
 438   * Run within a function hooked to the widgets_init action.
 439   *
 440   * @since 2.8.0
 441   *
 442   * @see WP_Widget
 443   * @see WP_Widget_Factory
 444   * @uses WP_Widget_Factory
 445   *
 446   * @param string $widget_class The name of a class that extends WP_Widget
 447   */
 448  function unregister_widget($widget_class) {
 449      global $wp_widget_factory;
 450  
 451      $wp_widget_factory->unregister($widget_class);
 452  }
 453  
 454  /**
 455   * Creates multiple sidebars.
 456   *
 457   * If you wanted to quickly create multiple sidebars for a theme or internally.
 458   * This function will allow you to do so. If you don't pass the 'name' and/or
 459   * 'id' in $args, then they will be built for you.
 460   *
 461   * The default for the name is "Sidebar #", with '#' being replaced with the
 462   * number the sidebar is currently when greater than one. If first sidebar, the
 463   * name will be just "Sidebar". The default for id is "sidebar-" followed by the
 464   * number the sidebar creation is currently at. If the id is provided, and mutliple
 465   * sidebars are being defined, the id will have "-2" appended, and so on.
 466   *
 467   * @since 2.2.0
 468   *
 469   * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
 470   * @uses parse_str() Converts a string to an array to be used in the rest of the function.
 471   * @uses register_sidebar() Sends single sidebar information [name, id] to this
 472   *    function to handle building the sidebar.
 473   *
 474   * @param int $number Number of sidebars to create.
 475   * @param string|array $args Builds Sidebar based off of 'name' and 'id' values.
 476   */
 477  function register_sidebars($number = 1, $args = array()) {
 478      global $wp_registered_sidebars;
 479      $number = (int) $number;
 480  
 481      if ( is_string($args) )
 482          parse_str($args, $args);
 483  
 484      for ( $i = 1; $i <= $number; $i++ ) {
 485          $_args = $args;
 486  
 487          if ( $number > 1 )
 488              $_args['name'] = isset($args['name']) ? sprintf($args['name'], $i) : sprintf(__('Sidebar %d'), $i);
 489          else
 490              $_args['name'] = isset($args['name']) ? $args['name'] : __('Sidebar');
 491  
 492          // Custom specified ID's are suffixed if they exist already.
 493          // Automatically generated sidebar names need to be suffixed regardless starting at -0
 494          if ( isset($args['id']) ) {
 495              $_args['id'] = $args['id'];
 496              $n = 2; // Start at -2 for conflicting custom ID's
 497              while ( isset($wp_registered_sidebars[$_args['id']]) )
 498                  $_args['id'] = $args['id'] . '-' . $n++;
 499          } else {
 500              $n = count($wp_registered_sidebars);
 501              do {
 502                  $_args['id'] = 'sidebar-' . ++$n;
 503              } while ( isset($wp_registered_sidebars[$_args['id']]) );
 504          }
 505          register_sidebar($_args);
 506      }
 507  }
 508  
 509  /**
 510   * Builds the definition for a single sidebar and returns the ID.
 511   *
 512   * The $args parameter takes either a string or an array with 'name' and 'id'
 513   * contained in either usage. It will be noted that the values will be applied
 514   * to all sidebars, so if creating more than one, it will be advised to allow
 515   * for WordPress to create the defaults for you.
 516   *
 517   * Example for string would be <code>'name=whatever;id=whatever1'</code> and for
 518   * the array it would be <code>array(
 519   *    'name' => 'whatever',
 520   *    'id' => 'whatever1')</code>.
 521   *
 522   * name - The name of the sidebar, which presumably the title which will be
 523   *     displayed.
 524   * id - The unique identifier by which the sidebar will be called by.
 525   * before_widget - The content that will prepended to the widgets when they are
 526   *     displayed.
 527   * after_widget - The content that will be appended to the widgets when they are
 528   *     displayed.
 529   * before_title - The content that will be prepended to the title when displayed.
 530   * after_title - the content that will be appended to the title when displayed.
 531   *
 532   * <em>Content</em> is assumed to be HTML and should be formatted as such, but
 533   * doesn't have to be.
 534   *
 535   * @since 2.2.0
 536   * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
 537   *
 538   * @param string|array $args Builds Sidebar based off of 'name' and 'id' values
 539   * @return string The sidebar id that was added.
 540   */
 541  function register_sidebar($args = array()) {
 542      global $wp_registered_sidebars;
 543  
 544      $i = count($wp_registered_sidebars) + 1;
 545  
 546      $defaults = array(
 547          'name' => sprintf(__('Sidebar %d'), $i ),
 548          'id' => "sidebar-$i",
 549          'description' => '',
 550          'before_widget' => '<li id="%1$s" class="widget %2$s">',
 551          'after_widget' => "</li>\n",
 552          'before_title' => '<h2 class="widgettitle">',
 553          'after_title' => "</h2>\n",
 554      );
 555  
 556      $sidebar = wp_parse_args( $args, $defaults );
 557  
 558      $wp_registered_sidebars[$sidebar['id']] = $sidebar;
 559  
 560      add_theme_support('widgets');
 561  
 562      do_action( 'register_sidebar', $sidebar );
 563  
 564      return $sidebar['id'];
 565  }
 566  
 567  /**
 568   * Removes a sidebar from the list.
 569   *
 570   * @since 2.2.0
 571   *
 572   * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
 573   *
 574   * @param string $name The ID of the sidebar when it was added.
 575   */
 576  function unregister_sidebar( $name ) {
 577      global $wp_registered_sidebars;
 578  
 579      if ( isset( $wp_registered_sidebars[$name] ) )
 580          unset( $wp_registered_sidebars[$name] );
 581  }
 582  
 583  /**
 584   * Register widget for use in sidebars.
 585   *
 586   * The default widget option is 'classname' that can be override.
 587   *
 588   * The function can also be used to unregister widgets when $output_callback
 589   * parameter is an empty string.
 590   *
 591   * @since 2.2.0
 592   *
 593   * @uses $wp_registered_widgets Uses stored registered widgets.
 594   * @uses $wp_register_widget_defaults Retrieves widget defaults.
 595   *
 596   * @param int|string $id Widget ID.
 597   * @param string $name Widget display title.
 598   * @param callback $output_callback Run when widget is called.
 599   * @param array|string $options Optional. Widget Options.
 600   * @param mixed $params,... Widget parameters to add to widget.
 601   * @return null Will return if $output_callback is empty after removing widget.
 602   */
 603  function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
 604      global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;
 605  
 606      $id = strtolower($id);
 607  
 608      if ( empty($output_callback) ) {
 609          unset($wp_registered_widgets[$id]);
 610          return;
 611      }
 612  
 613      $id_base = _get_widget_id_base($id);
 614      if ( in_array($output_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($output_callback) ) {
 615          if ( isset($wp_registered_widget_controls[$id]) )
 616              unset($wp_registered_widget_controls[$id]);
 617  
 618          if ( isset($wp_registered_widget_updates[$id_base]) )
 619              unset($wp_registered_widget_updates[$id_base]);
 620  
 621          return;
 622      }
 623  
 624      $defaults = array('classname' => $output_callback);
 625      $options = wp_parse_args($options, $defaults);
 626      $widget = array(
 627          'name' => $name,
 628          'id' => $id,
 629          'callback' => $output_callback,
 630          'params' => array_slice(func_get_args(), 4)
 631      );
 632      $widget = array_merge($widget, $options);
 633  
 634      if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) {
 635          do_action( 'wp_register_sidebar_widget', $widget );
 636          $wp_registered_widgets[$id] = $widget;
 637      }
 638  }
 639  
 640  /**
 641   * Retrieve description for widget.
 642   *
 643   * When registering widgets, the options can also include 'description' that
 644   * describes the widget for display on the widget administration panel or
 645   * in the theme.
 646   *
 647   * @since 2.5.0
 648   *
 649   * @param int|string $id Widget ID.
 650   * @return string Widget description, if available. Null on failure to retrieve description.
 651   */
 652  function wp_widget_description( $id ) {
 653      if ( !is_scalar($id) )
 654          return;
 655  
 656      global $wp_registered_widgets;
 657  
 658      if ( isset($wp_registered_widgets[$id]['description']) )
 659          return esc_html( $wp_registered_widgets[$id]['description'] );
 660  }
 661  
 662  /**
 663   * Retrieve description for a sidebar.
 664   *
 665   * When registering sidebars a 'description' parameter can be included that
 666   * describes the sidebar for display on the widget administration panel.
 667   *
 668   * @since 2.9.0
 669   *
 670   * @param int|string $id sidebar ID.
 671   * @return string Sidebar description, if available. Null on failure to retrieve description.
 672   */
 673  function wp_sidebar_description( $id ) {
 674      if ( !is_scalar($id) )
 675          return;
 676  
 677      global $wp_registered_sidebars;
 678  
 679      if ( isset($wp_registered_sidebars[$id]['description']) )
 680          return esc_html( $wp_registered_sidebars[$id]['description'] );
 681  }
 682  
 683  
 684  /**
 685   * Remove widget from sidebar.
 686   *
 687   * @since 2.2.0
 688   *
 689   * @param int|string $id Widget ID.
 690   */
 691  function wp_unregister_sidebar_widget($id) {
 692      do_action( 'wp_unregister_sidebar_widget', $id );
 693  
 694      wp_register_sidebar_widget($id, '', '');
 695      wp_unregister_widget_control($id);
 696  }
 697  
 698  /**
 699   * Registers widget control callback for customizing options.
 700   *
 701   * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
 702   * option is never used. The 'width' option is the width of the fully expanded
 703   * control form, but try hard to use the default width. The 'id_base' is for
 704   * multi-widgets (widgets which allow multiple instances such as the text
 705   * widget), an id_base must be provided. The widget id will end up looking like
 706   * {$id_base}-{$unique_number}.
 707   *
 708   * @since 2.2.0
 709   *
 710   * @param int|string $id Sidebar ID.
 711   * @param string $name Sidebar display name.
 712   * @param callback $control_callback Run when sidebar is displayed.
 713   * @param array|string $options Optional. Widget options. See above long description.
 714   * @param mixed $params,... Optional. Additional parameters to add to widget.
 715   */
 716  function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
 717      global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
 718  
 719      $id = strtolower($id);
 720      $id_base = _get_widget_id_base($id);
 721  
 722      if ( empty($control_callback) ) {
 723          unset($wp_registered_widget_controls[$id]);
 724          unset($wp_registered_widget_updates[$id_base]);
 725          return;
 726      }
 727  
 728      if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) {
 729          if ( isset($wp_registered_widgets[$id]) )
 730              unset($wp_registered_widgets[$id]);
 731  
 732          return;
 733      }
 734  
 735      if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
 736          return;
 737  
 738      $defaults = array('width' => 250, 'height' => 200 ); // height is never used
 739      $options = wp_parse_args($options, $defaults);
 740      $options['width'] = (int) $options['width'];
 741      $options['height'] = (int) $options['height'];
 742  
 743      $widget = array(
 744          'name' => $name,
 745          'id' => $id,
 746          'callback' => $control_callback,
 747          'params' => array_slice(func_get_args(), 4)
 748      );
 749      $widget = array_merge($widget, $options);
 750  
 751      $wp_registered_widget_controls[$id] = $widget;
 752  
 753      if ( isset($wp_registered_widget_updates[$id_base]) )
 754          return;
 755  
 756      if ( isset($widget['params'][0]['number']) )
 757          $widget['params'][0]['number'] = -1;
 758  
 759      unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
 760      $wp_registered_widget_updates[$id_base] = $widget;
 761  }
 762  
 763  function _register_widget_update_callback($id_base, $update_callback, $options = array()) {
 764      global $wp_registered_widget_updates;
 765  
 766      if ( isset($wp_registered_widget_updates[$id_base]) ) {
 767          if ( empty($update_callback) )
 768              unset($wp_registered_widget_updates[$id_base]);
 769          return;
 770      }
 771  
 772      $widget = array(
 773          'callback' => $update_callback,
 774          'params' => array_slice(func_get_args(), 3)
 775      );
 776  
 777      $widget = array_merge($widget, $options);
 778      $wp_registered_widget_updates[$id_base] = $widget;
 779  }
 780  
 781  function _register_widget_form_callback($id, $name, $form_callback, $options = array()) {
 782      global $wp_registered_widget_controls;
 783  
 784      $id = strtolower($id);
 785  
 786      if ( empty($form_callback) ) {
 787          unset($wp_registered_widget_controls[$id]);
 788          return;
 789      }
 790  
 791      if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
 792          return;
 793  
 794      $defaults = array('width' => 250, 'height' => 200 );
 795      $options = wp_parse_args($options, $defaults);
 796      $options['width'] = (int) $options['width'];
 797      $options['height'] = (int) $options['height'];
 798  
 799      $widget = array(
 800          'name' => $name,
 801          'id' => $id,
 802          'callback' => $form_callback,
 803          'params' => array_slice(func_get_args(), 4)
 804      );
 805      $widget = array_merge($widget, $options);
 806  
 807      $wp_registered_widget_controls[$id] = $widget;
 808  }
 809  
 810  /**
 811   * Remove control callback for widget.
 812   *
 813   * @since 2.2.0
 814   * @uses wp_register_widget_control() Unregisters by using empty callback.
 815   *
 816   * @param int|string $id Widget ID.
 817   */
 818  function wp_unregister_widget_control($id) {
 819      return wp_register_widget_control($id, '', '');
 820  }
 821  
 822  /**
 823   * Display dynamic sidebar.
 824   *
 825   * By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is
 826   * not named by the theme, the actual name is '1', but 'sidebar-' is added to
 827   * the registered sidebars for the name. If you named your sidebar 'after-post',
 828   * then the parameter $index will still be 'after-post', but the lookup will be
 829   * for 'sidebar-after-post'.
 830   *
 831   * It is confusing for the $index parameter, but just know that it should just
 832   * work. When you register the sidebar in the theme, you will use the same name
 833   * for this function or "Pay no heed to the man behind the curtain." Just accept
 834   * it as an oddity of WordPress sidebar register and display.
 835   *
 836   * @since 2.2.0
 837   *
 838   * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.
 839   * @return bool True, if widget sidebar was found and called. False if not found or not called.
 840   */
 841  function dynamic_sidebar($index = 1) {
 842      global $wp_registered_sidebars, $wp_registered_widgets;
 843  
 844      if ( is_int($index) ) {
 845          $index = "sidebar-$index";
 846      } else {
 847          $index = sanitize_title($index);
 848          foreach ( (array) $wp_registered_sidebars as $key => $value ) {
 849              if ( sanitize_title($value['name']) == $index ) {
 850                  $index = $key;
 851                  break;
 852              }
 853          }
 854      }
 855  
 856      $sidebars_widgets = wp_get_sidebars_widgets();
 857      if ( empty( $sidebars_widgets ) )
 858          return false;
 859  
 860      if ( empty($wp_registered_sidebars[$index]) || !array_key_exists($index, $sidebars_widgets) || !is_array($sidebars_widgets[$index]) || empty($sidebars_widgets[$index]) )
 861          return false;
 862  
 863      $sidebar = $wp_registered_sidebars[$index];
 864  
 865      $did_one = false;
 866      foreach ( (array) $sidebars_widgets[$index] as $id ) {
 867  
 868          if ( !isset($wp_registered_widgets[$id]) ) continue;
 869  
 870          $params = array_merge(
 871              array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ),
 872              (array) $wp_registered_widgets[$id]['params']
 873          );
 874  
 875          // Substitute HTML id and class attributes into before_widget
 876          $classname_ = '';
 877          foreach ( (array) $wp_registered_widgets[$id]['classname'] as $cn ) {
 878              if ( is_string($cn) )
 879                  $classname_ .= '_' . $cn;
 880              elseif ( is_object($cn) )
 881                  $classname_ .= '_' . get_class($cn);
 882          }
 883          $classname_ = ltrim($classname_, '_');
 884          $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
 885  
 886          $params = apply_filters( 'dynamic_sidebar_params', $params );
 887  
 888          $callback = $wp_registered_widgets[$id]['callback'];
 889  
 890          do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );
 891  
 892          if ( is_callable($callback) ) {
 893              call_user_func_array($callback, $params);
 894              $did_one = true;
 895          }
 896      }
 897  
 898      return $did_one;
 899  }
 900  
 901  /**
 902   * Whether widget is displayied on the front-end.
 903   *
 904   * Either $callback or $id_base can be used
 905   * $id_base is the first argument when extending WP_Widget class
 906   * Without the optional $widget_id parameter, returns the ID of the first sidebar
 907   * in which the first instance of the widget with the given callback or $id_base is found.
 908   * With the $widget_id parameter, returns the ID of the sidebar where
 909   * the widget with that callback/$id_base AND that ID is found.
 910   *
 911   * NOTE: $widget_id and $id_base are the same for single widgets. To be effective
 912   * this function has to run after widgets have initialized, at action 'init' or later.
 913   *
 914   * @since 2.2.0
 915   *
 916   * @param string $callback Optional, Widget callback to check.
 917   * @param int $widget_id Optional, but needed for checking. Widget ID.
 918   * @param string $id_base Optional, the base ID of a widget created by extending WP_Widget.
 919   * @param bool $skip_inactive Optional, whether to check in 'wp_inactive_widgets'.
 920   * @return mixed false if widget is not active or id of sidebar in which the widget is active.
 921   */
 922  function is_active_widget($callback = false, $widget_id = false, $id_base = false, $skip_inactive = true) {
 923      global $wp_registered_widgets;
 924  
 925      $sidebars_widgets = wp_get_sidebars_widgets();
 926  
 927      if ( is_array($sidebars_widgets) ) {
 928          foreach ( $sidebars_widgets as $sidebar => $widgets ) {
 929              if ( $skip_inactive && 'wp_inactive_widgets' == $sidebar )
 930                  continue;
 931  
 932              if ( is_array($widgets) ) {
 933                  foreach ( $widgets as $widget ) {
 934                      if ( ( $callback && isset($wp_registered_widgets[$widget]['callback']) && $wp_registered_widgets[$widget]['callback'] == $callback ) || ( $id_base && _get_widget_id_base($widget) == $id_base ) ) {
 935                          if ( !$widget_id || $widget_id == $wp_registered_widgets[$widget]['id'] )
 936                              return $sidebar;
 937                      }
 938                  }
 939              }
 940          }
 941      }
 942      return false;
 943  }
 944  
 945  /**
 946   * Whether the dynamic sidebar is enabled and used by theme.
 947   *
 948   * @since 2.2.0
 949   *
 950   * @return bool True, if using widgets. False, if not using widgets.
 951   */
 952  function is_dynamic_sidebar() {
 953      global $wp_registered_widgets, $wp_registered_sidebars;
 954      $sidebars_widgets = get_option('sidebars_widgets');
 955      foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) {
 956          if ( count($sidebars_widgets[$index]) ) {
 957              foreach ( (array) $sidebars_widgets[$index] as $widget )
 958                  if ( array_key_exists($widget, $wp_registered_widgets) )
 959                      return true;
 960          }
 961      }
 962      return false;
 963  }
 964  
 965  /**
 966   * Whether a sidebar is in use.
 967   *
 968   * @since 2.8
 969   *
 970   * @param mixed $index Sidebar name, id or number to check.
 971   * @return bool true if the sidebar is in use, false otherwise.
 972   */
 973  function is_active_sidebar( $index ) {
 974      $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
 975      $sidebars_widgets = wp_get_sidebars_widgets();
 976      if ( !empty($sidebars_widgets[$index]) )
 977          return true;
 978  
 979      return false;
 980  }
 981  
 982  /* Internal Functions */
 983  
 984  /**
 985   * Retrieve full list of sidebars and their widgets.
 986   *
 987   * Will upgrade sidebar widget list, if needed. Will also save updated list, if
 988   * needed.
 989   *
 990   * @since 2.2.0
 991   * @access private
 992   *
 993   * @param bool $deprecated Not used (deprecated).
 994   * @return array Upgraded list of widgets to version 3 array format when called from the admin.
 995   */
 996  function wp_get_sidebars_widgets($deprecated = true) {
 997      if ( $deprecated !== true )
 998          _deprecated_argument( __FUNCTION__, '2.8.1' );
 999  
1000      global $wp_registered_widgets, $wp_registered_sidebars, $_wp_sidebars_widgets;
1001  
1002      // If loading from front page, consult $_wp_sidebars_widgets rather than options
1003      // to see if wp_convert_widget_settings() has made manipulations in memory.
1004      if ( !is_admin() ) {
1005          if ( empty($_wp_sidebars_widgets) )
1006              $_wp_sidebars_widgets = get_option('sidebars_widgets', array());
1007  
1008          $sidebars_widgets = $_wp_sidebars_widgets;
1009      } else {
1010          $sidebars_widgets = get_option('sidebars_widgets', array());
1011          $_sidebars_widgets = array();
1012  
1013          if ( isset($sidebars_widgets['wp_inactive_widgets']) || empty($sidebars_widgets) )
1014              $sidebars_widgets['array_version'] = 3;
1015          elseif ( !isset($sidebars_widgets['array_version']) )
1016              $sidebars_widgets['array_version'] = 1;
1017  
1018          switch ( $sidebars_widgets['array_version'] ) {
1019              case 1 :
1020                  foreach ( (array) $sidebars_widgets as $index => $sidebar )
1021                  if ( is_array($sidebar) )
1022                  foreach ( (array) $sidebar as $i => $name ) {
1023                      $id = strtolower($name);
1024                      if ( isset($wp_registered_widgets[$id]) ) {
1025                          $_sidebars_widgets[$index][$i] = $id;
1026                          continue;
1027                      }
1028                      $id = sanitize_title($name);
1029                      if ( isset($wp_registered_widgets[$id]) ) {
1030                          $_sidebars_widgets[$index][$i] = $id;
1031                          continue;
1032                      }
1033  
1034                      $found = false;
1035  
1036                      foreach ( $wp_registered_widgets as $widget_id => $widget ) {
1037                          if ( strtolower($widget['name']) == strtolower($name) ) {
1038                              $_sidebars_widgets[$index][$i] = $widget['id'];
1039                              $found = true;
1040                              break;
1041                          } elseif ( sanitize_title($widget['name']) == sanitize_title($name) ) {
1042                              $_sidebars_widgets[$index][$i] = $widget['id'];
1043                              $found = true;
1044                              break;
1045                          }
1046                      }
1047  
1048                      if ( $found )
1049                          continue;
1050  
1051                      unset($_sidebars_widgets[$index][$i]);
1052                  }
1053                  $_sidebars_widgets['array_version'] = 2;
1054                  $sidebars_widgets = $_sidebars_widgets;
1055                  unset($_sidebars_widgets);
1056  
1057              case 2 :
1058                  $sidebars = array_keys( $wp_registered_sidebars );
1059                  if ( !empty( $sidebars ) ) {
1060                      // Move the known-good ones first
1061                      foreach ( (array) $sidebars as $id ) {
1062                          if ( array_key_exists( $id, $sidebars_widgets ) ) {
1063                              $_sidebars_widgets[$id] = $sidebars_widgets[$id];
1064                              unset($sidebars_widgets[$id], $sidebars[$id]);
1065                          }
1066                      }
1067  
1068                      // move the rest to wp_inactive_widgets
1069                      if ( !isset($_sidebars_widgets['wp_inactive_widgets']) )
1070                          $_sidebars_widgets['wp_inactive_widgets'] = array();
1071  
1072                      if ( !empty($sidebars_widgets) ) {
1073                          foreach ( $sidebars_widgets as $lost => $val ) {
1074                              if ( is_array($val) )
1075                                  $_sidebars_widgets['wp_inactive_widgets'] = array_merge( (array) $_sidebars_widgets['wp_inactive_widgets'], $val );
1076                          }
1077                      }
1078  
1079                      $sidebars_widgets = $_sidebars_widgets;
1080                      unset($_sidebars_widgets);
1081                  }
1082          }
1083      }
1084  
1085      if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) )
1086          unset($sidebars_widgets['array_version']);
1087  
1088      $sidebars_widgets = apply_filters('sidebars_widgets', $sidebars_widgets);
1089      return $sidebars_widgets;
1090  }
1091  
1092  /**
1093   * Set the sidebar widget option to update sidebars.
1094   *
1095   * @since 2.2.0
1096   * @access private
1097   *
1098   * @param array $sidebars_widgets Sidebar widgets and their settings.
1099   */
1100  function wp_set_sidebars_widgets( $sidebars_widgets ) {
1101      if ( !isset( $sidebars_widgets['array_version'] ) )
1102          $sidebars_widgets['array_version'] = 3;
1103      update_option( 'sidebars_widgets', $sidebars_widgets );
1104  }
1105  
1106  /**
1107   * Retrieve default registered sidebars list.
1108   *
1109   * @since 2.2.0
1110   * @access private
1111   *
1112   * @return array
1113   */
1114  function wp_get_widget_defaults() {
1115      global $wp_registered_sidebars;
1116  
1117      $defaults = array();
1118  
1119      foreach ( (array) $wp_registered_sidebars as $index => $sidebar )
1120          $defaults[$index] = array();
1121  
1122      return $defaults;
1123  }
1124  
1125  /**
1126   * Convert the widget settings from single to multi-widget format.
1127   *
1128   * @since 2.8.0
1129   *
1130   * @return array
1131   */
1132  function wp_convert_widget_settings($base_name, $option_name, $settings) {
1133      // This test may need expanding.
1134      $single = $changed = false;
1135      if ( empty($settings) ) {
1136          $single = true;
1137      } else {
1138          foreach ( array_keys($settings) as $number ) {
1139              if ( 'number' == $number )
1140                  continue;
1141              if ( !is_numeric($number) ) {
1142                  $single = true;
1143                  break;
1144              }
1145          }
1146      }
1147  
1148      if ( $single ) {
1149          $settings = array( 2 => $settings );
1150  
1151          // If loading from the front page, update sidebar in memory but don't save to options
1152          if ( is_admin() ) {
1153              $sidebars_widgets = get_option('sidebars_widgets');
1154          } else {
1155              if ( empty($GLOBALS['_wp_sidebars_widgets']) )
1156                  $GLOBALS['_wp_sidebars_widgets'] = get_option('sidebars_widgets', array());
1157              $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets'];
1158          }
1159  
1160          foreach ( (array) $sidebars_widgets as $index => $sidebar ) {
1161              if ( is_array($sidebar) ) {
1162                  foreach ( $sidebar as $i => $name ) {
1163                      if ( $base_name == $name ) {
1164                          $sidebars_widgets[$index][$i] = "$name-2";
1165                          $changed = true;
1166                          break 2;
1167                      }
1168                  }
1169              }
1170          }
1171  
1172          if ( is_admin() && $changed )
1173              update_option('sidebars_widgets', $sidebars_widgets);
1174      }
1175  
1176      $settings['_multiwidget'] = 1;
1177      if ( is_admin() )
1178          update_option( $option_name, $settings );
1179  
1180      return $settings;
1181  }
1182  
1183  /**
1184   * Output an arbitrary widget as a template tag
1185   *
1186   * @since 2.8
1187   *
1188   * @param string $widget the widget's PHP class name (see default-widgets.php)
1189   * @param array $instance the widget's instance settings
1190   * @param array $args the widget's sidebar args
1191   * @return void
1192   **/
1193  function the_widget($widget, $instance = array(), $args = array()) {
1194      global $wp_widget_factory;
1195  
1196      $widget_obj = $wp_widget_factory->widgets[$widget];
1197      if ( !is_a($widget_obj, 'WP_Widget') )
1198          return;
1199  
1200      $before_widget = sprintf('<div class="widget %s">', $widget_obj->widget_options['classname']);
1201      $default_args = array('before_widget' => $before_widget, 'after_widget' => "</div>", 'before_title' => '<h2 class="widgettitle">', 'after_title' => '</h2>');
1202  
1203      $args = wp_parse_args($args, $default_args);
1204      $instance = wp_parse_args($instance);
1205  
1206      do_action( 'the_widget', $widget, $instance, $args );
1207  
1208      $widget_obj->_set(-1);
1209      $widget_obj->widget($args, $instance);
1210  }
1211  
1212  /**
1213   * Private
1214   */
1215  function _get_widget_id_base($id) {
1216      return preg_replace( '/-[0-9]+$/', '', $id );
1217  }