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 		$this->__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 

   130 		if ( empty($settings) ) {

   131 			// If there are none, we register the widget's existance with a

   132 			// generic template

   133 			$this->_set(1);

   134 			$this->_register_one();

   135 		} elseif ( is_array($settings) ) {

   136 			foreach ( array_keys($settings) as $number ) {

   137 				if ( is_numeric($number) ) {

   138 					$this->_set($number);

   139 					$this->_register_one($number);

   140 				}

   141 			}

   142 		}

   143 	}

   144 

   145 	function _set($number) {

   146 		$this->number = $number;

   147 		$this->id = $this->id_base . '-' . $number;

   148 	}

   149 

   150 	function _get_display_callback() {

   151 		return array(&$this, 'display_callback');

   152 	}

   153 

   154 	function _get_update_callback() {

   155 		return array(&$this, 'update_callback');

   156 	}

   157 

   158 	function _get_form_callback() {

   159 		return array(&$this, 'form_callback');

   160 	}

   161 

   162 	/** Generate the actual widget content.

   163 	 *	Just finds the instance and calls widget().

   164 	 *	Do NOT over-ride this function. */

   165 	function display_callback( $args, $widget_args = 1 ) {

   166 		if ( is_numeric($widget_args) )

   167 			$widget_args = array( 'number' => $widget_args );

   168 

   169 		$widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );

   170 		$this->_set( $widget_args['number'] );

   171 		$instance = $this->get_settings();

   172 

   173 		if ( array_key_exists( $this->number, $instance ) ) {

   174 			$instance = $instance[$this->number];

   175 			// filters the widget's settings, return false to stop displaying the widget

   176 			$instance = apply_filters('widget_display_callback', $instance, $this, $args);

   177 			if ( false !== $instance )

   178 				$this->widget($args, $instance);

   179 		}

   180 	}

   181 

   182 	/** Deal with changed settings.

   183 	 *	Do NOT over-ride this function. */

   184 	function update_callback( $widget_args = 1 ) {

   185 		global $wp_registered_widgets;

   186 

   187 		if ( is_numeric($widget_args) )

   188 			$widget_args = array( 'number' => $widget_args );

   189 

   190 		$widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );

   191 		$all_instances = $this->get_settings();

   192 

   193 		// We need to update the data

   194 		if ( $this->updated )

   195 			return;

   196 

   197 		$sidebars_widgets = wp_get_sidebars_widgets();

   198 

   199 		if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) {

   200 			// Delete the settings for this instance of the widget

   201 			if ( isset($_POST['the-widget-id']) )

   202 				$del_id = $_POST['the-widget-id'];

   203 			else

   204 				return;

   205 

   206 			if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) {

   207 				$number = $wp_registered_widgets[$del_id]['params'][0]['number'];

   208 

   209 				if ( $this->id_base . '-' . $number == $del_id )

   210 					unset($all_instances[$number]);

   211 			}

   212 		} else {

   213 			if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) {

   214 				$settings = $_POST['widget-' . $this->id_base];

   215 			} elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) {

   216 				$num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];

   217 				$settings = array( $num => array() );

   218 			} else {

   219 				return;

   220 			}

   221 

   222 			foreach ( $settings as $number => $new_instance ) {

   223 				$new_instance = stripslashes_deep($new_instance);

   224 				$this->_set($number);

   225 

   226 				$old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array();

   227 

   228 				$instance = $this->update($new_instance, $old_instance);

   229 

   230 				// filters the widget's settings before saving, return false to cancel saving (keep the old settings if updating)

   231 				$instance = apply_filters('widget_update_callback', $instance, $new_instance, $old_instance, $this);

   232 				if ( false !== $instance )

   233 					$all_instances[$number] = $instance;

   234 

   235 				break; // run only once

   236 			}

   237 		}

   238 

   239 		$this->save_settings($all_instances);

   240 		$this->updated = true;

   241 	}

   242 

   243 	/** Generate the control form.

   244 	 *	Do NOT over-ride this function. */

   245 	function form_callback( $widget_args = 1 ) {

   246 		if ( is_numeric($widget_args) )

   247 			$widget_args = array( 'number' => $widget_args );

   248 

   249 		$widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );

   250 		$all_instances = $this->get_settings();

   251 

   252 		if ( -1 == $widget_args['number'] ) {

   253 			// We echo out a form where 'number' can be set later

   254 			$this->_set('__i__');

   255 			$instance = array();

   256 		} else {

   257 			$this->_set($widget_args['number']);

   258 			$instance = $all_instances[ $widget_args['number'] ];

   259 		}

   260 

   261 		// filters the widget admin form before displaying, return false to stop displaying it

   262 		$instance = apply_filters('widget_form_callback', $instance, $this);

   263 

   264 		$return = null;

   265 		if ( false !== $instance ) {

   266 			$return = $this->form($instance);

   267 			// add extra fields in the widget form - be sure to set $return to null if you add any

   268 			// if the widget has no form the text echoed from the default form method can be hidden using css

   269 			do_action_ref_array( 'in_widget_form', array(&$this, &$return, $instance) );

   270 		}

   271 		return $return;

   272 	}

   273 

   274 	/** Helper function: Registers a single instance. */

   275 	function _register_one($number = -1) {

   276 		wp_register_sidebar_widget(	$this->id, $this->name,	$this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );

   277 		_register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );

   278 		_register_widget_form_callback(	$this->id, $this->name,	$this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );

   279 	}

   280 

   281 	function save_settings($settings) {

   282 		$settings['_multiwidget'] = 1;

   283 		update_option( $this->option_name, $settings );

   284 	}

   285 

   286 	function get_settings() {

   287 		$settings = get_option($this->option_name);

   288 

   289 		if ( false === $settings && isset($this->alt_option_name) )

   290 			$settings = get_option($this->alt_option_name);

   291 

   292 		if ( !is_array($settings) )

   293 			$settings = array();

   294 

   295 		if ( !array_key_exists('_multiwidget', $settings) ) {

   296 			// old format, conver if single widget

   297 			$settings = wp_convert_widget_settings($this->id_base, $this->option_name, $settings);

   298 		}

   299 

   300 		unset($settings['_multiwidget'], $settings['__i__']);

   301 		return $settings;

   302 	}

   303 }

   304 

   305 /**

   306  * Singleton that registers and instantiates WP_Widget classes.

   307  *

   308  * @package WordPress

   309  * @subpackage Widgets

   310  * @since 2.8

   311  */

   312 class WP_Widget_Factory {

   313 	var $widgets = array();

   314 

   315 	function WP_Widget_Factory() {

   316 		add_action( 'widgets_init', array( &$this, '_register_widgets' ), 100 );

   317 	}

   318 

   319 	function register($widget_class) {

   320 		$this->widgets[$widget_class] = & new $widget_class();

   321 	}

   322 

   323 	function unregister($widget_class) {

   324 		if ( isset($this->widgets[$widget_class]) )

   325 			unset($this->widgets[$widget_class]);

   326 	}

   327 

   328 	function _register_widgets() {

   329 		global $wp_registered_widgets;

   330 		$keys = array_keys($this->widgets);

   331 		$registered = array_keys($wp_registered_widgets);

   332 		$registered = array_map('_get_widget_id_base', $registered);

   333 

   334 		foreach ( $keys as $key ) {

   335 			// don't register new widget if old widget with the same id is already registered

   336 			if ( in_array($this->widgets[$key]->id_base, $registered, true) ) {

   337 				unset($this->widgets[$key]);

   338 				continue;

   339 			}

   340 

   341 			$this->widgets[$key]->_register();

   342 		}

   343 	}

   344 }

   345 

   346 /* Global Variables */

   347 

   348 /** @ignore */

   349 global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates;

   350 

   351 /**

   352  * Stores the sidebars, since many themes can have more than one.

   353  *

   354  * @global array $wp_registered_sidebars

   355  * @since 2.2.0

   356  */

   357 $wp_registered_sidebars = array();

   358 

   359 /**

   360  * Stores the registered widgets.

   361  *

   362  * @global array $wp_registered_widgets

   363  * @since 2.2.0

   364  */

   365 $wp_registered_widgets = array();

   366 

   367 /**

   368  * Stores the registered widget control (options).

   369  *

   370  * @global array $wp_registered_widget_controls

   371  * @since 2.2.0

   372  */

   373 $wp_registered_widget_controls = array();

   374 $wp_registered_widget_updates = array();

   375 

   376 /**

   377  * Private

   378  */

   379 $_wp_sidebars_widgets = array();

   380 

   381 /**

   382  * Private

   383  */

   384  $_wp_deprecated_widgets_callbacks = array(

   385  	'wp_widget_pages',

   386 	'wp_widget_pages_control',

   387 	'wp_widget_calendar',

   388 	'wp_widget_calendar_control',

   389 	'wp_widget_archives',

   390 	'wp_widget_archives_control',

   391 	'wp_widget_links',

   392 	'wp_widget_meta',

   393 	'wp_widget_meta_control',

   394 	'wp_widget_search',

   395 	'wp_widget_recent_entries',

   396 	'wp_widget_recent_entries_control',

   397 	'wp_widget_tag_cloud',

   398 	'wp_widget_tag_cloud_control',

   399 	'wp_widget_categories',

   400 	'wp_widget_categories_control',

   401 	'wp_widget_text',

   402 	'wp_widget_text_control',

   403 	'wp_widget_rss',

   404 	'wp_widget_rss_control',

   405 	'wp_widget_recent_comments',

   406 	'wp_widget_recent_comments_control'

   407  );

   408 

   409 /* Template tags & API functions */

   410 

   411 /**

   412  * Register a widget

   413  *

   414  * Registers a WP_Widget widget

   415  *

   416  * @since 2.8.0

   417  *

   418  * @see WP_Widget

   419  * @see WP_Widget_Factory

   420  * @uses WP_Widget_Factory

   421  *

   422  * @param string $widget_class The name of a class that extends WP_Widget

   423  */

   424 function register_widget($widget_class) {

   425 	global $wp_widget_factory;

   426 

   427 	$wp_widget_factory->register($widget_class);

   428 }

   429 

   430 /**

   431  * Unregister a widget

   432  *

   433  * Unregisters a WP_Widget widget. Useful for unregistering default widgets.

   434  * Run within a function hooked to the widgets_init action.

   435  *

   436  * @since 2.8.0

   437  *

   438  * @see WP_Widget

   439  * @see WP_Widget_Factory

   440  * @uses WP_Widget_Factory

   441  *

   442  * @param string $widget_class The name of a class that extends WP_Widget

   443  */

   444 function unregister_widget($widget_class) {

   445 	global $wp_widget_factory;

   446 

   447 	$wp_widget_factory->unregister($widget_class);

   448 }

   449 

   450 /**

   451  * Creates multiple sidebars.

   452  *

   453  * If you wanted to quickly create multiple sidebars for a theme or internally.

   454  * This function will allow you to do so. If you don't pass the 'name' and/or

   455  * 'id' in $args, then they will be built for you.

   456  *

   457  * The default for the name is "Sidebar #", with '#' being replaced with the

   458  * number the sidebar is currently when greater than one. If first sidebar, the

   459  * name will be just "Sidebar". The default for id is "sidebar-" followed by the

   460  * number the sidebar creation is currently at.

   461  *

   462  * @since 2.2.0

   463  *

   464  * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.

   465  * @uses parse_str() Converts a string to an array to be used in the rest of the function.

   466  * @uses register_sidebar() Sends single sidebar information [name, id] to this

   467  *	function to handle building the sidebar.

   468  *

   469  * @param int $number Number of sidebars to create.

   470  * @param string|array $args Builds Sidebar based off of 'name' and 'id' values.

   471  */

   472 function register_sidebars($number = 1, $args = array()) {

   473 	global $wp_registered_sidebars;

   474 	$number = (int) $number;

   475 

   476 	if ( is_string($args) )

   477 		parse_str($args, $args);

   478 

   479 	for ( $i=1; $i <= $number; $i++ ) {

   480 		$_args = $args;

   481 

   482 		if ( $number > 1 ) {

   483 			$_args['name'] = isset($args['name']) ? sprintf($args['name'], $i) : sprintf(__('Sidebar %d'), $i);

   484 		} else {

   485 			$_args['name'] = isset($args['name']) ? $args['name'] : __('Sidebar');

   486 		}

   487 

   488 		if (isset($args['id'])) {

   489 			$_args['id'] = $args['id'];

   490 		} else {

   491 			$n = count($wp_registered_sidebars);

   492 			do {

   493 				$n++;

   494 				$_args['id'] = "sidebar-$n";

   495 			} while (isset($wp_registered_sidebars[$_args['id']]));

   496 		}

   497 

   498 		register_sidebar($_args);

   499 	}

   500 }

   501 

   502 /**

   503  * Builds the definition for a single sidebar and returns the ID.

   504  *

   505  * The $args parameter takes either a string or an array with 'name' and 'id'

   506  * contained in either usage. It will be noted that the values will be applied

   507  * to all sidebars, so if creating more than one, it will be advised to allow

   508  * for WordPress to create the defaults for you.

   509  *

   510  * Example for string would be <code>'name=whatever;id=whatever1'</code> and for

   511  * the array it would be <code>array(

   512  *    'name' => 'whatever',

   513  *    'id' => 'whatever1')</code>.

   514  *

   515  * name - The name of the sidebar, which presumably the title which will be

   516  *     displayed.

   517  * id - The unique identifier by which the sidebar will be called by.

   518  * before_widget - The content that will prepended to the widgets when they are

   519  *     displayed.

   520  * after_widget - The content that will be appended to the widgets when they are

   521  *     displayed.

   522  * before_title - The content that will be prepended to the title when displayed.

   523  * after_title - the content that will be appended to the title when displayed.

   524  *

   525  * <em>Content</em> is assumed to be HTML and should be formatted as such, but

   526  * doesn't have to be.

   527  *

   528  * @since 2.2.0

   529  * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.

   530  * @uses parse_str() Converts a string to an array to be used in the rest of the function.

   531  * @usedby register_sidebars()

   532  *

   533  * @param string|array $args Builds Sidebar based off of 'name' and 'id' values

   534  * @return string The sidebar id that was added.

   535  */

   536 function register_sidebar($args = array()) {

   537 	global $wp_registered_sidebars;

   538 

   539 	if ( is_string($args) )

   540 		parse_str($args, $args);

   541 

   542 	$i = count($wp_registered_sidebars) + 1;

   543 

   544 	$defaults = array(

   545 		'name' => sprintf(__('Sidebar %d'), $i ),

   546 		'id' => "sidebar-$i",

   547 		'before_widget' => '<li id="%1$s" class="widget %2$s">',

   548 		'after_widget' => "</li>\n",

   549 		'before_title' => '<h2 class="widgettitle">',

   550 		'after_title' => "</h2>\n",

   551 	);

   552 

   553 	$sidebar = array_merge($defaults, (array) $args);

   554 

   555 	$wp_registered_sidebars[$sidebar['id']] = $sidebar;

   556 

   557 	return $sidebar['id'];

   558 }

   559 

   560 /**

   561  * Removes a sidebar from the list.

   562  *

   563  * @since 2.2.0

   564  *

   565  * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.

   566  *

   567  * @param string $name The ID of the sidebar when it was added.

   568  */

   569 function unregister_sidebar( $name ) {

   570 	global $wp_registered_sidebars;

   571 

   572 	if ( isset( $wp_registered_sidebars[$name] ) )

   573 		unset( $wp_registered_sidebars[$name] );

   574 }

   575 

   576 /**

   577  * Register widget for use in sidebars.

   578  *

   579  * The default widget option is 'classname' that can be override.

   580  *

   581  * The function can also be used to unregister widgets when $output_callback

   582  * parameter is an empty string.

   583  *

   584  * @since 2.2.0

   585  *

   586  * @uses $wp_registered_widgets Uses stored registered widgets.

   587  * @uses $wp_register_widget_defaults Retrieves widget defaults.

   588  *

   589  * @param int|string $id Widget ID.

   590  * @param string $name Widget display title.

   591  * @param callback $output_callback Run when widget is called.

   592  * @param array|string Optional. $options Widget Options.

   593  * @param mixed $params,... Widget parameters to add to widget.

   594  * @return null Will return if $output_callback is empty after removing widget.

   595  */

   596 function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {

   597 	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;

   598 

   599 	$id = strtolower($id);

   600 

   601 	if ( empty($output_callback) ) {

   602 		unset($wp_registered_widgets[$id]);

   603 		return;

   604 	}

   605 

   606 	$id_base = _get_widget_id_base($id);

   607 	if ( in_array($output_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($output_callback) ) {

   608 		if ( isset($wp_registered_widget_controls[$id]) )

   609 			unset($wp_registered_widget_controls[$id]);

   610 

   611 		if ( isset($wp_registered_widget_updates[$id_base]) )

   612 			unset($wp_registered_widget_updates[$id_base]);

   613 

   614 		return;

   615 	}

   616 

   617 	$defaults = array('classname' => $output_callback);

   618 	$options = wp_parse_args($options, $defaults);

   619 	$widget = array(

   620 		'name' => $name,

   621 		'id' => $id,

   622 		'callback' => $output_callback,

   623 		'params' => array_slice(func_get_args(), 4)

   624 	);

   625 	$widget = array_merge($widget, $options);

   626 

   627 	if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) )

   628 		$wp_registered_widgets[$id] = $widget;

   629 }

   630 

   631 /**

   632  * Retrieve description for widget.

   633  *

   634  * When registering widgets, the options can also include 'description' that

   635  * describes the widget for display on the widget administration panel or

   636  * in the theme.

   637  *

   638  * @since 2.5.0

   639  *

   640  * @param int|string $id Widget ID.

   641  * @return string Widget description, if available. Null on failure to retrieve description.

   642  */

   643 function wp_widget_description( $id ) {

   644 	if ( !is_scalar($id) )

   645 		return;

   646 

   647 	global $wp_registered_widgets;

   648 

   649 	if ( isset($wp_registered_widgets[$id]['description']) )

   650 		return esc_html( $wp_registered_widgets[$id]['description'] );

   651 }

   652 

   653 /**

   654  * Remove widget from sidebar.

   655  *

   656  * @since 2.2.0

   657  *

   658  * @param int|string $id Widget ID.

   659  */

   660 function wp_unregister_sidebar_widget($id) {

   661 	wp_register_sidebar_widget($id, '', '');

   662 	wp_unregister_widget_control($id);

   663 }

   664 

   665 /**

   666  * Registers widget control callback for customizing options.

   667  *

   668  * The options contains the 'height', 'width', and 'id_base' keys. The 'height'

   669  * option is never used. The 'width' option is the width of the fully expanded

   670  * control form, but try hard to use the default width. The 'id_base' is for

   671  * multi-widgets (widgets which allow multiple instances such as the text

   672  * widget), an id_base must be provided. The widget id will end up looking like

   673  * {$id_base}-{$unique_number}.

   674  *

   675  * @since 2.2.0

   676  *

   677  * @param int|string $id Sidebar ID.

   678  * @param string $name Sidebar display name.

   679  * @param callback $control_callback Run when sidebar is displayed.

   680  * @param array|string $options Optional. Widget options. See above long description.

   681  * @param mixed $params,... Optional. Additional parameters to add to widget.

   682  */

   683 function wp_register_widget_control($id, $name, $control_callback, $options = array()) {

   684 	global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;

   685 

   686 	$id = strtolower($id);

   687 	$id_base = _get_widget_id_base($id);

   688 

   689 	if ( empty($control_callback) ) {

   690 		unset($wp_registered_widget_controls[$id]);

   691 		unset($wp_registered_widget_updates[$id_base]);

   692 		return;

   693 	}

   694 

   695 	if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) {

   696 		if ( isset($wp_registered_widgets[$id]) )

   697 			unset($wp_registered_widgets[$id]);

   698 

   699 		return;

   700 	}

   701 

   702 	if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )

   703 		return;

   704 

   705 	$defaults = array('width' => 250, 'height' => 200 ); // height is never used

   706 	$options = wp_parse_args($options, $defaults);

   707 	$options['width'] = (int) $options['width'];

   708 	$options['height'] = (int) $options['height'];

   709 

   710 	$widget = array(

   711 		'name' => $name,

   712 		'id' => $id,

   713 		'callback' => $control_callback,

   714 		'params' => array_slice(func_get_args(), 4)

   715 	);

   716 	$widget = array_merge($widget, $options);

   717 

   718 	$wp_registered_widget_controls[$id] = $widget;

   719 

   720 	if ( isset($wp_registered_widget_updates[$id_base]) )

   721 		return;

   722 

   723 	if ( isset($widget['params'][0]['number']) )

   724 		$widget['params'][0]['number'] = -1;

   725 

   726 	unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);

   727 	$wp_registered_widget_updates[$id_base] = $widget;

   728 }

   729 

   730 function _register_widget_update_callback($id_base, $update_callback, $options = array()) {

   731 	global $wp_registered_widget_updates;

   732 

   733 	if ( isset($wp_registered_widget_updates[$id_base]) ) {

   734 		if ( empty($update_callback) )

   735 			unset($wp_registered_widget_updates[$id_base]);

   736 		return;

   737 	}

   738 

   739 	$widget = array(

   740 		'callback' => $update_callback,

   741 		'params' => array_slice(func_get_args(), 3)

   742 	);

   743 

   744 	$widget = array_merge($widget, $options);

   745 	$wp_registered_widget_updates[$id_base] = $widget;

   746 }

   747 

   748 function _register_widget_form_callback($id, $name, $form_callback, $options = array()) {

   749 	global $wp_registered_widget_controls;

   750 

   751 	$id = strtolower($id);

   752 

   753 	if ( empty($form_callback) ) {

   754 		unset($wp_registered_widget_controls[$id]);

   755 		return;

   756 	}

   757 

   758 	if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )

   759 		return;

   760 

   761 	$defaults = array('width' => 250, 'height' => 200 );

   762 	$options = wp_parse_args($options, $defaults);

   763 	$options['width'] = (int) $options['width'];

   764 	$options['height'] = (int) $options['height'];

   765 

   766 	$widget = array(

   767 		'name' => $name,

   768 		'id' => $id,

   769 		'callback' => $form_callback,

   770 		'params' => array_slice(func_get_args(), 4)

   771 	);

   772 	$widget = array_merge($widget, $options);

   773 

   774 	$wp_registered_widget_controls[$id] = $widget;

   775 }

   776 

   777 /**

   778  * Remove control callback for widget.

   779  *

   780  * @since 2.2.0

   781  * @uses wp_register_widget_control() Unregisters by using empty callback.

   782  *

   783  * @param int|string $id Widget ID.

   784  */

   785 function wp_unregister_widget_control($id) {

   786 	return wp_register_widget_control($id, '', '');

   787 }

   788 

   789 /**

   790  * Display dynamic sidebar.

   791  *

   792  * By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is

   793  * not named by the theme, the actual name is '1', but 'sidebar-' is added to

   794  * the registered sidebars for the name. If you named your sidebar 'after-post',

   795  * then the parameter $index will still be 'after-post', but the lookup will be

   796  * for 'sidebar-after-post'.

   797  *

   798  * It is confusing for the $index parameter, but just know that it should just

   799  * work. When you register the sidebar in the theme, you will use the same name

   800  * for this function or "Pay no heed to the man behind the curtain." Just accept

   801  * it as an oddity of WordPress sidebar register and display.

   802  *

   803  * @since 2.2.0

   804  *

   805  * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.

   806  * @return bool True, if widget sidebar was found and called. False if not found or not called.

   807  */

   808 function dynamic_sidebar($index = 1) {

   809 	global $wp_registered_sidebars, $wp_registered_widgets;

   810 

   811 	if ( is_int($index) ) {

   812 		$index = "sidebar-$index";

   813 	} else {

   814 		$index = sanitize_title($index);

   815 		foreach ( (array) $wp_registered_sidebars as $key => $value ) {

   816 			if ( sanitize_title($value['name']) == $index ) {

   817 				$index = $key;

   818 				break;

   819 			}

   820 		}

   821 	}

   822 

   823 	$sidebars_widgets = wp_get_sidebars_widgets();

   824 

   825 	if ( empty($wp_registered_sidebars[$index]) || !array_key_exists($index, $sidebars_widgets) || !is_array($sidebars_widgets[$index]) || empty($sidebars_widgets[$index]) )

   826 		return false;

   827 

   828 	$sidebar = $wp_registered_sidebars[$index];

   829 

   830 	$did_one = false;

   831 	foreach ( (array) $sidebars_widgets[$index] as $id ) {

   832 

   833 		if ( !isset($wp_registered_widgets[$id]) ) continue;

   834 

   835 		$params = array_merge(

   836 			array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ),

   837 			(array) $wp_registered_widgets[$id]['params']

   838 		);

   839 

   840 		// Substitute HTML id and class attributes into before_widget

   841 		$classname_ = '';

   842 		foreach ( (array) $wp_registered_widgets[$id]['classname'] as $cn ) {

   843 			if ( is_string($cn) )

   844 				$classname_ .= '_' . $cn;

   845 			elseif ( is_object($cn) )

   846 				$classname_ .= '_' . get_class($cn);

   847 		}

   848 		$classname_ = ltrim($classname_, '_');

   849 		$params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);

   850 

   851 		$params = apply_filters( 'dynamic_sidebar_params', $params );

   852 

   853 		$callback = $wp_registered_widgets[$id]['callback'];

   854 

   855 		if ( is_callable($callback) ) {

   856 			call_user_func_array($callback, $params);

   857 			$did_one = true;

   858 		}

   859 	}

   860 

   861 	return $did_one;

   862 }

   863 

   864 /**

   865  * Whether widget is displayied on the front-end.

   866  *

   867  * Either $callback or $id_base can be used

   868  * $id_base is the first argument when extending WP_Widget class

   869  * Without the optional $widget_id parameter, returns the ID of the first sidebar

   870  * in which the first instance of the widget with the given callback or $id_base is found.

   871  * With the $widget_id parameter, returns the ID of the sidebar where

   872  * the widget with that callback/$id_base AND that ID is found.

   873  *

   874  * NOTE: $widget_id and $id_base are the same for single widgets. To be effective

   875  * this function has to run after widgets have initialized, at action 'init' or later.

   876  *

   877  * @since 2.2.0

   878  *

   879  * @param callback Optional, Widget callback to check.

   880  * @param int $widget_id Optional, but needed for checking. Widget ID.

   881  * @param string $id_base Optional, the base ID of a widget created by extending WP_Widget.

   882  * @param bool $skip_inactive Optional, whether to check in 'wp_inactive_widgets'.

   883  * @return mixed false if widget is not active or id of sidebar in which the widget is active.

   884  */

   885 function is_active_widget($callback = false, $widget_id = false, $id_base = false, $skip_inactive = true) {

   886 	global $wp_registered_widgets;

   887 

   888 	$sidebars_widgets = wp_get_sidebars_widgets();

   889 

   890 	if ( is_array($sidebars_widgets) ) {

   891 		foreach ( $sidebars_widgets as $sidebar => $widgets ) {

   892 			if ( $skip_inactive && 'wp_inactive_widgets' == $sidebar )

   893 				continue;

   894 

   895 			if ( is_array($widgets) ) {

   896 				foreach ( $widgets as $widget ) {

   897 					if ( ( $callback && isset($wp_registered_widgets[$widget]['callback']) && $wp_registered_widgets[$widget]['callback'] == $callback ) || ( $id_base && _get_widget_id_base($widget) == $id_base ) ) {

   898 						if ( !$widget_id || $widget_id == $wp_registered_widgets[$widget]['id'] )

   899 							return $sidebar;

   900 					}

   901 				}

   902 			}

   903 		}

   904 	}

   905 	return false;

   906 }

   907 

   908 /**

   909  * Whether the dynamic sidebar is enabled and used by theme.

   910  *

   911  * @since 2.2.0

   912  *

   913  * @return bool True, if using widgets. False, if not using widgets.

   914  */

   915 function is_dynamic_sidebar() {

   916 	global $wp_registered_widgets, $wp_registered_sidebars;

   917 	$sidebars_widgets = get_option('sidebars_widgets');

   918 	foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) {

   919 		if ( count($sidebars_widgets[$index]) ) {

   920 			foreach ( (array) $sidebars_widgets[$index] as $widget )

   921 				if ( array_key_exists($widget, $wp_registered_widgets) )

   922 					return true;

   923 		}

   924 	}

   925 	return false;

   926 }

   927 

   928 /**

   929  * Whether a sidebar is in use.

   930  *

   931  * @since 2.8

   932  *

   933  * @param mixed $index, sidebar name, id or number to check.

   934  * @return bool true if the sidebar is in use, false otherwise.

   935  */

   936 function is_active_sidebar( $index ) {

   937 	$index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);

   938 	$sidebars_widgets = wp_get_sidebars_widgets();

   939 	if ( isset($sidebars_widgets[$index]) && !empty($sidebars_widgets[$index]) )

   940 		return true;

   941 

   942 	return false;

   943 }

   944 

   945 /* Internal Functions */

   946 

   947 /**

   948  * Retrieve full list of sidebars and their widgets.

   949  *

   950  * Will upgrade sidebar widget list, if needed. Will also save updated list, if

   951  * needed.

   952  *

   953  * @since 2.2.0

   954  * @access private

   955  *

   956  * @param bool $update Optional, deprecated.

   957  * @return array Upgraded list of widgets to version 3 array format when called from the admin.

   958  */

   959 function wp_get_sidebars_widgets($deprecated = true) {

   960 	global $wp_registered_widgets, $wp_registered_sidebars, $_wp_sidebars_widgets;

   961 

   962 	// If loading from front page, consult $_wp_sidebars_widgets rather than options

   963 	// to see if wp_convert_widget_settings() has made manipulations in memory.

   964 	if ( !is_admin() ) {

   965 		if ( empty($_wp_sidebars_widgets) )

   966 			$_wp_sidebars_widgets = get_option('sidebars_widgets', array());

   967 

   968 		$sidebars_widgets = $_wp_sidebars_widgets;

   969 	} else {

   970 		$sidebars_widgets = get_option('sidebars_widgets', array());

   971 		$_sidebars_widgets = array();

   972 

   973 		if ( isset($sidebars_widgets['wp_inactive_widgets']) )

   974 			$sidebars_widgets['array_version'] = 3;

   975 		elseif ( !isset($sidebars_widgets['array_version']) )

   976 			$sidebars_widgets['array_version'] = 1;

   977 

   978 		switch ( $sidebars_widgets['array_version'] ) {

   979 			case 1 :

   980 				foreach ( (array) $sidebars_widgets as $index => $sidebar )

   981 				if ( is_array($sidebar) )

   982 				foreach ( (array) $sidebar as $i => $name ) {

   983 					$id = strtolower($name);

   984 					if ( isset($wp_registered_widgets[$id]) ) {

   985 						$_sidebars_widgets[$index][$i] = $id;

   986 						continue;

   987 					}

   988 					$id = sanitize_title($name);

   989 					if ( isset($wp_registered_widgets[$id]) ) {

   990 						$_sidebars_widgets[$index][$i] = $id;

   991 						continue;

   992 					}

   993 

   994 					$found = false;

   995 

   996 					foreach ( $wp_registered_widgets as $widget_id => $widget ) {

   997 						if ( strtolower($widget['name']) == strtolower($name) ) {

   998 							$_sidebars_widgets[$index][$i] = $widget['id'];

   999 							$found = true;

  1000 							break;

  1001 						} elseif ( sanitize_title($widget['name']) == sanitize_title($name) ) {

  1002 							$_sidebars_widgets[$index][$i] = $widget['id'];

  1003 							$found = true;

  1004 							break;

  1005 						}

  1006 					}

  1007 

  1008 					if ( $found )

  1009 						continue;

  1010 

  1011 					unset($_sidebars_widgets[$index][$i]);

  1012 				}

  1013 				$_sidebars_widgets['array_version'] = 2;

  1014 				$sidebars_widgets = $_sidebars_widgets;

  1015 				unset($_sidebars_widgets);

  1016 

  1017 			case 2 :

  1018 				$sidebars = array_keys( $wp_registered_sidebars );

  1019 				if ( !empty( $sidebars ) ) {

  1020 					// Move the known-good ones first

  1021 					foreach ( (array) $sidebars as $id ) {

  1022 						if ( array_key_exists( $id, $sidebars_widgets ) ) {

  1023 							$_sidebars_widgets[$id] = $sidebars_widgets[$id];

  1024 							unset($sidebars_widgets[$id], $sidebars[$id]);

  1025 						}

  1026 					}

  1027 

  1028 					// move the rest to wp_inactive_widgets

  1029 					if ( !isset($_sidebars_widgets['wp_inactive_widgets']) )

  1030 						$_sidebars_widgets['wp_inactive_widgets'] = array();

  1031 

  1032 					if ( !empty($sidebars_widgets) ) {

  1033 						foreach ( $sidebars_widgets as $lost => $val ) {

  1034 							if ( is_array($val) )

  1035 								$_sidebars_widgets['wp_inactive_widgets'] = array_merge( (array) $_sidebars_widgets['wp_inactive_widgets'], $val );

  1036 						}

  1037 					}

  1038 

  1039 					$sidebars_widgets = $_sidebars_widgets;

  1040 					unset($_sidebars_widgets);

  1041 				}

  1042 		}

  1043 	}

  1044 

  1045 	if ( isset($sidebars_widgets['array_version']) )

  1046 		unset($sidebars_widgets['array_version']);

  1047 

  1048 	$sidebars_widgets = apply_filters('sidebars_widgets', $sidebars_widgets);

  1049 	return $sidebars_widgets;

  1050 }

  1051 

  1052 /**

  1053  * Set the sidebar widget option to update sidebars.

  1054  *

  1055  * @since 2.2.0

  1056  * @access private

  1057  *

  1058  * @param array $sidebars_widgets Sidebar widgets and their settings.

  1059  */

  1060 function wp_set_sidebars_widgets( $sidebars_widgets ) {

  1061 	if ( !isset( $sidebars_widgets['array_version'] ) )

  1062 		$sidebars_widgets['array_version'] = 3;

  1063 	update_option( 'sidebars_widgets', $sidebars_widgets );

  1064 }

  1065 

  1066 /**

  1067  * Retrieve default registered sidebars list.

  1068  *

  1069  * @since 2.2.0

  1070  * @access private

  1071  *

  1072  * @return array

  1073  */

  1074 function wp_get_widget_defaults() {

  1075 	global $wp_registered_sidebars;

  1076 

  1077 	$defaults = array();

  1078 

  1079 	foreach ( (array) $wp_registered_sidebars as $index => $sidebar )

  1080 		$defaults[$index] = array();

  1081 

  1082 	return $defaults;

  1083 }

  1084 

  1085 /**

  1086  * Convert the widget settings from single to multi-widget format.

  1087  *

  1088  * @since 2.8.0

  1089  *

  1090  * @return array

  1091  */

  1092 function wp_convert_widget_settings($base_name, $option_name, $settings) {

  1093 	// This test may need expanding.

  1094 	$single = $changed = false;

  1095 	if ( empty($settings) ) {

  1096 		$single = true;

  1097 	} else {

  1098 		foreach ( array_keys($settings) as $number ) {

  1099 			if ( 'number' == $number )

  1100 				continue;

  1101 			if ( !is_numeric($number) ) {

  1102 				$single = true;

  1103 				break;

  1104 			}

  1105 		}

  1106 	}

  1107 

  1108 	if ( $single ) {

  1109 		$settings = array( 2 => $settings );

  1110 

  1111 		// If loading from the front page, update sidebar in memory but don't save to options

  1112 		if ( is_admin() ) {

  1113 			$sidebars_widgets = get_option('sidebars_widgets');

  1114 		} else {

  1115 			if ( empty($GLOBALS['_wp_sidebars_widgets']) )

  1116 				$GLOBALS['_wp_sidebars_widgets'] = get_option('sidebars_widgets', array());

  1117 			$sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets'];

  1118 		}

  1119 

  1120 		foreach ( (array) $sidebars_widgets as $index => $sidebar ) {

  1121 			if ( is_array($sidebar) ) {

  1122 				foreach ( $sidebar as $i => $name ) {

  1123 					if ( $base_name == $name ) {

  1124 						$sidebars_widgets[$index][$i] = "$name-2";

  1125 						$changed = true;

  1126 						break 2;

  1127 					}

  1128 				}

  1129 			}

  1130 		}

  1131 

  1132 		if ( is_admin() && $changed )

  1133 			update_option('sidebars_widgets', $sidebars_widgets);

  1134 	}

  1135