WordPress.org
Get WordPress

Make WordPress Core

Changeset 27903


Ignore:
Timestamp:
04/02/2014 05:44:54 AM (9 years ago)
Author:
DrewAPicture
Message:

Second-pass inline documentation improvements for WP_Customize_Widgets.

See #27534.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r27860 r27903  
    1010 */
    1111final class WP_Customize_Widgets {
    12     /**
     12
     13    /**
     14     * WP_Customize_Manager instance.
     15     *
     16     * @since 3.9.0
    1317     * @access public
    1418     * @var WP_Customize_Manager
    … …  
    1721
    1822    /**
    19      * All id_bases for widgets defined in core
     23     * All id_bases for widgets defined in core.
    2024     *
    2125     * @since 3.9.0
    … …  
    7276     * @since 3.9.0
    7377     * @access public
     78     *
     79     * @param WP_Customize_Manager $manager Customize manager bootstrap instance.
    7480     */
    7581    public function __construct( WP_Customize_Manager $manager ) {
    … …  
    108114
    109115    /**
    110      *
    111      *
    112      * Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register),
    113      * we have to filter the options similarly to how the setting previewer will filter the options later.
    114      *
    115      * @since 3.9.0
    116      *
    117      * @access public
    118      * @global WP_Customize_Manager $wp_customize
     116     * Set up widget addition previews.
     117     *
     118     * Since the widgets get registered on 'widgets_init' before the customizer
     119     * settings are set up on 'customize_register', we have to filter the options
     120     * similarly to how the setting previewer will filter the options later.
     121     *
     122     * @since 3.9.0
     123     *
     124     * @access public
     125     * @global WP_Customize_Manager $wp_customize Customizer instance.
    119126     */
    120127    public function setup_widget_addition_previews() {
    … …  
    169176        foreach ( $customized as $setting_id => $value ) {
    170177            if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) {
     178
     179                /*
     180                 * @todo Replace the next two lines with the following once WordPress supports PHP 5.3.
     181                 *
     182                 * $self = $this; // not needed in PHP 5.4
     183                 *
     184                 * $function = function ( $value ) use ( $self, $setting_id ) {
     185                 *      return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
     186                 * };
     187                 */
    171188                $body     = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) );
    172189                $function = create_function( '$value', $body );
    173                 // @todo replace above two lines with following once PHP 5.3 happens in WordPress
    174                 // $self = $this; // not needed in PHP 5.4
    175                 // $function = function ( $value ) use ( $self, $setting_id ) {
    176                 //  return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
    177                 //};
    178 
    179                 $option   = $matches[1];
     190
     191                $option = $matches[1];
    180192
    181193                $hook = sprintf( 'option_%s', $option );
    … …  
    187199                $this->_prepreview_added_filters[] = compact( 'hook', 'function' );
    188200
    189                 /**
    190                  * Make sure the option is registered so that the update_option won't fail due to
    191                  * the filters providing a default value, which causes the update_option() to get confused.
     201                /*
     202                 * Make sure the option is registered so that the update_option()
     203                 * won't fail due to the filters providing a default value, which
     204                 * causes the update_option() to get confused.
    192205                 */
    193206                add_option( $option, array() );
    … …  
    199212
    200213    /**
    201      *
    202      *
    203214     * Ensure that newly-added widgets will appear in the widgets_sidebars.
    204      * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
    205      * which is too late for the widgets to be set up properly.
    206      *
    207      * @since 3.9.0
    208      * @access public
    209      *
    210      * @param array $sidebars_widgets Array of
    211      * @return array
     215     *
     216     * This is necessary because the customizer's setting preview filters
     217     * are added after the widgets_init action, which is too late for the
     218     * widgets to be set up properly.
     219     *
     220     * @since 3.9.0
     221     * @access public
     222     *
     223     * @param array $sidebars_widgets Associative array of sidebars and their widgets.
     224     * @return array Filtered array of sidebars and their widgets.
    212225     */
    213226    public function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
    … …  
    222235
    223236    /**
    224      *
    225      *
    226      * Ensure that newly-added widgets will have empty instances so that they will be recognized.
    227      * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
    228      * which is too late for the widgets to be set up properly.
     237     * Ensure newly-added widgets have empty instances so they
     238     * will be recognized.
     239     *
     240     * This is necessary because the customizer's setting preview
     241     * filters are added after the widgets_init action, which is
     242     * too late for the widgets to be set up properly.
    229243     *
    230244     * @since 3.9.0
    … …  
    240254            $widget_number     = $parsed_setting_id['number'];
    241255
    242             // Single widget
     256            // Single widget.
    243257            if ( is_null( $widget_number ) ) {
    244258                if ( false === $instance && empty( $value ) ) {
    … …  
    260274
    261275    /**
    262      * Remove filters added in setup_widget_addition_previews() which ensure that
    263      * widgets are populating the options during widgets_init
     276     * Remove pre-preview filters.
     277     *
     278     * Removes filters added in setup_widget_addition_previews()
     279     * to ensure widgets are populating the options during
     280     * 'widgets_init'.
    264281     *
    265282     * @since 3.9.0
    … …  
    274291
    275292    /**
    276      * Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget()
     293     * Make sure all widgets get loaded into the Customizer.
     294     *
     295     * Note: these actions are also fired in wp_ajax_update_widget().
    277296     *
    278297     * @since 3.9.0
    … …  
    280299     */
    281300    public function customize_controls_init() {
     301        /** This action is documented in wp-admin/includes/ajax-actions.php */
    282302        do_action( 'load-widgets.php' );
     303
     304        /** This action is documented in wp-admin/includes/ajax-actions.php */
    283305        do_action( 'widgets.php' );
    284306
    … …  
    288310
    289311    /**
    290      * When in preview, invoke customize_register for settings after WordPress is
    291      * loaded so that all filters have been initialized (e.g. Widget Visibility)
     312     * Ensure widgets are available for all types of previews.
     313     *
     314     * When in preview, hook to 'customize_register' for settings
     315     * after WordPress is loaded so that all filters have been
     316     * initialized (e.g. Widget Visibility).
    292317     *
    293318     * @since 3.9.0
    … …  
    303328
    304329    /**
    305      * Register customizer settings and controls for all sidebars and widgets
     330     * Register customizer settings and controls for all sidebars and widgets.
    306331     *
    307332     * @since 3.9.0
    … …  
    320345
    321346        /*
    322          * Register a setting for all widgets, including those which are active, inactive, and orphaned
    323          * since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility).
     347         * Register a setting for all widgets, including those which are active,
     348         * inactive, and orphaned since a widget may get suppressed from a sidebar
     349         * via a plugin (like Widget Visibility).
    324350         */
    325351        foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
    … …  
    340366            $is_active_sidebar     = ( $is_registered_sidebar && ! $is_inactive_widgets );
    341367
    342             /**
    343              * Add setting for managing the sidebar's widgets
    344              */
     368            // Add setting for managing the sidebar's widgets.
    345369            if ( $is_registered_sidebar || $is_inactive_widgets ) {
    346370                $setting_id   = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
    … …  
    351375                $new_setting_ids[] = $setting_id;
    352376
    353                 /**
    354                  * Add section to contain controls
    355                  */
     377                // Add section to contain controls.
    356378                $section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
    357379                if ( $is_active_sidebar ) {
    … …  
    423445
    424446    /**
    425      * Covert a widget_id into its corresponding customizer setting id (option name)
     447     * Covert a widget_id into its corresponding customizer setting ID (option name).
    426448     *
    427449     * @since 3.9.0
    … …  
    441463
    442464    /**
    443      * Core widgets which may have controls wider than 250, but can still be
    444      * shown in the narrow customizer panel. The RSS and Text widgets in Core,
    445      * for example, have widths of 400 and yet they still render fine in the
    446      * customizer panel. This method will return all Core widgets as being
    447      * not wide, but this can be overridden with the is_wide_widget_in_customizer
    448      * filter.
     465     * Determine whether the widget is considered "wide".
     466     *
     467     * Core widgets which may have controls wider than 250, but can
     468     * still be shown in the narrow customizer panel. The RSS and Text
     469     * widgets in Core, for example, have widths of 400 and yet they
     470     * still render fine in the customizer panel. This method will
     471     * return all Core widgets as being not wide, but this can be
     472     * overridden with the is_wide_widget_in_customizer filter.
    449473     *
    450474     * @since 3.9.0
    … …  
    469493         * @param string $widget_id Widget ID.
    470494         */
    471         $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
    472         return $is_wide;
     495        return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
    473496    }
    474497
    … …  
    504527     *
    505528     * @param string $setting_id Widget setting ID.
    506      * @return WP_Error|array Array contain a widget's id_base and number components,
     529     * @return WP_Error|array Array containing a widget's id_base and number components,
    507530     *                        or a WP_Error object.
    508531     */
    … …  
    518541
    519542    /**
    520      * Enqueue scripts and styles for customizer panel and export data to JS.
     543     * Enqueue scripts and styles for customizer panel and export data to JavaScript.
    521544     *
    522545     * @since 3.9.0
    … …  
    527550        wp_enqueue_script( 'customize-widgets' );
    528551
    529         // Export available widgets with control_tpl removed from model
    530         // since plugins need templates to be in the DOM
     552        /*
     553         * Export available widgets with control_tpl removed from model
     554         * since plugins need templates to be in the DOM.
     555         */
    531556        $available_widgets = array();
    532557        foreach ( $this->get_available_widgets() as $available_widget ) {
    … …  
    563588        );
    564589
    565         // Why not wp_localize_script? Because we're not localizing, and it forces values into strings.
     590        /*
     591         * Why not wp_localize_script? Because we're not localizing,
     592         * and it forces values into strings.
     593         */
    566594        global $wp_scripts;
    567595        $exports = array(
    … …  
    595623
    596624    /**
    597      * Render the widget form control templates into the DOM so that plugin scripts can manipulate them
     625     * Render the widget form control templates into the DOM.
    598626     *
    599627     * @since 3.9.0
    … …  
    619647
    620648    /**
    621      * Get common arguments to supply when constructing a customizer setting
     649     * Get common arguments to supply when constructing a Customizer setting.
    622650     *
    623651     * @since 3.9.0
    … …  
    636664        );
    637665        $args = array_merge( $args, $overrides );
    638         $args = apply_filters( 'widget_customizer_setting_args', $args, $id );
    639         return $args;
    640     }
    641 
    642     /**
    643      * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs.
    644      * Used as sanitize_callback for each sidebars_widgets setting.
     666
     667        /**
     668         * Filter the common arguments supplied when constructing a Customizer setting.
     669         *
     670         * @since 3.9.0
     671         *
     672         * @see WP_Customize_Setting
     673         *
     674         * @param array  $args Array of Customizer setting arguments.
     675         * @param string $id   Widget setting ID.
     676         */
     677        return apply_filters( 'widget_customizer_setting_args', $args, $id );
     678    }
     679
     680    /**
     681     * Make sure that sidebar widget arrays only ever contain widget IDS.
     682     *
     683     * Used as the 'sanitize_callback' for each $sidebars_widgets setting.
    645684     *
    646685     * @since 3.9.0
    … …  
    669708     *
    670709     * @see wp_list_widgets()
    671      * @return array
     710     *
     711     * @return array List of available widgets.
    672712     */
    673713    public function get_available_widgets() {
    … …  
    727767            $control_tpl = $this->get_widget_control( $list_widget_controls_args );
    728768
    729             // The properties here are mapped to the Backbone Widget model
     769            // The properties here are mapped to the Backbone Widget model.
    730770            $available_widget = array_merge(
    731771                $available_widget,
    … …  
    765805
    766806    /**
    767      * Invoke wp_widget_control() but capture the output buffer and transform the markup
    768      * so that it can be used in the customizer.
     807     * Get the widget control markup.
    769808     *
    770809     * @since 3.9.0
    … …  
    787826
    788827    /**
    789      * Add hooks for the customizer preview
     828     * Add hooks for the customizer preview.
    790829     *
    791830     * @since 3.9.0
    … …  
    800839
    801840    /**
    802      *
    803      *
    804      * When previewing, make sure the proper previewing widgets are used. Because wp_get_sidebars_widgets()
    805      * gets called early at init (via wp_convert_widget_settings()) and can set global variable
    806      * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the customizer
    807      * preview filter is added, we have to reset it after the filter has been added.
     841     * When previewing, make sure the proper previewing widgets are used.
     842     *
     843     * Because wp_get_sidebars_widgets() gets called early at init
     844     * (via wp_convert_widget_settings()) and can set global variable
     845     * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' )
     846     * before the customizer preview filter is added, we have to reset
     847     * it after the filter has been added.
    808848     *
    809849     * @since 3.9.0
    … …  
    814854    public function preview_sidebars_widgets( $sidebars_widgets ) {
    815855        $sidebars_widgets = get_option( 'sidebars_widgets' );
     856
    816857        unset( $sidebars_widgets['array_version'] );
    817858        return $sidebars_widgets;
    … …  
    819860
    820861    /**
    821      * Enqueue scripts for the customizer preview
     862     * Enqueue scripts for the Customizer preview.
    822863     *
    823864     * @since 3.9.0
    … …  
    852893
    853894    /**
    854      * At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page.
     895     * At the very end of the page, at the very end of the wp_footer,
     896     * communicate the sidebars that appeared on the page.
    855897     *
    856898     * @since 3.9.0
    … …  
    880922
    881923    /**
    882      * Keep track of the widgets that were rendered
     924     * Keep track of the widgets that were rendered.
    883925     *
    884926     * @since 3.9.0
    … …  
    892934
    893935    /**
    894      * Keep track of the times that is_active_sidebar() is called in the template, and assume that this
    895      * means that the sidebar would be rendered on the template if there were widgets populating it.
     936     * Tally the sidebars rendered via is_active_sidebar().
     937     *
     938     * Keep track of the times that is_active_sidebar() is called
     939     * in the template, and assume that this means that the sidebar
     940     * would be rendered on the template if there were widgets
     941     * populating it.
    896942     *
    897943     * @since 3.9.0
    … …  
    905951            $this->rendered_sidebars[] = $sidebar_id;
    906952        }
    907         // We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets
    908         // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
     953        /*
     954         * We may need to force this to true, and also force-true the value
     955         * for 'dynamic_sidebar_has_widgets' if we want to ensure that there
     956         * is an area to drop widgets into, if the sidebar is empty.
     957         */
    909958        return $is_active;
    910959    }
    911960
    912961    /**
    913      * Keep track of the times that dynamic_sidebar() is called in the template, and assume that this
    914      * means that the sidebar would be rendered on the template if there were widgets populating it.
     962     * Tally the sidebars rendered via dynamic_sidebar().
     963     *
     964     * Keep track of the times that dynamic_sidebar() is called in the template,
     965     * and assume this means the sidebar would be rendered on the template if
     966     * there were widgets populating it.
    915967     *
    916968     * @since 3.9.0
    … …  
    924976            $this->rendered_sidebars[] = $sidebar_id;
    925977        }
     978
    926979        /*
    927          * We may need to force this to true, and also force-true the value for is_active_sidebar
    928          * if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
     980         * We may need to force this to true, and also force-true the value
     981         * for 'is_active_sidebar' if we want to ensure there is an area to
     982         * drop widgets into, if the sidebar is empty.
    929983         */
    930984        return $has_widgets;
    … …  
    9581012     * @since 3.9.0
    9591013     * @access public
    960      *
    961      * @see Widget_Customizer::sanitize_widget_js_instance()
    9621014     *
    9631015     * @param array $value Widget instance to sanitize.
    … …  
    9981050     * @access public
    9991051     *
    1000      * @see Widget_Customizer::sanitize_widget_instance()
    1001      *
    10021052     * @param array $value Widget instance to convert to JSON.
    10031053     * @return array JSON-converted widget instance.
    … …  
    10171067
    10181068    /**
    1019      * Strip out widget IDs for widgets which are no longer registered, such
    1020      * as the case when a plugin orphans a widget in a sidebar when it is deactivated.
     1069     * Strip out widget IDs for widgets which are no longer registered.
     1070     *
     1071     * One example where this might happen is when a plugin orphans a widget
     1072     * in a sidebar upon deactivation.
    10211073     *
    10221074     * @since 3.9.0
    … …  
    10411093     *
    10421094     * @param  string $widget_id Widget ID.
    1043      * @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise.
     1095     * @return WP_Error|array Array containing the updated widget information.
     1096     *                        A WP_Error object, otherwise.
    10441097     */
    10451098    public function call_widget_update( $widget_id ) {
    … …  
    11331186
    11341187    /**
    1135      * Allow customizer to update a widget using its form, but return the new
     1188     * Update widget settings asynchronously.
     1189     *
     1190     * Allows the Customizer to update a widget using its form, but return the new
    11361191     * instance info via Ajax instead of saving it to the options table.
     1192     *
    11371193     * Most code here copied from wp_ajax_save_widget()
    11381194     *
    … …  
    11401196     * @access public
    11411197     *
    1142      * @see wp_ajax_save_widget
     1198     * @see wp_ajax_save_widget()
     1199     *
    11431200     * @todo Reuse wp_ajax_save_widget now that we have option transactions?
    1144      * @action wp_ajax_update_widget
    11451201     */
    11461202    public function wp_ajax_update_widget() {
    … …  
    11601216        }
    11611217
     1218        /** This action is documented in wp-admin/includes/ajax-actions.php */
    11621219        do_action( 'load-widgets.php' );
     1220
     1221        /** This action is documented in wp-admin/includes/ajax-actions.php */
    11631222        do_action( 'widgets.php' );
    11641223
    … …  
    11901249
    11911250    /**
    1192      * @var array $_captured_options values updated while capturing is happening
     1251     * List of captured widget option updates.
     1252     *
     1253     * @since 3.9.0
     1254     * @access protected
     1255     * @var array $_captured_options Values updated while option capture is happening.
    11931256     */
    11941257    protected $_captured_options = array();
    11951258
    11961259    /**
    1197      * @var bool $_is_current whether capturing is currently happening or not
     1260     * Whether option capture is currently happening.
     1261     *
     1262     * @since 3.9.0
     1263     * @access protected
     1264     * @var bool $_is_current Whether option capture is currently happening or not.
    11981265     */
    11991266    protected $_is_capturing_option_updates = false;
    12001267
    12011268    /**
    1202      * @param $option_name
    1203      * @return boolean
     1269     * Determine whether the captured option update should be ignored.
     1270     *
     1271     * @since 3.9.0
     1272     * @access protected
     1273     *
     1274     * @param string $option_name Option name.
     1275     * @return boolean Whether the option capture is ignored.
    12041276     */
    12051277    protected function is_option_capture_ignored( $option_name ) {
    … …  
    12081280
    12091281    /**
    1210      * Get options updated
    1211      * @return array
     1282     * Retrieve captured widget option updates.
     1283     *
     1284     * @since 3.9.0
     1285     * @access protected
     1286     *
     1287     * @return array Array of captured options.
    12121288     */
    12131289    protected function get_captured_options() {
    … …  
    12161292
    12171293    /**
    1218      * Get the number of options updated
    1219      * @return bool
     1294     * Get the number of captured widget option updates.
     1295     *
     1296     * @since 3.9.0
     1297     * @access protected
     1298     *
     1299     * @return int Number of updated options.
    12201300     */
    12211301    protected function count_captured_options() {
    … …  
    12241304
    12251305    /**
    1226      * Start keeping track of changes to options, and cache their new values
     1306     * Start keeping track of changes to widget options, caching new values.
     1307     *
     1308     * @since 3.9.0
     1309     * @access protected
    12271310     */
    12281311    protected function start_capturing_option_updates() {
    … …  
    12361319
    12371320    /**
     1321     * Pre-filter captured option values before updating.
     1322     *
    12381323     * @access private
    12391324     * @param mixed $new_value
    … …  
    12421327     * @return mixed
    12431328     */
    1244     public function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
     1329    private function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
    12451330        if ( $this->is_option_capture_ignored( $option_name ) ) {
    12461331            return;
    … …  
    12571342
    12581343    /**
     1344     * Pre-filter captured option values before retrieving.
     1345     *
    12591346     * @access private
    1260      * @param mixed $value
     1347     * @param mixed $value Option
    12611348     * @return mixed
    12621349     */
    1263     public function _capture_filter_pre_get_option( $value ) {
     1350    private function _capture_filter_pre_get_option( $value ) {
    12641351        $option_name = preg_replace( '/^pre_option_/', '', current_filter() );
    12651352        if ( isset( $this->_captured_options[$option_name] ) ) {
    … …  
    12721359
    12731360    /**
    1274      * Undo any changes to the options since start_capturing_option_updates() was called
     1361     * Undo any changes to the options since options capture began.
     1362     *
     1363     * @since 3.9.0
     1364     * @access protected
    12751365     */
    12761366    protected function stop_capturing_option_updates() {
Note: See TracChangeset for help on using the changeset viewer.