Changeset 27870

Timestamp:

03/31/2014 07:29:29 AM (11 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 );