Changeset 27870 for trunk/src/wp-includes/widgets.php

Timestamp:

03/31/2014 07:29:29 AM (12 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-includes/widgets.php.

Props eliorivero and Nessworthy for the initial patches. Props kpdesign.
Fixes #27129.

File:

• trunk/src/wp-includes/widgets.php (modified) (10 diffs)

trunk/src/wp-includes/widgets.php

@@ -177 +177 @@
                 if ( array_key_exists( $this->number, $instance ) ) {
                         $instance = $instance[$this->number];
-                        // filters the widget's settings, return false to stop displaying the widget
-                        $instance = apply_filters('widget_display_callback', $instance, $this, $args);
+
+                        /**
+                         * Filter the settings for a particular widget instance.
+                         *
+                         * Returning false will effectively short-circuit display of the widget.
+                         *
+                         * @since 2.8.0
+                         *
+                         * @param array     $instance The current widget instance's settings.
+                         * @param WP_Widget $this     The current widget instance.
+                         * @param array     $args     An array of default widget arguments.
+                         */
+                        $instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
                         if ( false !== $instance )
                                 $this->widget($args, $instance);
@@ -233 +244 @@
                                 $instance = $this->update($new_instance, $old_instance);
 
-                                // filters the widget's settings before saving, return false to cancel saving (keep the old settings if updating)
-                                $instance = apply_filters('widget_update_callback', $instance, $new_instance, $old_instance, $this);
+                                /**
+                                 * Filter a widget's settings before saving.
+                                 *
+                                 * Returning false will effectively short-circuit the widget's ability
+                                 * to update settings.
+                                 *
+                                 * @since 2.8.0
+                                 *
+                                 * @param array     $instance     The current widget instance's settings.
+                                 * @param array     $new_instance Array of new widget settings.
+                                 * @param array     $old_instance Array of old widget settings.
+                                 * @param WP_Widget $this         The current widget instance.
+                                 */
+                                $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
                                 if ( false !== $instance )
                                         $all_instances[$number] = $instance;
@@ -246 +269 @@
         }
 
-        /** Generate the control form.
-         *      Do NOT over-ride this function. */
+        /**
+         * Generate the control form.
+         *
+         * Do NOT over-ride this function.
+         */
         function form_callback( $widget_args = 1 ) {
                 if ( is_numeric($widget_args) )
@@ -264 +290 @@
                 }
 
-                // filters the widget admin form before displaying, return false to stop displaying it
-                $instance = apply_filters('widget_form_callback', $instance, $this);
+                /**
+                 * Filter the widget instance's settings before displaying the control form.
+                 *
+                 * Returning false effectively short-circuits display of the control form.
+                 *
+                 * @since 2.8.0
+                 *
+                 * @param array     $instance The current widget instance's settings.
+                 * @param WP_Widget $this     The current widget instance.
+                 */
+                $instance = apply_filters( 'widget_form_callback', $instance, $this );
 
                 $return = null;
                 if ( false !== $instance ) {
                         $return = $this->form($instance);
-                        // add extra fields in the widget form - be sure to set $return to null if you add any
-                        // if the widget has no form the text echoed from the default form method can be hidden using css
-                        do_action_ref_array( 'in_widget_form', array(&$this, &$return, $instance) );
+
+                        /**
+                         * Fires at the end of the widget control form.
+                         *
+                         * Use this hook to add extra fields to the widget form. The hook
+                         * is only fired if the value passed to the 'widget_form_callback'
+                         * hook is not false.
+                         *
+                         * Note: If the widget has no form, the text echoed from the default
+                         * form method can be hidden using CSS.
+                         *
+                         * @since 2.8.0
+                         *
+                         * @param WP_Widget $this     The widget instance, passed by reference.
+                         * @param null      $return   Return null if new fields are added.
+                         * @param array     $instance An array of the widget's settings.
+                         */
+                        do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
                 }
                 return $return;
@@ -573 +623 @@
         add_theme_support('widgets');
 
+        /**
+         * Fires once a sidebar has been registered.
+         *
+         * @since 3.0.0
+         *
+         * @param array $sidebar Parsed arguments for the registered sidebar.
+         */
         do_action( 'register_sidebar', $sidebar );
 
@@ -646 +703 @@
 
         if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) {
+
+                /**
+                 * Fires once for each registered widget.
+                 *
+                 * @since 3.0.0
+                 *
+                 * @param array $widget An array of default widget arguments.
+                 */
                 do_action( 'wp_register_sidebar_widget', $widget );
                 $wp_registered_widgets[$id] = $widget;
@@ -702 +767 @@
  */
 function wp_unregister_sidebar_widget($id) {
+
+        /**
+         * Fires just before a widget is removed from a sidebar.
+         *
+         * @since 3.0.0
+         *
+         * @param int $id The widget ID.
+         */
         do_action( 'wp_unregister_sidebar_widget', $id );
 
@@ -1129 +1202 @@
                 unset($sidebars_widgets['array_version']);
 
-        $sidebars_widgets = apply_filters('sidebars_widgets', $sidebars_widgets);
+        /**
+         * Filter the list of sidebars and their widgets.
+         *
+         * @since 2.7.0
+         *
+         * @param array $sidebars_widgets An associative array of sidebars and their widgets.
+         */
+        $sidebars_widgets = apply_filters( 'sidebars_widgets', $sidebars_widgets );
         return $sidebars_widgets;
 }
@@ -1225 +1305 @@
 
 /**
- * Output an arbitrary widget as a template tag
+ * Output an arbitrary widget as a template tag.
  *
  * @since 2.8.0
@@ -1247 +1327 @@
         $instance = wp_parse_args($instance);
 
+        /**
+         * Fires before rendering the requested widget.
+         *
+         * @since 3.0.0
+         *
+         * @param string $widget   The widget's class name.
+         * @param array  $instance The current widget instance's settings.
+         * @param array  $args     An array of the widget's sidebar arguments.
+         */
         do_action( 'the_widget', $widget, $instance, $args );