WordPress.org
Get WordPress

Make WordPress Core

Changeset 37700


Ignore:
Timestamp:
06/14/2016 07:16:54 PM (10 years ago)
Author:
westonruter
Message:

Customize: Update server-sent setting validation notifications as changes are entered.

Send back setting validities with full refreshes and selective refreshes so that invalid settings can have notifications displayed immediately before attempting save, and so that these notifications can be cleared as soon as the input is corrected.

  • Splits out JS logic for listing controls into separate methods wp.customize.Setting.prototype.findControls() and wp.customize.findControlsForSettings().
  • Adds a setting property to the data on notifications added to controls that are synced from their settings.
  • Adds selective-refresh-setting-validities message sent from preview to pane.
  • Changes WP_Customize_Manager::validate_setting_values() to return when settings are valid as well as invalid.
  • Adds WP_Customize_Manager::prepare_setting_validity_for_js().
  • Add setting validities to data exported to JS in Customizer Preview and in selective refresh responses.

Fixes #36944.

Location:
trunk
Files:
8 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/js/customize-controls.js

    r37476 r37700  
    4444                                        return this.previewer.send( 'setting', [ this.id, this() ] );
    4545                        }
     46                },
     47
     48                /**
     49                 * Find controls associated with this setting.
     50                 *
     51                 * @since 4.6.0
     52                 * @returns {wp.customize.Control[]} Controls associated with setting.
     53                 */
     54                findControls: function() {
     55                        var setting = this, controls = [];
     56                        api.control.each( function( control ) {
     57                                _.each( control.settings, function( controlSetting ) {
     58                                        if ( controlSetting.id === setting.id ) {
     59                                                controls.push( control );
     60                                        }
     61                                } );
     62                        } );
     63                        return controls;
    4664                }
    4765        });
    … …  
    15441562                                        control.setting = control.settings['default'] || null;
    15451563
     1564                                        // Add setting notifications to the control notification.
    15461565                                        _.each( control.settings, function( setting ) {
    15471566                                                setting.notifications.bind( 'add', function( settingNotification ) {
    1548                                                         var controlNotification = new api.Notification( setting.id + ':' + settingNotification.code, settingNotification );
     1567                                                        var controlNotification, code, params;
     1568                                                        code = setting.id + ':' + settingNotification.code;
     1569                                                        params = _.extend(
     1570                                                                {},
     1571                                                                settingNotification,
     1572                                                                {
     1573                                                                        setting: setting.id
     1574                                                                }
     1575                                                        );
     1576                                                        controlNotification = new api.Notification( code, params );
    15491577                                                        control.notifications.add( controlNotification.code, controlNotification );
    15501578                                                } );
    … …  
    29092937                                        } );
    29102938                                } );
     2939
     2940                                if ( data.settingValidities ) {
     2941                                        api._handleSettingValidities( {
     2942                                                settingValidities: data.settingValidities,
     2943                                                focusInvalidControl: false
     2944                                        } );
     2945                                }
    29112946                        } );
    29122947
    … …  
    34313466                        },
    34323467
    3433                         /**
    3434                          * Handle invalid_settings in an error response for the customize-save request.
    3435                          *
    3436                          * Add notifications to the settings and focus on the first control that has an invalid setting.
    3437                          *
    3438                          * @since 4.6.0
    3439                          * @private
    3440                          *
    3441                          * @param {object} response
    3442                          * @param {object} response.invalid_settings
    3443                          * @returns {void}
    3444                          */
    3445                         _handleInvalidSettingsError: function( response ) {
    3446                                 var invalidControls = [], wasFocused = false;
    3447                                 if ( _.isEmpty( response.invalid_settings ) ) {
    3448                                         return;
    3449                                 }
    3450 
    3451                                 // Find the controls that correspond to each invalid setting.
    3452                                 _.each( response.invalid_settings, function( notifications, settingId ) {
    3453                                         var setting = api( settingId );
    3454                                         if ( setting ) {
    3455                                                 _.each( notifications, function( notificationParams, code ) {
    3456                                                         var notification = new api.Notification( code, notificationParams );
    3457                                                         setting.notifications.add( code, notification );
    3458                                                 } );
    3459                                         }
    3460 
    3461                                         api.control.each( function( control ) {
    3462                                                 _.each( control.settings, function( controlSetting ) {
    3463                                                         if ( controlSetting.id === settingId ) {
    3464                                                                 invalidControls.push( control );
    3465                                                         }
    3466                                                 } );
    3467                                         } );
    3468                                 } );
    3469 
    3470                                 // Focus on the first control that is inside of an expanded section (one that is visible).
    3471                                 _( invalidControls ).find( function( control ) {
    3472                                         var isExpanded = control.section() && api.section.has( control.section() ) && api.section( control.section() ).expanded();
    3473                                         if ( isExpanded && control.expanded ) {
    3474                                                 isExpanded = control.expanded();
    3475                                         }
    3476                                         if ( isExpanded ) {
    3477                                                 control.focus();
    3478                                                 wasFocused = true;
    3479                                         }
    3480                                         return wasFocused;
    3481                                 } );
    3482 
    3483                                 // Focus on the first invalid control.
    3484                                 if ( ! wasFocused && invalidControls[0] ) {
    3485                                         invalidControls[0].focus();
    3486                                 }
    3487                         },
    3488 
    34893468                        save: function() {
    34903469                                var self = this,
    … …  
    34923471                                        submitWhenDoneProcessing,
    34933472                                        submit,
    3494                                         modifiedWhileSaving = {};
     3473                                        modifiedWhileSaving = {},
     3474                                        invalidSettings = [],
     3475                                        invalidControls;
    34953476
    34963477                                body.addClass( 'saving' );
    … …  
    35033484                                submit = function () {
    35043485                                        var request, query;
     3486
     3487                                        /*
     3488                                         * Block saving if there are any settings that are marked as
     3489                                         * invalid from the client (not from the server). Focus on
     3490                                         * the control.
     3491                                         */
     3492                                        api.each( function( setting ) {
     3493                                                setting.notifications.each( function( notification ) {
     3494                                                        if ( 'error' === notification.type && ( ! notification.data || ! notification.data.from_server ) ) {
     3495                                                                invalidSettings.push( setting.id );
     3496                                                        }
     3497                                                } );
     3498                                        } );
     3499                                        invalidControls = api.findControlsForSettings( invalidSettings );
     3500                                        if ( ! _.isEmpty( invalidControls ) ) {
     3501                                                _.values( invalidControls )[0][0].focus();
     3502                                                body.removeClass( 'saving' );
     3503                                                api.unbind( 'change', captureSettingModifiedDuringSave );
     3504                                                return;
     3505                                        }
     3506
    35053507                                        query = $.extend( self.query(), {
    35063508                                                nonce:  self.nonce.save
    … …  
    35123514
    35133515                                        api.trigger( 'save', request );
    3514 
    3515                                         /*
    3516                                          * Remove all setting error notifications prior to save, allowing
    3517                                          * server to respond with fresh validation error notifications.
    3518                                          */
    3519                                         api.each( function( setting ) {
    3520                                                 setting.notifications.each( function( notification ) {
    3521                                                         if ( 'error' === notification.type ) {
    3522                                                                 setting.notifications.remove( notification.code );
    3523                                                         }
    3524                                                 } );
    3525                                         } );
    35263516
    35273517                                        request.always( function () {
    … …  
    35493539                                                }
    35503540
    3551                                                 self._handleInvalidSettingsError( response );
     3541                                                if ( response.setting_validities ) {
     3542                                                        api._handleSettingValidities( {
     3543                                                                settingValidities: response.setting_validities,
     3544                                                                focusInvalidControl: true
     3545                                                        } );
     3546                                                }
    35523547
    35533548                                                api.trigger( 'error', response );
    … …  
    35643559
    35653560                                                api.previewer.send( 'saved', response );
     3561
     3562                                                if ( response.setting_validities ) {
     3563                                                        api._handleSettingValidities( {
     3564                                                                settingValidities: response.setting_validities,
     3565                                                                focusInvalidControl: true
     3566                                                        } );
     3567                                                }
    35663568
    35673569                                                api.trigger( 'saved', response );
    … …  
    36693671                        });
    36703672                });
     3673
     3674                /**
     3675                 * Handle setting_validities in an error response for the customize-save request.
     3676                 *
     3677                 * Add notifications to the settings and focus on the first control that has an invalid setting.
     3678                 *
     3679                 * @since 4.6.0
     3680                 * @private
     3681                 *
     3682                 * @param {object}  args
     3683                 * @param {object}  args.settingValidities
     3684                 * @param {boolean} [args.focusInvalidControl=false]
     3685                 * @returns {void}
     3686                 */
     3687                api._handleSettingValidities = function handleSettingValidities( args ) {
     3688                        var invalidSettingControls, invalidSettings = [], wasFocused = false;
     3689
     3690                        // Find the controls that correspond to each invalid setting.
     3691                        _.each( args.settingValidities, function( validity, settingId ) {
     3692                                var setting = api( settingId );
     3693                                if ( setting ) {
     3694
     3695                                        // Add notifications for invalidities.
     3696                                        if ( _.isObject( validity ) ) {
     3697                                                _.each( validity, function( params, code ) {
     3698                                                        var notification = new api.Notification( code, params ), existingNotification, needsReplacement = false;
     3699
     3700                                                        // Remove existing notification if already exists for code but differs in parameters.
     3701                                                        existingNotification = setting.notifications( notification.code );
     3702                                                        if ( existingNotification ) {
     3703                                                                needsReplacement = ( notification.type !== existingNotification.type ) || ! _.isEqual( notification.data, existingNotification.data );
     3704                                                        }
     3705                                                        if ( needsReplacement ) {
     3706                                                                setting.notifications.remove( code );
     3707                                                        }
     3708
     3709                                                        if ( ! setting.notifications.has( notification.code ) ) {
     3710                                                                setting.notifications.add( code, notification );
     3711                                                        }
     3712                                                        invalidSettings.push( setting.id );
     3713                                                } );
     3714                                        }
     3715
     3716                                        // Remove notification errors that are no longer valid.
     3717                                        setting.notifications.each( function( notification ) {
     3718                                                if ( 'error' === notification.type && ( true === validity || ! validity[ notification.code ] ) ) {
     3719                                                        setting.notifications.remove( notification.code );
     3720                                                }
     3721                                        } );
     3722                                }
     3723                        } );
     3724
     3725                        if ( args.focusInvalidControl ) {
     3726                                invalidSettingControls = api.findControlsForSettings( invalidSettings );
     3727
     3728                                // Focus on the first control that is inside of an expanded section (one that is visible).
     3729                                _( _.values( invalidSettingControls ) ).find( function( controls ) {
     3730                                        return _( controls ).find( function( control ) {
     3731                                                var isExpanded = control.section() && api.section.has( control.section() ) && api.section( control.section() ).expanded();
     3732                                                if ( isExpanded && control.expanded ) {
     3733                                                        isExpanded = control.expanded();
     3734                                                }
     3735                                                if ( isExpanded ) {
     3736                                                        control.focus();
     3737                                                        wasFocused = true;
     3738                                                }
     3739                                                return wasFocused;
     3740                                        } );
     3741                                } );
     3742
     3743                                // Focus on the first invalid control.
     3744                                if ( ! wasFocused && ! _.isEmpty( invalidSettingControls ) ) {
     3745                                        _.values( invalidSettingControls )[0][0].focus();
     3746                                }
     3747                        }
     3748                };
     3749
     3750                /**
     3751                 * Find all controls associated with the given settings.
     3752                 *
     3753                 * @since 4.6.0
     3754                 * @param {string[]} settingIds Setting IDs.
     3755                 * @returns {object<string, wp.customize.Control>} Mapping setting ids to arrays of controls.
     3756                 */
     3757                api.findControlsForSettings = function findControlsForSettings( settingIds ) {
     3758                        var controls = {}, settingControls;
     3759                        _.each( _.unique( settingIds ), function( settingId ) {
     3760                                var setting = api( settingId );
     3761                                if ( setting ) {
     3762                                        settingControls = setting.findControls();
     3763                                        if ( settingControls && settingControls.length > 0 ) {
     3764                                                controls[ settingId ] = settingControls;
     3765                                        }
     3766                                }
     3767                        } );
     3768                        return controls;
     3769                };
    36713770
    36723771                /**
    … …  
    40414140                });
    40424141
     4142                // Update the setting validities.
     4143                api.previewer.bind( 'selective-refresh-setting-validities', function handleSelectiveRefreshedSettingValidities( settingValidities ) {
     4144                        api._handleSettingValidities( {
     4145                                settingValidities: settingValidities,
     4146                                focusInvalidControl: false
     4147                        } );
     4148                } );
     4149
    40434150                // Focus on the control that is associated with the given setting.
    40444151                api.previewer.bind( 'focus-control-for-setting', function( settingId ) {

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

    r37539 r37700  
    826826         */
    827827        public function customize_preview_settings() {
     828                $setting_validities = $this->validate_setting_values( $this->unsanitized_post_values() );
     829                $exported_setting_validities = array_map( array( $this, 'prepare_setting_validity_for_js' ), $setting_validities );
     830
    828831                $settings = array(
    829832                        'theme' => array(
    … …  
    838841                        'activeSections' => array(),
    839842                        'activeControls' => array(),
     843                        'settingValidities' => $exported_setting_validities,
    840844                        'nonce' => $this->get_nonces(),
    841845                        'l10n' => array(
    … …  
    992996         * @access public
    993997         * @see WP_REST_Request::has_valid_params()
     998         * @see WP_Customize_Setting::validate()
    994999         *
    9951000         * @param array $setting_values Mapping of setting IDs to values to sanitize and validate.
    996          * @return array Empty array if all settings were valid. One or more instances of `WP_Error` if any were invalid.
     1001         * @return array Mapping of setting IDs to return value of validate method calls, either `true` or `WP_Error`.
    9971002         */
    9981003        public function validate_setting_values( $setting_values ) {
    999                 $validity_errors = array();
     1004                $validities = array();
    10001005                foreach ( $setting_values as $setting_id => $unsanitized_value ) {
    10011006                        $setting = $this->get_setting( $setting_id );
    … …  
    10071012                                $validity = new WP_Error( 'invalid_value', __( 'Invalid value.' ) );
    10081013                        }
    1009                         if ( is_wp_error( $validity ) ) {
    1010                                 $validity_errors[ $setting_id ] = $validity;
    1011                         }
    1012                 }
    1013                 return $validity_errors;
     1014                        $validities[ $setting_id ] = $validity;
     1015                }
     1016                return $validities;
     1017        }
     1018
     1019        /**
     1020         * Prepare setting validity for exporting to the client (JS).
     1021         *
     1022         * Converts `WP_Error` instance into array suitable for passing into the
     1023         * `wp.customize.Notification` JS model.
     1024         *
     1025         * @since 4.6.0
     1026         * @access public
     1027         *
     1028         * @param true|WP_Error $validity Setting validity.
     1029         * @return true|array If `$validity` was `WP_Error` then array mapping the error
     1030         *                    codes to their respective `message` and `data` to pass
     1031         *                    into the `wp.customize.Notification` JS model.
     1032         */
     1033        public function prepare_setting_validity_for_js( $validity ) {
     1034                if ( is_wp_error( $validity ) ) {
     1035                        $notification = array();
     1036                        foreach ( $validity->errors as $error_code => $error_messages ) {
     1037                                $error_data = $validity->get_error_data( $error_code );
     1038                                if ( is_null( $error_data ) ) {
     1039                                        $error_data = array();
     1040                                }
     1041                                $error_data = array_merge(
     1042                                        $error_data,
     1043                                        array( 'from_server' => true )
     1044                                );
     1045                                $notification[ $error_code ] = array(
     1046                                        'message' => join( ' ', $error_messages ),
     1047                                        'data' => $error_data,
     1048                                );
     1049                        }
     1050                        return $notification;
     1051                } else {
     1052                        return true;
     1053                }
    10141054        }
    10151055
    … …  
    10421082
    10431083                // Validate settings.
    1044                 $validity_errors = $this->validate_setting_values( $this->unsanitized_post_values() );
    1045                 $invalid_count = count( $validity_errors );
    1046                 if ( $invalid_count > 0 ) {
    1047                         $settings_errors = array();
    1048                         foreach ( $validity_errors as $setting_id => $validity_error ) {
    1049                                 $settings_errors[ $setting_id ] = array();
    1050                                 foreach ( $validity_error->errors as $error_code => $error_messages ) {
    1051                                         $settings_errors[ $setting_id ][ $error_code ] = array(
    1052                                                 'message' => join( ' ', $error_messages ),
    1053                                                 'data' => $validity_error->get_error_data( $error_code ),
    1054                                         );
    1055                                 }
    1056                         }
     1084                $setting_validities = $this->validate_setting_values( $this->unsanitized_post_values() );
     1085                $invalid_setting_count = count( array_filter( $setting_validities, 'is_wp_error' ) );
     1086                $exported_setting_validities = array_map( array( $this, 'prepare_setting_validity_for_js' ), $setting_validities );
     1087                if ( $invalid_setting_count > 0 ) {
    10571088                        $response = array(
    1058                                 'invalid_settings' => $settings_errors,
    1059                                 'message' => sprintf( _n( 'There is %s invalid setting.', 'There are %s invalid settings.', $invalid_count ), number_format_i18n( $invalid_count ) ),
     1089                                'setting_validities' => $exported_setting_validities,
     1090                                'message' => sprintf( _n( 'There is %s invalid setting.', 'There are %s invalid settings.', $invalid_setting_count ), number_format_i18n( $invalid_setting_count ) ),
    10601091                        );
    10611092
    … …  
    10981129                do_action( 'customize_save_after', $this );
    10991130
     1131                $data = array(
     1132                        'setting_validities' => $exported_setting_validities,
     1133                );
     1134
    11001135                /**
    11011136                 * Filters response data for a successful customize_save AJAX request.
    … …  
    11091144                 * @param WP_Customize_Manager $this WP_Customize_Manager instance.
    11101145                 */
    1111                 $response = apply_filters( 'customize_save_response', array(), $this );
     1146                $response = apply_filters( 'customize_save_response', $data, $this );
    11121147                wp_send_json_success( $response );
    11131148        }

  • trunk/src/wp-includes/customize/class-wp-customize-selective-refresh.php

    r37011 r37700  
    403403                }
    404404
     405                $setting_validities = $this->manager->validate_setting_values( $this->manager->unsanitized_post_values() );
     406                $exported_setting_validities = array_map( array( $this->manager, 'prepare_setting_validity_for_js' ), $setting_validities );
     407                $response['setting_validities'] = $exported_setting_validities;
     408
    405409                /**
    406410                 * Filters the response from rendering the partials.

  • trunk/src/wp-includes/js/customize-preview.js

    r36990 r37700  
    173173                        activePanels: api.settings.activePanels,
    174174                        activeSections: api.settings.activeSections,
    175                         activeControls: api.settings.activeControls
     175                        activeControls: api.settings.activeControls,
     176                        settingValidities: api.settings.settingValidities
    176177                } );
    177178

  • trunk/src/wp-includes/js/customize-selective-refresh.js

    r37040 r37700  
    848848                } );
    849849
     850                /**
     851                 * Handle setting validities in partial refresh response.
     852                 *
     853                 * @param {object} data Response data.
     854                 * @param {object} data.setting_validities Setting validities.
     855                 */
     856                api.selectiveRefresh.bind( 'render-partials-response', function handleSettingValiditiesResponse( data ) {
     857                        if ( data.setting_validities ) {
     858                                api.preview.send( 'selective-refresh-setting-validities', data.setting_validities );
     859                        }
     860                } );
     861
    850862                api.preview.bind( 'active', function() {
    851863

  • trunk/tests/phpunit/tests/customize/manager.php

    r37476 r37700  
    197197         */
    198198        function test_validate_setting_values() {
    199                 $default_value = 'foo_default';
    200199                $setting = $this->manager->add_setting( 'foo', array(
    201200                        'validate_callback' => array( $this, 'filter_customize_validate_foo' ),
    … …  
    205204                $post_value = 'bar';
    206205                $this->manager->set_post_value( 'foo', $post_value );
    207                 $this->assertEmpty( $this->manager->validate_setting_values( $this->manager->unsanitized_post_values() ) );
     206                $validities = $this->manager->validate_setting_values( $this->manager->unsanitized_post_values() );
     207                $this->assertCount( 1, $validities );
     208                $this->assertEquals( array( 'foo' => true ), $validities );
    208209
    209210                $this->manager->set_post_value( 'foo', 'return_wp_error_in_sanitize' );
    … …  
    235236
    236237        /**
     238         * Test WP_Customize_Manager::prepare_setting_validity_for_js().
     239         *
     240         * @see WP_Customize_Manager::prepare_setting_validity_for_js()
     241         */
     242        function test_prepare_setting_validity_for_js() {
     243                $this->assertTrue( $this->manager->prepare_setting_validity_for_js( true ) );
     244                $error = new WP_Error();
     245                $error->add( 'bad_letter', 'Bad letter' );
     246                $error->add( 'bad_letter', 'Bad letra' );
     247                $error->add( 'bad_number', 'Bad number', array( 'number' => 123 ) );
     248                $validity = $this->manager->prepare_setting_validity_for_js( $error );
     249                $this->assertInternalType( 'array', $validity );
     250                foreach ( $error->errors as $code => $messages ) {
     251                        $this->assertArrayHasKey( $code, $validity );
     252                        $this->assertInternalType( 'array', $validity[ $code ] );
     253                        $this->assertEquals( join( ' ', $messages ), $validity[ $code ]['message'] );
     254                        $this->assertArrayHasKey( 'data', $validity[ $code ] );
     255                        $this->assertArrayHasKey( 'from_server', $validity[ $code ]['data'] );
     256                }
     257                $this->assertArrayHasKey( 'number', $validity['bad_number']['data'] );
     258                $this->assertEquals( 123, $validity['bad_number']['data']['number'] );
     259        }
     260
     261        /**
    237262         * Test WP_Customize_Manager::set_post_value().
    238263         *
    … …  
    566591                $this->assertArrayHasKey( 'activeSections', $settings );
    567592                $this->assertArrayHasKey( 'activeControls', $settings );
     593                $this->assertArrayHasKey( 'settingValidities', $settings );
    568594                $this->assertArrayHasKey( 'nonce', $settings );
    569595                $this->assertArrayHasKey( '_dirty', $settings );

  • trunk/tests/phpunit/tests/customize/selective-refresh-ajax.php

    r36650 r37700  
    345345                $output = json_decode( ob_get_clean(), true );
    346346                $this->assertEquals( array( get_bloginfo( 'name', 'display' ) ), $output['data']['contents']['test_blogname'] );
     347                $this->assertArrayHasKey( 'setting_validities', $output['data'] );
    347348        }
    348349

  • trunk/tests/qunit/wp-admin/js/customize-controls.js

    r37476 r37700  
    9696                ok( setting.notifications.extended( wp.customize.Values ) );
    9797                equal( wp.customize.Notification, setting.notifications.prototype.constructor.defaultConstructor );
     98        } );
     99        test( 'Setting has findControls method', function() {
     100                var controls, setting = wp.customize( 'fixture-setting' );
     101                equal( 'function', typeof setting.findControls );
     102                controls = setting.findControls();
     103                equal( 1, controls.length );
     104                equal( 'fixture-control', controls[0].id );
    98105        } );
    99106        test( 'Setting constructor object exists', function( assert ) {
    … …  
    506513                equal( mockPanel.isContextuallyActive(), false );
    507514        });
     515
     516        module( 'Test wp.customize.findControlsForSettings' );
     517        test( 'findControlsForSettings(blogname)', function() {
     518                var controlsForSettings, settingId = 'fixture-setting', controlId = 'fixture-control';
     519                ok( wp.customize.control.has( controlId ) );
     520                ok( wp.customize.has( settingId ) );
     521                controlsForSettings = wp.customize.findControlsForSettings( [ settingId ] );
     522                ok( _.isObject( controlsForSettings ), 'Response is object' );
     523                ok( _.isArray( controlsForSettings['fixture-setting'] ), 'Response has a fixture-setting array' );
     524                equal( 1, controlsForSettings['fixture-setting'].length );
     525                equal( wp.customize.control( controlId ), controlsForSettings['fixture-setting'][0] );
     526        } );
    508527});
Note: See TracChangeset for help on using the changeset viewer.