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 	 * PHP5 constructor

    75 	 *

    76 	 * @param string $id_base Optional Base ID for the widget, lower case,

    77 	 * if left empty a portion of the widget's class name will be used. Has to be unique.

    78 	 * @param string $name Name for the widget displayed on the configuration page.

    79 	 * @param array $widget_options Optional Passed to wp_register_sidebar_widget()

    80 	 *	 - description: shown on the configuration page

    81 	 *	 - classname

    82 	 * @param array $control_options Optional Passed to wp_register_widget_control()

    83 	 *	 - width: required if more than 250px

    84 	 *	 - height: currently not used but may be needed in the future

    85 	 */

    86 	function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {

    87 		$this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);

    88 		$this->name = $name;

    89 		$this->option_name = 'widget_' . $this->id_base;

    90 		$this->widget_options = wp_parse_args( $widget_options, array('classname' => $this->option_name) );

    91 		$this->control_options = wp_parse_args( $control_options, array('id_base' => $this->id_base) );

    92 	}

    93 

    94 	/**

    95 	 * PHP4 constructor

    96 	 */

    97 	function WP_Widget( $id_base, $name, $widget_options = array(), $control_options = array() ) {

    98 		WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );

    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 existence 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 ( !empty($settings) && !array_key_exists('_multiwidget', $settings) ) {

   300 			// old format, convert 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  $GLOBALS['_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 multiple

   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  * Accepts either a string or an array and then parses that against a set

   513  * of default arguments for the new sidebar. WordPress will automatically

   514  * generate a sidebar ID and name based on the current number of registered

   515  * sidebars if those arguments are not included.

   516  *

   517  * When allowing for automatic generation of the name and ID parameters, keep

   518  * in mind that the incrementor for your sidebar can change over time depending

   519  * on what other plugins and themes are installed.

   520  *

   521  * If theme support for 'widgets' has not yet been added when this function is

   522  * called, it will be automatically enabled through the use of add_theme_support()

   523  *

   524  * Arguments passed as a string should be separated by '&':

   525  *

   526  *     e.g. 'name=Sidebar&id=my_prefix_sidebar'

   527  *

   528  * The same arguments passed as an array:

   529  *

   530  *     array(

   531  *         'name' => 'Sidebar',

   532  *         'id'   => 'my_prefix_sidebar',

   533  *     )

   534  *

   535  * Arguments:

   536  *     name          - The name or title of the sidebar displayed in the admin dashboard.

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

   538  *     before_widget - HTML content that will be prepended to each widget's HTML output

   539  *                     when assigned to this sidebar.

   540  *     after_widget  - HTML content that will be appended to each widget's HTML output

   541  *                     when assigned to this sidebar.

   542  *     before_title  - HTML content that will be prepended to the sidebar title when displayed.

   543  *     after_title   - HTML content that will be appended to the sidebar title when displayed.

   544  *

   545  * @since 2.2.0

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

   547  * @uses add_theme_support() to ensure widget support has been added.

   548  *

   549  * @param string|array $args Arguments for the sidebar being registered.

   550  * @return string Sidebar ID added to $wp_registered_sidebars global.

   551  */

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

   553 	global $wp_registered_sidebars;

   554 

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

   556 

   557 	$defaults = array(

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

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

   560 		'description' => '',

   561 		'class' => '',

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

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

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

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

   566 	);

   567 

   568 	$sidebar = wp_parse_args( $args, $defaults );

   569 

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

   571 

   572 	add_theme_support('widgets');

   573 

   574 	do_action( 'register_sidebar', $sidebar );

   575 

   576 	return $sidebar['id'];

   577 }

   578 

   579 /**

   580  * Removes a sidebar from the list.

   581  *

   582  * @since 2.2.0

   583  *

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

   585  *

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

   587  */

   588 function unregister_sidebar( $name ) {

   589 	global $wp_registered_sidebars;

   590 

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

   592 		unset( $wp_registered_sidebars[$name] );

   593 }

   594 

   595 /**

   596  * Register widget for use in sidebars.

   597  *

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

   599  *

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

   601  * parameter is an empty string.

   602  *

   603  * @since 2.2.0

   604  *

   605  * @uses $wp_registered_widgets Uses stored registered widgets.

   606  * @uses $wp_register_widget_defaults Retrieves widget defaults.

   607  *

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

   609  * @param string $name Widget display title.

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

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

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

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

   614  */

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

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

   617 

   618 	$id = strtolower($id);

   619 

   620 	if ( empty($output_callback) ) {

   621 		unset($wp_registered_widgets[$id]);

   622 		return;

   623 	}

   624 

   625 	$id_base = _get_widget_id_base($id);

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

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

   628 			unset($wp_registered_widget_controls[$id]);

   629 

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

   631 			unset($wp_registered_widget_updates[$id_base]);

   632 

   633 		return;

   634 	}

   635 

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

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

   638 	$widget = array(

   639 		'name' => $name,

   640 		'id' => $id,

   641 		'callback' => $output_callback,

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

   643 	);

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

   645 

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

   647 		do_action( 'wp_register_sidebar_widget', $widget );

   648 		$wp_registered_widgets[$id] = $widget;

   649 	}

   650 }

   651 

   652 /**

   653  * Retrieve description for widget.

   654  *

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

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

   657  * in the theme.

   658  *

   659  * @since 2.5.0

   660  *

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

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

   663  */

   664 function wp_widget_description( $id ) {

   665 	if ( !is_scalar($id) )

   666 		return;

   667 

   668 	global $wp_registered_widgets;

   669 

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

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

   672 }

   673 

   674 /**

   675  * Retrieve description for a sidebar.

   676  *

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

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

   679  *

   680  * @since 2.9.0

   681  *

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

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

   684  */

   685 function wp_sidebar_description( $id ) {

   686 	if ( !is_scalar($id) )

   687 		return;

   688 

   689 	global $wp_registered_sidebars;

   690 

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

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

   693 }

   694 

   695 /**

   696  * Remove widget from sidebar.

   697  *

   698  * @since 2.2.0

   699  *

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

   701  */

   702 function wp_unregister_sidebar_widget($id) {

   703 	do_action( 'wp_unregister_sidebar_widget', $id );

   704 

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

   706 	wp_unregister_widget_control($id);

   707 }

   708 

   709 /**

   710  * Registers widget control callback for customizing options.

   711  *

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

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

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

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

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

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

   718  *

   719  * @since 2.2.0

   720  *

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

   722  * @param string $name Sidebar display name.

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

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

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

   726  */

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

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

   729 

   730 	$id = strtolower($id);

   731 	$id_base = _get_widget_id_base($id);

   732 

   733 	if ( empty($control_callback) ) {

   734 		unset($wp_registered_widget_controls[$id]);

   735 		unset($wp_registered_widget_updates[$id_base]);

   736 		return;

   737 	}

   738 

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

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

   741 			unset($wp_registered_widgets[$id]);

   742 

   743 		return;

   744 	}

   745 

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

   747 		return;

   748 

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

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

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

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

   753 

   754 	$widget = array(

   755 		'name' => $name,

   756 		'id' => $id,

   757 		'callback' => $control_callback,

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

   759 	);

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

   761 

   762 	$wp_registered_widget_controls[$id] = $widget;

   763 

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

   765 		return;

   766 

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

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

   769 

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

   771 	$wp_registered_widget_updates[$id_base] = $widget;

   772 }

   773 

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

   775 	global $wp_registered_widget_updates;

   776 

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

   778 		if ( empty($update_callback) )

   779 			unset($wp_registered_widget_updates[$id_base]);

   780 		return;

   781 	}

   782 

   783 	$widget = array(

   784 		'callback' => $update_callback,

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

   786 	);

   787 

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

   789 	$wp_registered_widget_updates[$id_base] = $widget;

   790 }

   791 

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

   793 	global $wp_registered_widget_controls;

   794 

   795 	$id = strtolower($id);

   796 

   797 	if ( empty($form_callback) ) {

   798 		unset($wp_registered_widget_controls[$id]);

   799 		return;

   800 	}

   801 

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

   803 		return;

   804 

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

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

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

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

   809 

   810 	$widget = array(

   811 		'name' => $name,

   812 		'id' => $id,

   813 		'callback' => $form_callback,

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

   815 	);

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

   817 

   818 	$wp_registered_widget_controls[$id] = $widget;

   819 }

   820 

   821 /**

   822  * Remove control callback for widget.

   823  *

   824  * @since 2.2.0

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

   826  *

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

   828  */

   829 function wp_unregister_widget_control($id) {

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

   831 }

   832 

   833 /**

   834  * Display dynamic sidebar.

   835  *

   836  * By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or

   837  * 'name' parameter for its registered sidebars you can pass an id or name as the $index parameter.

   838  * Otherwise, you can pass in a numerical index to display the sidebar at that index.

   839  *

   840  * @since 2.2.0

   841  *

   842  * @param int|string $index Optional, default is 1. Index, name or ID of dynamic sidebar.

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

   844  */

   845 function dynamic_sidebar($index = 1) {

   846 	global $wp_registered_sidebars, $wp_registered_widgets;

   847 

   848 	if ( is_int($index) ) {

   849 		$index = "sidebar-$index";

   850 	} else {

   851 		$index = sanitize_title($index);

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

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

   854 				$index = $key;

   855 				break;

   856 			}

   857 		}

   858 	}

   859 

   860 	$sidebars_widgets = wp_get_sidebars_widgets();

   861 	if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {

   862 		return false;

   863 	}

   864 

   865 	$sidebar = $wp_registered_sidebars[$index];

   866 

   867 	$did_one = false;

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

   869 

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

   871 

   872 		$params = array_merge(

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

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

   875 		);

   876 

   877 		// Substitute HTML id and class attributes into before_widget

   878 		$classname_ = '';

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

   880 			if ( is_string($cn) )

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

   882 			elseif ( is_object($cn) )

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

   884 		}

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

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

   887 

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

   889 

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

   891 

   892 		do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );

   893 

   894 		if ( is_callable($callback) ) {

   895 			call_user_func_array($callback, $params);

   896 			$did_one = true;

   897 		}

   898 	}

   899 

   900 	return $did_one;

   901 }

   902 

   903 /**

   904  * Whether widget is displayed on the front-end.

   905  *

   906  * Either $callback or $id_base can be used

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

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

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

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

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

   912  *

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

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

   915  *

   916  * @since 2.2.0

   917  *

   918  * @param string $callback Optional, Widget callback to check.

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

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

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

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

   923  */

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

   925 	global $wp_registered_widgets;

   926 

   927 	$sidebars_widgets = wp_get_sidebars_widgets();

   928 

   929 	if ( is_array($sidebars_widgets) ) {

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

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

   932 				continue;

   933 

   934 			if ( is_array($widgets) ) {

   935 				foreach ( $widgets as $widget ) {

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

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

   938 							return $sidebar;

   939 					}

   940 				}

   941 			}

   942 		}

   943 	}

   944 	return false;

   945 }

   946 

   947 /**

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

   949  *

   950  * @since 2.2.0

   951  *

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

   953  */

   954 function is_dynamic_sidebar() {

   955 	global $wp_registered_widgets, $wp_registered_sidebars;

   956 	$sidebars_widgets = get_option('sidebars_widgets');

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

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

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

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

   961 					return true;

   962 		}

   963 	}

   964 	return false;

   965 }

   966 

   967 /**

   968  * Whether a sidebar is in use.

   969  *

   970  * @since 2.8

   971  *

   972  * @param mixed $index Sidebar name, id or number to check.

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

   974  */

   975 function is_active_sidebar( $index ) {

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

   977 	$sidebars_widgets = wp_get_sidebars_widgets();

   978 	$is_active_sidebar = ! empty( $sidebars_widgets[$index] );

   979 	return $is_active_sidebar;

   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_sidebars_widgets, $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 	}

  1012 

  1013 	if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) )

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

  1015 

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

  1017 	return $sidebars_widgets;

  1018 }

  1019 

  1020 /**

  1021  * Set the sidebar widget option to update sidebars.

  1022  *

  1023  * @since 2.2.0

  1024  * @access private

  1025  *

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

  1027  */

  1028 function wp_set_sidebars_widgets( $sidebars_widgets ) {

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

  1030 		$sidebars_widgets['array_version'] = 3;

  1031 	update_option( 'sidebars_widgets', $sidebars_widgets );

  1032 }

  1033 

  1034 /**

  1035  * Retrieve default registered sidebars list.

  1036  *

  1037  * @since 2.2.0

  1038  * @access private

  1039  *

  1040  * @return array

  1041  */

  1042 function wp_get_widget_defaults() {

  1043 	global $wp_registered_sidebars;

  1044 

  1045 	$defaults = array();

  1046 

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

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

  1049 

  1050 	return $defaults;

  1051 }

  1052 

  1053 /**

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

  1055  *

  1056  * @since 2.8.0

  1057  *

  1058  * @return array

  1059  */

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

  1061 	// This test may need expanding.

  1062 	$single = $changed = false;

  1063 	if ( empty($settings) ) {

  1064 		$single = true;

  1065 	} else {

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

  1067 			if ( 'number' == $number )

  1068 				continue;

  1069 			if ( !is_numeric($number) ) {

  1070 				$single = true;

  1071 				break;

  1072 			}

  1073 		}

  1074 	}

  1075 

  1076 	if ( $single ) {

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

  1078 

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

  1080 		if ( is_admin() ) {

  1081 			$sidebars_widgets = get_option('sidebars_widgets');

  1082 		} else {

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

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

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

  1086 		}

  1087 

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

  1089 			if ( is_array($sidebar) ) {

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

  1091 					if ( $base_name == $name ) {

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

  1093 						$changed = true;

  1094 						break 2;

  1095 					}

  1096 				}

  1097 			}

  1098 		}

  1099 

  1100 		if ( is_admin() && $changed )

  1101 			update_option('sidebars_widgets', $sidebars_widgets);

  1102 	}

  1103 

  1104 	$settings['_multiwidget'] = 1;

  1105 	if ( is_admin() )

  1106 		update_option( $option_name, $settings );

  1107 

  1108 	return $settings;

  1109 }

  1110 

  1111 /**

  1112  * Output an arbitrary widget as a template tag

  1113  *

  1114  * @since 2.8

  1115  *

  1116  * @param string $widget the widget's PHP class name (see default-widgets.php)

  1117  * @param array $instance the widget's instance settings

  1118  * @param array $args the widget's sidebar args

  1119  * @return void

  1120  **/

  1121 function the_widget($widget, $instance = array(), $args = array()) {

  1122 	global $wp_widget_factory;

  1123 

  1124 	$widget_obj = $wp_widget_factory->widgets[$widget];

  1125 	if ( !is_a($widget_obj, 'WP_Widget') )

  1126 		return;

  1127 

  1128 	$before_widget = sprintf('<div class="widget %s">', $widget_obj->widget_options['classname'] );

  1129 	$default_args = array( 'before_widget' => $before_widget, 'after_widget' => "</div>", 'before_title' => '<h2 class="widgettitle">', 'after_title' => '</h2>' );

  1130 

  1131 	$args = wp_parse_args($args, $default_args);

  1132 	$instance = wp_parse_args($instance);

  1133 

  1134 	do_action( 'the_widget', $widget, $instance, $args );

  1135