diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index 791fa165a..02cbf4206 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -1,15 +1,70 @@ 'name=whatever;id=whatever1' and for + * the array it would be array( + * 'name' => 'whatever', + * 'id' => 'whatever1'). + * + * name - The name of the sidebar, which presumably the title which will be + * displayed. + * id - The unique identifier by which the sidebar will be called by. + * before_widget - The content that will prepended to the widgets when they are + * displayed. + * after_widget - The content that will be appended to the widgets when they are + * displayed. + * before_title - The content that will be prepended to the title when displayed. + * after_title - the content that will be appended to the title when displayed. + * + * Content is assumed to be HTML and should be formatted as such, but + * doesn't have to be. + * + * @since 2.2.0 + * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID. + * @uses parse_str() Converts a string to an array to be used in the rest of the function. + * @usedby register_sidebars() + * + * @param string|array $args Builds Sidebar based off of 'name' and 'id' values + * @return string The sidebar id that was added. + */ function register_sidebar($args = array()) { global $wp_registered_sidebars; @@ -64,6 +153,15 @@ function register_sidebar($args = array()) { return $sidebar['id']; } +/** + * Removes a sidebar from the list. + * + * @since 2.2.0 + * + * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID. + * + * @param string $name The ID of the sidebar when it was added. + */ function unregister_sidebar( $name ) { global $wp_registered_sidebars; @@ -71,6 +169,18 @@ function unregister_sidebar( $name ) { unset( $wp_registered_sidebars[$name] ); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * @uses wp_register_sidebar_widget() Passes the compiled arguments. + * + * @param string $name + * @param callback $output_callback + * @param string $classname + */ function register_sidebar_widget($name, $output_callback, $classname = '') { // Compat if ( is_array($name) ) { @@ -92,6 +202,22 @@ function register_sidebar_widget($name, $output_callback, $classname = '') { call_user_func_array('wp_register_sidebar_widget', $args); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @uses $wp_registered_widgets {@internal Missing Description}} + * @uses $wp_register_widget_defaults {@internal Missing Description}} + * + * @param int $id {@internal Missing Description}} + * @param string $name {@internal Missing Description}} + * @param callback $output_callback {@internal Missing Description}} + * @param array|string $options {@internal Missing Description}} + * @return null Will return if $output_callback is empty + */ function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) { global $wp_registered_widgets; @@ -116,6 +242,16 @@ function wp_register_sidebar_widget($id, $name, $output_callback, $options = arr $wp_registered_widgets[$id] = $widget; } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.5.0 + * + * @param unknown_type $id + * @return unknown + */ function wp_widget_description( $id ) { if ( !is_scalar($id) ) return; @@ -126,15 +262,45 @@ function wp_widget_description( $id ) { return wp_specialchars( $wp_registered_widgets[$id]['description'] ); } +/** + * Alias of {@link wp_unregister_sidebar_widget()}. + * + * @see wp_unregister_sidebar_widget() + * + * @since 2.2.0 + * + * @param int $id Same as wp_unregister_sidebar_widget() + */ function unregister_sidebar_widget($id) { return wp_unregister_sidebar_widget($id); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param int $id {@internal Missing Description}} + */ function wp_unregister_sidebar_widget($id) { wp_register_sidebar_widget($id, '', ''); wp_unregister_widget_control($id); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param unknown_type $name {@internal Missing Description}} + * @param unknown_type $control_callback {@internal Missing Description}} + * @param unknown_type $width {@internal Missing Description}} + * @param unknown_type $height {@internal Missing Description}} + */ function register_widget_control($name, $control_callback, $width = '', $height = '') { // Compat if ( is_array($name) ) { @@ -164,6 +330,18 @@ function register_widget_control($name, $control_callback, $width = '', $height * id_base: for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided. * the widget id will ennd up looking like {$id_base}-{$unique_number} */ +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param int $id {@internal Missing Description}} + * @param string $name {@internal Missing Description}} + * @param callback $control_callback {@internal Missing Description}} + * @param array|string $options {@internal Missing Description}} + */ function wp_register_widget_control($id, $name, $control_callback, $options = array()) { global $wp_registered_widget_controls; @@ -193,14 +371,42 @@ function wp_register_widget_control($id, $name, $control_callback, $options = ar $wp_registered_widget_controls[$id] = $widget; } +/** + * Alias of {@link wp_unregister_widget_control()}. + * + * @since 2.2.0 + * @see wp_unregister_widget_control() + * + * @param int $id Widget ID + */ function unregister_widget_control($id) { return wp_unregister_widget_control($id); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * @uses wp_register_widget_control() {@internal Missing Description}} + * + * @param int $id {@internal Missing Description}} + */ function wp_unregister_widget_control($id) { return wp_register_widget_control($id, '', ''); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param unknown_type $index + * @return unknown + */ function dynamic_sidebar($index = 1) { global $wp_registered_sidebars, $wp_registered_widgets; @@ -254,6 +460,14 @@ function dynamic_sidebar($index = 1) { return $did_one; } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param unknown_type $callback /* @return mixed false if widget is not active or id of sidebar in which the widget is active */ function is_active_widget($callback, $widget_id = false) { @@ -271,6 +485,15 @@ function is_active_widget($callback, $widget_id = false) { return false; } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @return unknown + */ function is_dynamic_sidebar() { global $wp_registered_widgets, $wp_registered_sidebars; $sidebars_widgets = get_option('sidebars_widgets'); @@ -286,6 +509,17 @@ function is_dynamic_sidebar() { /* Internal Functions */ +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * @access private + * + * @param unknown_type $update + * @return unknown + */ function wp_get_sidebars_widgets($update = true) { global $wp_registered_widgets, $wp_registered_sidebars; @@ -364,10 +598,31 @@ function wp_get_sidebars_widgets($update = true) { return $sidebars_widgets; } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * @access private + * @uses update_option() + * + * @param unknown_type $sidebars_widgets + */ function wp_set_sidebars_widgets( $sidebars_widgets ) { update_option( 'sidebars_widgets', $sidebars_widgets ); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * @access private + * + * @return unknown + */ function wp_get_widget_defaults() { global $wp_registered_sidebars; @@ -381,6 +636,15 @@ function wp_get_widget_defaults() { /* Default Widgets */ +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param array $args Widget arguments. + */ function wp_widget_pages( $args ) { extract( $args ); $options = get_option( 'widget_pages' ); @@ -407,6 +671,13 @@ function wp_widget_pages( $args ) { } } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + */ function wp_widget_pages_control() { $options = $newoptions = get_option('widget_pages'); if ( $_POST['pages-submit'] ) { @@ -448,6 +719,15 @@ function wp_widget_pages_control() { @@ -1046,6 +1486,13 @@ function wp_widget_recent_comments_style() { 'widget_recent_comments', 'description' => __( 'The most recent comments' ) ); wp_register_sidebar_widget('recent-comments', __('Recent Comments'), 'wp_widget_recent_comments', $widget_ops); @@ -1055,6 +1502,16 @@ function wp_widget_recent_comments_register() { add_action('wp_head', 'wp_widget_recent_comments_style'); } +/** + * {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param unknown_type $args + * @param unknown_type $number + */ // See large comment section at end of this file function wp_widget_rss($args, $widget_args = 1) { extract($args, EXTR_SKIP); @@ -1190,6 +1647,15 @@ function wp_widget_rss_output( $rss, $args = array() ) { } } +/** + * wp_widget_rss_control() - {@internal Missing Short Description}} + * + * {@internal Missing Long Description}} + * + * @since 2.2.0 + * + * @param unknown_type $widget_args + */ function wp_widget_rss_control($widget_args) { global $wp_registered_widgets; static $updated = false; @@ -1384,7 +1850,7 @@ function wp_widget_rss_process( $widget_rss, $check_feed = true ) { /** * Register RSS widget to allow multiple RSS widgets. * - * @since unknown + * @since 2.2.0 */ function wp_widget_rss_register() { if ( !$options = get_option('widget_rss') ) @@ -1411,9 +1877,9 @@ function wp_widget_rss_register() { } /** - * Display tag cloud WordPress widget. + * Display tag cloud widget. * - * @since unknown + * @since 2.3.0 * * @param array $args Widget arguments. */ @@ -1433,7 +1899,7 @@ function wp_widget_tag_cloud($args) { * * Displays management form for changing the tag cloud widget title. * - * @since unknown + * @since 2.3.0 */ function wp_widget_tag_cloud_control() { $options = $newoptions = get_option('widget_tag_cloud'); @@ -1462,7 +1928,7 @@ function wp_widget_tag_cloud_control() { * Calls 'widgets_init' action after all of the WordPress widgets have been * registered. * - * @since unknown + * @since 2.2.0 */ function wp_widgets_init() { if ( !is_blog_installed() )