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 		$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.

   465  *

   466  * @since 2.2.0

   467  *

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

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

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

   471  *	function to handle building the sidebar.

   472  *

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

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

   475  */

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

   477 	global $wp_registered_sidebars;

   478 	$number = (int) $number;

   479 

   480 	if ( is_string($args) )

   481 		parse_str($args, $args);

   482 

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

   484 		$_args = $args;

   485 

   486 		if ( $number > 1 ) {

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

   488 		} else {

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

   490 		}

   491 

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

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

   494 		} else {

   495 			$n = count($wp_registered_sidebars);

   496 			do {

   497 				$n++;

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

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

   500 		}

   501 

   502 		register_sidebar($_args);

   503 	}

   504 }

   505 

   506 /**

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

   508  *

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

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

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

   512  * for WordPress to create the defaults for you.

   513  *

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

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

   516  *    'name' => 'whatever',

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

   518  *

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

   520  *     displayed.

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

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

   523  *     displayed.

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

   525  *     displayed.

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

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

   528  *

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

   530  * doesn't have to be.

   531  *

   532  * @since 2.2.0

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

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

   535  * @usedby register_sidebars()

   536  *

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

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

   539  */

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

   541 	global $wp_registered_sidebars;

   542 

   543 	if ( is_string($args) )

   544 		parse_str($args, $args);

   545 

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

   547 

   548 	$defaults = array(

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

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

   551 		'description' => '',

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

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

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

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

   556 	);

   557 

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

   559 

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

   561 

   562 	return $sidebar['id'];

   563 }

   564 

   565 /**

   566  * Removes a sidebar from the list.

   567  *

   568  * @since 2.2.0

   569  *

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

   571  *

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

   573  */

   574 function unregister_sidebar( $name ) {

   575 	global $wp_registered_sidebars;

   576 

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

   578 		unset( $wp_registered_sidebars[$name] );

   579 }

   580 

   581 /**

   582  * Register widget for use in sidebars.

   583  *

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

   585  *

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

   587  * parameter is an empty string.

   588  *

   589  * @since 2.2.0

   590  *

   591  * @uses $wp_registered_widgets Uses stored registered widgets.

   592  * @uses $wp_register_widget_defaults Retrieves widget defaults.

   593  *

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

   595  * @param string $name Widget display title.

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

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

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

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

   600  */

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

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

   603 

   604 	$id = strtolower($id);

   605 

   606 	if ( empty($output_callback) ) {

   607 		unset($wp_registered_widgets[$id]);

   608 		return;

   609 	}

   610 

   611 	$id_base = _get_widget_id_base($id);

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

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

   614 			unset($wp_registered_widget_controls[$id]);

   615 

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

   617 			unset($wp_registered_widget_updates[$id_base]);

   618 

   619 		return;

   620 	}

   621 

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

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

   624 	$widget = array(

   625 		'name' => $name,

   626 		'id' => $id,

   627 		'callback' => $output_callback,

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

   629 	);

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

   631 

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

   633 		$wp_registered_widgets[$id] = $widget;

   634 }

   635 

   636 /**

   637  * Retrieve description for widget.

   638  *

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

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

   641  * in the theme.

   642  *

   643  * @since 2.5.0

   644  *

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

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

   647  */

   648 function wp_widget_description( $id ) {

   649 	if ( !is_scalar($id) )

   650 		return;

   651 

   652 	global $wp_registered_widgets;

   653 

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

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

   656 }

   657 

   658 /**

   659  * Retrieve description for a sidebar.

   660  *

   661  * When registering sidebars a 'description' parameter can be included that

   662  * describes the sidebar for display on the widget administration panel.

   663  *

   664  * @since 2.9.0

   665  *

   666  * @param int|string $id sidebar ID.

   667  * @return string Sidebar description, if available. Null on failure to retrieve description.

   668  */

   669 function wp_sidebar_description( $id ) {

   670 	if ( !is_scalar($id) )

   671 		return;

   672 

   673 	global $wp_registered_sidebars;

   674 

   675 	if ( isset($wp_registered_sidebars[$id]['description']) )

   676 		return esc_html( $wp_registered_sidebars[$id]['description'] );

   677 }

   678 

   679 

   680 /**

   681  * Remove widget from sidebar.

   682  *

   683  * @since 2.2.0

   684  *

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

   686  */

   687 function wp_unregister_sidebar_widget($id) {

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

   689 	wp_unregister_widget_control($id);

   690 }

   691 

   692 /**

   693  * Registers widget control callback for customizing options.

   694  *

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

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

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

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

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

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

   701  *

   702  * @since 2.2.0

   703  *

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

   705  * @param string $name Sidebar display name.

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

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

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

   709  */

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

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

   712 

   713 	$id = strtolower($id);

   714 	$id_base = _get_widget_id_base($id);

   715 

   716 	if ( empty($control_callback) ) {

   717 		unset($wp_registered_widget_controls[$id]);

   718 		unset($wp_registered_widget_updates[$id_base]);

   719 		return;

   720 	}

   721 

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

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

   724 			unset($wp_registered_widgets[$id]);

   725 

   726 		return;

   727 	}

   728 

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

   730 		return;

   731 

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

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

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

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

   736 

   737 	$widget = array(

   738 		'name' => $name,

   739 		'id' => $id,

   740 		'callback' => $control_callback,

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

   742 	);

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

   744 

   745 	$wp_registered_widget_controls[$id] = $widget;

   746 

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

   748 		return;

   749 

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

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

   752 

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

   754 	$wp_registered_widget_updates[$id_base] = $widget;

   755 }

   756 

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

   758 	global $wp_registered_widget_updates;

   759 

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

   761 		if ( empty($update_callback) )

   762 			unset($wp_registered_widget_updates[$id_base]);

   763 		return;

   764 	}

   765 

   766 	$widget = array(

   767 		'callback' => $update_callback,

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

   769 	);

   770 

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

   772 	$wp_registered_widget_updates[$id_base] = $widget;

   773 }

   774 

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

   776 	global $wp_registered_widget_controls;

   777 

   778 	$id = strtolower($id);

   779 

   780 	if ( empty($form_callback) ) {

   781 		unset($wp_registered_widget_controls[$id]);

   782 		return;

   783 	}

   784 

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

   786 		return;

   787 

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

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

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

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

   792 

   793 	$widget = array(

   794 		'name' => $name,

   795 		'id' => $id,

   796 		'callback' => $form_callback,

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

   798 	);

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

   800 

   801 	$wp_registered_widget_controls[$id] = $widget;

   802 }

   803 

   804 /**

   805  * Remove control callback for widget.

   806  *

   807  * @since 2.2.0

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

   809  *

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

   811  */

   812 function wp_unregister_widget_control($id) {

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

   814 }

   815 

   816 /**

   817  * Display dynamic sidebar.

   818  *

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

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

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

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

   823  * for 'sidebar-after-post'.

   824  *

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

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

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

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

   829  *

   830  * @since 2.2.0

   831  *

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

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

   834  */

   835 function dynamic_sidebar($index = 1) {

   836 	global $wp_registered_sidebars, $wp_registered_widgets;

   837 

   838 	if ( is_int($index) ) {

   839 		$index = "sidebar-$index";

   840 	} else {

   841 		$index = sanitize_title($index);

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

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

   844 				$index = $key;

   845 				break;

   846 			}

   847 		}

   848 	}

   849 

   850 	$sidebars_widgets = wp_get_sidebars_widgets();

   851 

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

   853 		return false;

   854 

   855 	$sidebar = $wp_registered_sidebars[$index];

   856 

   857 	$did_one = false;

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

   859 

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

   861 

   862 		$params = array_merge(

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

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

   865 		);

   866 

   867 		// Substitute HTML id and class attributes into before_widget

   868 		$classname_ = '';

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

   870 			if ( is_string($cn) )

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

   872 			elseif ( is_object($cn) )

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

   874 		}

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

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

   877 

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

   879 

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

   881 

   882 		if ( is_callable($callback) ) {

   883 			call_user_func_array($callback, $params);

   884 			$did_one = true;

   885 		}

   886 	}

   887 

   888 	return $did_one;

   889 }

   890 

   891 /**

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

   893  *

   894  * Either $callback or $id_base can be used

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

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

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

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

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

   900  *

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

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

   903  *

   904  * @since 2.2.0

   905  *

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

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

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

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

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

   911  */

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

   913 	global $wp_registered_widgets;

   914 

   915 	$sidebars_widgets = wp_get_sidebars_widgets();

   916 

   917 	if ( is_array($sidebars_widgets) ) {

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

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

   920 				continue;

   921 

   922 			if ( is_array($widgets) ) {

   923 				foreach ( $widgets as $widget ) {

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

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

   926 							return $sidebar;

   927 					}

   928 				}

   929 			}

   930 		}

   931 	}

   932 	return false;

   933 }

   934 

   935 /**

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

   937  *

   938  * @since 2.2.0

   939  *

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

   941  */

   942 function is_dynamic_sidebar() {

   943 	global $wp_registered_widgets, $wp_registered_sidebars;

   944 	$sidebars_widgets = get_option('sidebars_widgets');

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

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

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

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

   949 					return true;

   950 		}

   951 	}

   952 	return false;

   953 }

   954 

   955 /**

   956  * Whether a sidebar is in use.

   957  *

   958  * @since 2.8

   959  *

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

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

   962  */

   963 function is_active_sidebar( $index ) {

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

   965 	$sidebars_widgets = wp_get_sidebars_widgets();

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

   967 		return true;

   968 

   969 	return false;

   970 }

   971 

   972 /* Internal Functions */

   973 

   974 /**

   975  * Retrieve full list of sidebars and their widgets.

   976  *

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

   978  * needed.

   979  *

   980  * @since 2.2.0

   981  * @access private

   982  *

   983  * @param bool $update Optional, deprecated.

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

   985  */

   986 function wp_get_sidebars_widgets($deprecated = true) {

   987 	global $wp_registered_widgets, $wp_registered_sidebars, $_wp_sidebars_widgets;

   988 

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

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

   991 	if ( !is_admin() ) {

   992 		if ( empty($_wp_sidebars_widgets) )

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

   994 

   995 		$sidebars_widgets = $_wp_sidebars_widgets;

   996 	} else {

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

   998 		$_sidebars_widgets = array();

   999 

  1000 		if ( isset($sidebars_widgets['wp_inactive_widgets']) || empty($sidebars_widgets) )

  1001 			$sidebars_widgets['array_version'] = 3;

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

  1003 			$sidebars_widgets['array_version'] = 1;

  1004 

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

  1006 			case 1 :

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

  1008 				if ( is_array($sidebar) )

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

  1010 					$id = strtolower($name);

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

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

  1013 						continue;

  1014 					}

  1015 					$id = sanitize_title($name);

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

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

  1018 						continue;

  1019 					}

  1020 

  1021 					$found = false;

  1022 

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

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

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

  1026 							$found = true;

  1027 							break;

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

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

  1030 							$found = true;

  1031 							break;

  1032 						}

  1033 					}

  1034 

  1035 					if ( $found )

  1036 						continue;

  1037 

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

  1039 				}

  1040 				$_sidebars_widgets['array_version'] = 2;

  1041 				$sidebars_widgets = $_sidebars_widgets;

  1042 				unset($_sidebars_widgets);

  1043 

  1044 			case 2 :

  1045 				$sidebars = array_keys( $wp_registered_sidebars );

  1046 				if ( !empty( $sidebars ) ) {

  1047 					// Move the known-good ones first

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

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

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

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

  1052 						}

  1053 					}

  1054 

  1055 					// move the rest to wp_inactive_widgets

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

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

  1058 

  1059 					if ( !empty($sidebars_widgets) ) {

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

  1061 							if ( is_array($val) )

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

  1063 						}

  1064 					}

  1065 

  1066 					$sidebars_widgets = $_sidebars_widgets;

  1067 					unset($_sidebars_widgets);

  1068 				}

  1069 		}

  1070 	}

  1071 

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

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

  1074 

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

  1076 	return $sidebars_widgets;

  1077 }

  1078 

  1079 /**

  1080  * Set the sidebar widget option to update sidebars.

  1081  *

  1082  * @since 2.2.0

  1083  * @access private

  1084  *

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

  1086  */

  1087 function wp_set_sidebars_widgets( $sidebars_widgets ) {

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

  1089 		$sidebars_widgets['array_version'] = 3;

  1090 	update_option( 'sidebars_widgets', $sidebars_widgets );

  1091 }

  1092 

  1093 /**

  1094  * Retrieve default registered sidebars list.

  1095  *

  1096  * @since 2.2.0

  1097  * @access private

  1098  *

  1099  * @return array

  1100  */

  1101 function wp_get_widget_defaults() {

  1102 	global $wp_registered_sidebars;

  1103 

  1104 	$defaults = array();

  1105 

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

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

  1108 

  1109 	return $defaults;

  1110 }

  1111 

  1112 /**

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

  1114  *

  1115  * @since 2.8.0

  1116  *

  1117  * @return array

  1118  */

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

  1120 	// This test may need expanding.

  1121 	$single = $changed = false;

  1122 	if ( empty($settings) ) {

  1123 		$single = true;

  1124 	} else {

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

  1126 			if ( 'number' == $number )

  1127 				continue;

  1128 			if ( !is_numeric($number) ) {

  1129 				$single = true;

  1130 				break;

  1131 			}

  1132 		}

  1133 	}

  1134 

  1135 	if ( $single ) {