Customize: Add setting validation model and control notifications to augment setting sanitization.
When a setting is invalid, not only will it be blocked from being saved but all other settings will be blocked as well. This ensures that Customizer saves aren't partial but are more transactional. User will be displayed the error in a notification so that they can fix and re-attempt saving.
PHP changes:
* Introduces `WP_Customize_Setting::validate()`, `WP_Customize_Setting::$validate_callback`, and the `customize_validate_{$setting_id}` filter.
* Introduces `WP_Customize_Manager::validate_setting_values()` to do validation (and sanitization) for the setting values supplied, returning a list of `WP_Error` instances for invalid settings.
* Attempting to save settings that are invalid will result in the save being blocked entirely, with the errors being sent in the `customize_save_response`. Modifies `WP_Customize_Manager::save()` to check all settings for validity issues prior to calling their `save` methods.
* Introduces `WP_Customize_Setting::json()` for parity with the other Customizer classes. This includes exporting of the `type`.
* Modifies `WP_Customize_Manager::post_value()` to apply `validate` after `sanitize`, and if validation fails, to return the `$default`.
* Introduces `customize_save_validation_before` action which fires right before the validation checks are made prior to saving.
JS changes:
* Introduces `wp.customize.Notification` in JS which to represent `WP_Error` instances returned from the server when setting validation fails.
* Introduces `wp.customize.Setting.prototype.notifications`.
* Introduces `wp.customize.Control.prototype.notifications`, which are synced with a control's settings' notifications.
* Introduces `wp.customize.Control.prototype.renderNotifications()` to re-render a control's notifications in its notification area. This is called automatically when the notifications collection changes.
* Introduces `wp.customize.settingConstructor`, allowing custom setting types to be used in the same way that custom controls, panels, and sections can be made.
* Injects a notification area into existing controls which is populated in response to the control's `notifications` collection changing. A custom control can customize the placement of the notification area by overriding the new `getNotificationsContainerElement` method.
* When a save fails due to setting invalidity, the invalidity errors will be added to the settings to then populate in the controls' notification areas, and the first such invalid control will be focused.
Props westonruter, celloexpressions, mrahmadawais.
See #35210.
See #30937.
Fixes #34893.
Built from https://develop.svn.wordpress.org/trunk@37476
git-svn-id: http://core.svn.wordpress.org/trunk@37444 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Weston Ruter
parent
19f988840f
commit
87b0a1b989
|
|
@ -494,7 +494,7 @@ p.customize-section-description {
|
|||
.customize-control input[type="search"],
|
||||
.customize-control input[type="tel"],
|
||||
.customize-control input[type="url"] {
|
||||
width: 98%;
|
||||
width: 100%;
|
||||
line-height: 18px;
|
||||
margin: 0;
|
||||
}
|
||||
|
|
@ -622,6 +622,46 @@ p.customize-section-description {
|
|||
border-left: 1px solid #ddd;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Notifications
|
||||
*/
|
||||
|
||||
#customize-controls .customize-control-notifications-container { /* Scoped to #customize-controls for specificity over notification styles in common.css. */
|
||||
margin: 4px 0 8px 0;
|
||||
padding: 0;
|
||||
display: none;
|
||||
cursor: default;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-widget_form.has-error .widget .widget-top,
|
||||
.customize-control-nav_menu_item.has-error .menu-item-bar .menu-item-handle {
|
||||
box-shadow: inset 0 0 0 2px #dc3232;
|
||||
transition: .15s box-shadow linear;
|
||||
}
|
||||
|
||||
.customize-control-notifications-container li.notice {
|
||||
list-style: none;
|
||||
margin: 0 0 6px 0;
|
||||
padding: 4px 8px;
|
||||
}
|
||||
|
||||
.customize-control-notifications-container li.notice:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-nav_menu_item .customize-control-notifications-container {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-widget_form .customize-control-notifications-container {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.customize-control-text.has-error input {
|
||||
outline: 2px solid #dc3232;
|
||||
}
|
||||
|
||||
/* Style for custom settings */
|
||||
|
||||
/**
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -494,7 +494,7 @@ p.customize-section-description {
|
|||
.customize-control input[type="search"],
|
||||
.customize-control input[type="tel"],
|
||||
.customize-control input[type="url"] {
|
||||
width: 98%;
|
||||
width: 100%;
|
||||
line-height: 18px;
|
||||
margin: 0;
|
||||
}
|
||||
|
|
@ -622,6 +622,46 @@ p.customize-section-description {
|
|||
border-right: 1px solid #ddd;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Notifications
|
||||
*/
|
||||
|
||||
#customize-controls .customize-control-notifications-container { /* Scoped to #customize-controls for specificity over notification styles in common.css. */
|
||||
margin: 4px 0 8px 0;
|
||||
padding: 0;
|
||||
display: none;
|
||||
cursor: default;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-widget_form.has-error .widget .widget-top,
|
||||
.customize-control-nav_menu_item.has-error .menu-item-bar .menu-item-handle {
|
||||
box-shadow: inset 0 0 0 2px #dc3232;
|
||||
transition: .15s box-shadow linear;
|
||||
}
|
||||
|
||||
.customize-control-notifications-container li.notice {
|
||||
list-style: none;
|
||||
margin: 0 0 6px 0;
|
||||
padding: 4px 8px;
|
||||
}
|
||||
|
||||
.customize-control-notifications-container li.notice:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-nav_menu_item .customize-control-notifications-container {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
#customize-controls .customize-control-widget_form .customize-control-notifications-container {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.customize-control-text.has-error input {
|
||||
outline: 2px solid #dc3232;
|
||||
}
|
||||
|
||||
/* Style for custom settings */
|
||||
|
||||
/**
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -27,6 +27,7 @@
|
|||
this.id = id;
|
||||
this.transport = this.transport || 'refresh';
|
||||
this._dirty = options.dirty || false;
|
||||
this.notifications = new api.Values({ defaultConstructor: api.Notification });
|
||||
|
||||
// Whenever the setting's value changes, refresh the preview.
|
||||
this.bind( this.preview );
|
||||
|
|
@ -1478,6 +1479,7 @@
|
|||
control.priority = new api.Value();
|
||||
control.active = new api.Value();
|
||||
control.activeArgumentsQueue = [];
|
||||
control.notifications = new api.Values({ defaultConstructor: api.Notification });
|
||||
|
||||
control.elements = [];
|
||||
|
||||
|
|
@ -1541,12 +1543,37 @@
|
|||
|
||||
control.setting = control.settings['default'] || null;
|
||||
|
||||
_.each( control.settings, function( setting ) {
|
||||
setting.notifications.bind( 'add', function( settingNotification ) {
|
||||
var controlNotification = new api.Notification( setting.id + ':' + settingNotification.code, settingNotification );
|
||||
control.notifications.add( controlNotification.code, controlNotification );
|
||||
} );
|
||||
setting.notifications.bind( 'remove', function( settingNotification ) {
|
||||
control.notifications.remove( setting.id + ':' + settingNotification.code );
|
||||
} );
|
||||
} );
|
||||
|
||||
control.embed();
|
||||
}) );
|
||||
}
|
||||
|
||||
// After the control is embedded on the page, invoke the "ready" method.
|
||||
control.deferred.embedded.done( function () {
|
||||
/*
|
||||
* Note that this debounced/deferred rendering is needed for two reasons:
|
||||
* 1) The 'remove' event is triggered just _before_ the notification is actually removed.
|
||||
* 2) Improve performance when adding/removing multiple notifications at a time.
|
||||
*/
|
||||
var debouncedRenderNotifications = _.debounce( function renderNotifications() {
|
||||
control.renderNotifications();
|
||||
} );
|
||||
control.notifications.bind( 'add', function( notification ) {
|
||||
wp.a11y.speak( notification.message, 'assertive' );
|
||||
debouncedRenderNotifications();
|
||||
} );
|
||||
control.notifications.bind( 'remove', debouncedRenderNotifications );
|
||||
control.renderNotifications();
|
||||
|
||||
control.ready();
|
||||
});
|
||||
},
|
||||
|
|
@ -1588,6 +1615,85 @@
|
|||
*/
|
||||
ready: function() {},
|
||||
|
||||
/**
|
||||
* Get the element inside of a control's container that contains the validation error message.
|
||||
*
|
||||
* Control subclasses may override this to return the proper container to render notifications into.
|
||||
* Injects the notification container for existing controls that lack the necessary container,
|
||||
* including special handling for nav menu items and widgets.
|
||||
*
|
||||
* @since 4.6.0
|
||||
* @returns {jQuery} Setting validation message element.
|
||||
* @this {wp.customize.Control}
|
||||
*/
|
||||
getNotificationsContainerElement: function() {
|
||||
var control = this, controlTitle, notificationsContainer;
|
||||
|
||||
notificationsContainer = control.container.find( '.customize-control-notifications-container:first' );
|
||||
if ( notificationsContainer.length ) {
|
||||
return notificationsContainer;
|
||||
}
|
||||
|
||||
notificationsContainer = $( '<div class="customize-control-notifications-container"></div>' );
|
||||
|
||||
if ( control.container.hasClass( 'customize-control-nav_menu_item' ) ) {
|
||||
control.container.find( '.menu-item-settings:first' ).prepend( notificationsContainer );
|
||||
} else if ( control.container.hasClass( 'customize-control-widget_form' ) ) {
|
||||
control.container.find( '.widget-inside:first' ).prepend( notificationsContainer );
|
||||
} else {
|
||||
controlTitle = control.container.find( '.customize-control-title' );
|
||||
if ( controlTitle.length ) {
|
||||
controlTitle.after( notificationsContainer );
|
||||
} else {
|
||||
control.container.prepend( notificationsContainer );
|
||||
}
|
||||
}
|
||||
return notificationsContainer;
|
||||
},
|
||||
|
||||
/**
|
||||
* Render notifications.
|
||||
*
|
||||
* Renders the `control.notifications` into the control's container.
|
||||
* Control subclasses may override this method to do their own handling
|
||||
* of rendering notifications.
|
||||
*
|
||||
* @since 4.6.0
|
||||
* @this {wp.customize.Control}
|
||||
*/
|
||||
renderNotifications: function() {
|
||||
var control = this, container, notifications, hasError = false;
|
||||
container = control.getNotificationsContainerElement();
|
||||
if ( ! container || ! container.length ) {
|
||||
return;
|
||||
}
|
||||
notifications = [];
|
||||
control.notifications.each( function( notification ) {
|
||||
notifications.push( notification );
|
||||
if ( 'error' === notification.type ) {
|
||||
hasError = true;
|
||||
}
|
||||
} );
|
||||
|
||||
if ( 0 === notifications.length ) {
|
||||
container.stop().slideUp( 'fast' );
|
||||
} else {
|
||||
container.stop().slideDown( 'fast', null, function() {
|
||||
$( this ).css( 'height', 'auto' );
|
||||
} );
|
||||
}
|
||||
|
||||
if ( ! control.notificationsTemplate ) {
|
||||
control.notificationsTemplate = wp.template( 'customize-control-notifications' );
|
||||
}
|
||||
|
||||
control.container.toggleClass( 'has-notifications', 0 !== notifications.length );
|
||||
control.container.toggleClass( 'has-error', hasError );
|
||||
container.empty().append( $.trim(
|
||||
control.notificationsTemplate( { notifications: notifications, altNotice: Boolean( control.altNotice ) } )
|
||||
) );
|
||||
},
|
||||
|
||||
/**
|
||||
* Normal controls do not expand, so just expand its parent
|
||||
*
|
||||
|
|
@ -3223,6 +3329,7 @@
|
|||
}
|
||||
});
|
||||
|
||||
api.settingConstructor = {};
|
||||
api.controlConstructor = {
|
||||
color: api.ColorControl,
|
||||
media: api.MediaControl,
|
||||
|
|
@ -3323,6 +3430,62 @@
|
|||
};
|
||||
},
|
||||
|
||||
/**
|
||||
* Handle invalid_settings in an error response for the customize-save request.
|
||||
*
|
||||
* Add notifications to the settings and focus on the first control that has an invalid setting.
|
||||
*
|
||||
* @since 4.6.0
|
||||
* @private
|
||||
*
|
||||
* @param {object} response
|
||||
* @param {object} response.invalid_settings
|
||||
* @returns {void}
|
||||
*/
|
||||
_handleInvalidSettingsError: function( response ) {
|
||||
var invalidControls = [], wasFocused = false;
|
||||
if ( _.isEmpty( response.invalid_settings ) ) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Find the controls that correspond to each invalid setting.
|
||||
_.each( response.invalid_settings, function( notifications, settingId ) {
|
||||
var setting = api( settingId );
|
||||
if ( setting ) {
|
||||
_.each( notifications, function( notificationParams, code ) {
|
||||
var notification = new api.Notification( code, notificationParams );
|
||||
setting.notifications.add( code, notification );
|
||||
} );
|
||||
}
|
||||
|
||||
api.control.each( function( control ) {
|
||||
_.each( control.settings, function( controlSetting ) {
|
||||
if ( controlSetting.id === settingId ) {
|
||||
invalidControls.push( control );
|
||||
}
|
||||
} );
|
||||
} );
|
||||
} );
|
||||
|
||||
// Focus on the first control that is inside of an expanded section (one that is visible).
|
||||
_( invalidControls ).find( function( control ) {
|
||||
var isExpanded = control.section() && api.section.has( control.section() ) && api.section( control.section() ).expanded();
|
||||
if ( isExpanded && control.expanded ) {
|
||||
isExpanded = control.expanded();
|
||||
}
|
||||
if ( isExpanded ) {
|
||||
control.focus();
|
||||
wasFocused = true;
|
||||
}
|
||||
return wasFocused;
|
||||
} );
|
||||
|
||||
// Focus on the first invalid control.
|
||||
if ( ! wasFocused && invalidControls[0] ) {
|
||||
invalidControls[0].focus();
|
||||
}
|
||||
},
|
||||
|
||||
save: function() {
|
||||
var self = this,
|
||||
processing = api.state( 'processing' ),
|
||||
|
|
@ -3349,6 +3512,18 @@
|
|||
|
||||
api.trigger( 'save', request );
|
||||
|
||||
/*
|
||||
* Remove all setting error notifications prior to save, allowing
|
||||
* server to respond with fresh validation error notifications.
|
||||
*/
|
||||
api.each( function( setting ) {
|
||||
setting.notifications.each( function( notification ) {
|
||||
if ( 'error' === notification.type ) {
|
||||
setting.notifications.remove( notification.code );
|
||||
}
|
||||
} );
|
||||
} );
|
||||
|
||||
request.always( function () {
|
||||
body.removeClass( 'saving' );
|
||||
saveBtn.prop( 'disabled', false );
|
||||
|
|
@ -3372,6 +3547,9 @@
|
|||
self.preview.iframe.show();
|
||||
} );
|
||||
}
|
||||
|
||||
self._handleInvalidSettingsError( response );
|
||||
|
||||
api.trigger( 'error', response );
|
||||
} );
|
||||
|
||||
|
|
@ -3424,11 +3602,15 @@
|
|||
|
||||
// Create Settings
|
||||
$.each( api.settings.settings, function( id, data ) {
|
||||
api.create( id, id, data.value, {
|
||||
var constructor = api.settingConstructor[ data.type ] || api.Setting,
|
||||
setting;
|
||||
|
||||
setting = new constructor( id, data.value, {
|
||||
transport: data.transport,
|
||||
previewer: api.previewer,
|
||||
dirty: !! data.dirty
|
||||
} );
|
||||
api.add( id, setting );
|
||||
});
|
||||
|
||||
// Create Panels
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -430,6 +430,7 @@
|
|||
args = $.extend( {}, control.defaultExpandedArguments, args );
|
||||
control.onChangeExpanded( expanded, args );
|
||||
});
|
||||
control.altNotice = true;
|
||||
|
||||
api.Control.prototype.initialize.call( control, id, options );
|
||||
},
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -654,19 +654,31 @@ final class WP_Customize_Manager {
|
|||
* Return the sanitized value for a given setting from the request's POST data.
|
||||
*
|
||||
* @since 3.4.0
|
||||
* @since 4.1.1 Introduced 'default' parameter.
|
||||
* @since 4.1.1 Introduced `$default` parameter.
|
||||
* @since 4.6.0 Return `$default` when setting post value is invalid.
|
||||
* @see WP_REST_Server::dispatch()
|
||||
* @see WP_Rest_Request::sanitize_params()
|
||||
* @see WP_Rest_Request::has_valid_params()
|
||||
*
|
||||
* @param WP_Customize_Setting $setting A WP_Customize_Setting derived object
|
||||
* @param mixed $default value returned $setting has no post value (added in 4.2.0).
|
||||
* @return string|mixed $post_value Sanitized value or the $default provided
|
||||
* @param WP_Customize_Setting $setting A WP_Customize_Setting derived object.
|
||||
* @param mixed $default Value returned $setting has no post value (added in 4.2.0)
|
||||
* or the post value is invalid (added in 4.6.0).
|
||||
* @return string|mixed $post_value Sanitized value or the $default provided.
|
||||
*/
|
||||
public function post_value( $setting, $default = null ) {
|
||||
$post_values = $this->unsanitized_post_values();
|
||||
if ( array_key_exists( $setting->id, $post_values ) ) {
|
||||
return $setting->sanitize( $post_values[ $setting->id ] );
|
||||
} else {
|
||||
if ( ! array_key_exists( $setting->id, $post_values ) ) {
|
||||
return $default;
|
||||
}
|
||||
$value = $setting->sanitize( $post_values[ $setting->id ] );
|
||||
if ( is_null( $value ) || is_wp_error( $value ) ) {
|
||||
return $default;
|
||||
}
|
||||
$valid = $setting->validate( $value );
|
||||
if ( is_wp_error( $valid ) ) {
|
||||
return $default;
|
||||
}
|
||||
return $value;
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
@ -969,6 +981,38 @@ final class WP_Customize_Manager {
|
|||
return $this->theme()->display('Name');
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate setting values.
|
||||
*
|
||||
* Sanitization is applied to the values before being passed for validation.
|
||||
* Validation is skipped for unregistered settings or for values that are
|
||||
* already null since they will be skipped anyway.
|
||||
*
|
||||
* @since 4.6.0
|
||||
* @access public
|
||||
* @see WP_REST_Request::has_valid_params()
|
||||
*
|
||||
* @param array $setting_values Mapping of setting IDs to values to sanitize and validate.
|
||||
* @return array Empty array if all settings were valid. One or more instances of `WP_Error` if any were invalid.
|
||||
*/
|
||||
public function validate_setting_values( $setting_values ) {
|
||||
$validity_errors = array();
|
||||
foreach ( $setting_values as $setting_id => $unsanitized_value ) {
|
||||
$setting = $this->get_setting( $setting_id );
|
||||
if ( ! $setting || is_null( $unsanitized_value ) ) {
|
||||
continue;
|
||||
}
|
||||
$validity = $setting->validate( $setting->sanitize( $unsanitized_value ) );
|
||||
if ( false === $validity || null === $validity ) {
|
||||
$validity = new WP_Error( 'invalid_value', __( 'Invalid value.' ) );
|
||||
}
|
||||
if ( is_wp_error( $validity ) ) {
|
||||
$validity_errors[ $setting_id ] = $validity;
|
||||
}
|
||||
}
|
||||
return $validity_errors;
|
||||
}
|
||||
|
||||
/**
|
||||
* Switch the theme and trigger the save() method on each setting.
|
||||
*
|
||||
|
|
@ -984,6 +1028,42 @@ final class WP_Customize_Manager {
|
|||
wp_send_json_error( 'invalid_nonce' );
|
||||
}
|
||||
|
||||
/**
|
||||
* Fires before save validation happens.
|
||||
*
|
||||
* Plugins can add just-in-time `customize_validate_{$setting_id}` filters
|
||||
* at this point to catch any settings registered after `customize_register`.
|
||||
*
|
||||
* @since 4.6.0
|
||||
*
|
||||
* @param WP_Customize_Manager $this WP_Customize_Manager instance.
|
||||
*/
|
||||
do_action( 'customize_save_validation_before', $this );
|
||||
|
||||
// Validate settings.
|
||||
$validity_errors = $this->validate_setting_values( $this->unsanitized_post_values() );
|
||||
$invalid_count = count( $validity_errors );
|
||||
if ( $invalid_count > 0 ) {
|
||||
$settings_errors = array();
|
||||
foreach ( $validity_errors as $setting_id => $validity_error ) {
|
||||
$settings_errors[ $setting_id ] = array();
|
||||
foreach ( $validity_error->errors as $error_code => $error_messages ) {
|
||||
$settings_errors[ $setting_id ][ $error_code ] = array(
|
||||
'message' => join( ' ', $error_messages ),
|
||||
'data' => $validity_error->get_error_data( $error_code ),
|
||||
);
|
||||
}
|
||||
}
|
||||
$response = array(
|
||||
'invalid_settings' => $settings_errors,
|
||||
'message' => sprintf( _n( 'There is %s invalid setting.', 'There are %s invalid settings.', $invalid_count ), number_format_i18n( $invalid_count ) ),
|
||||
);
|
||||
|
||||
/** This filter is documented in wp-includes/class-wp-customize-manager.php */
|
||||
$response = apply_filters( 'customize_save_response', $response, $this );
|
||||
wp_send_json_error( $response );
|
||||
}
|
||||
|
||||
// Do we have to switch themes?
|
||||
if ( ! $this->is_theme_active() ) {
|
||||
// Temporarily stop previewing the theme to allow switch_themes()
|
||||
|
|
@ -1403,6 +1483,15 @@ final class WP_Customize_Manager {
|
|||
) );
|
||||
$control->print_template();
|
||||
}
|
||||
?>
|
||||
<script type="text/html" id="tmpl-customize-control-notifications">
|
||||
<ul>
|
||||
<# _.each( data.notifications, function( notification ) { #>
|
||||
<li class="notice notice-{{ notification.type || 'info' }} {{ data.altNotice ? 'notice-alt' : '' }}" data-code="{{ notification.code }}" data-type="{{ notification.type }}">{{ notification.message || notification.code }}</li>
|
||||
<# } ); #>
|
||||
</ul>
|
||||
</script>
|
||||
<?php
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
@ -1763,11 +1852,7 @@ final class WP_Customize_Manager {
|
|||
printf(
|
||||
"s[%s] = %s;\n",
|
||||
wp_json_encode( $setting->id ),
|
||||
wp_json_encode( array(
|
||||
'value' => $setting->js_value(),
|
||||
'transport' => $setting->transport,
|
||||
'dirty' => $setting->dirty,
|
||||
) )
|
||||
wp_json_encode( $setting->json() )
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -59,6 +59,7 @@ class WP_Customize_Setting {
|
|||
*
|
||||
* @var callback
|
||||
*/
|
||||
public $validate_callback = '';
|
||||
public $sanitize_callback = '';
|
||||
public $sanitize_js_callback = '';
|
||||
|
||||
|
|
@ -142,6 +143,9 @@ class WP_Customize_Setting {
|
|||
$this->id .= '[' . implode( '][', $this->id_data['keys'] ) . ']';
|
||||
}
|
||||
|
||||
if ( $this->validate_callback ) {
|
||||
add_filter( "customize_validate_{$this->id}", $this->validate_callback, 10, 3 );
|
||||
}
|
||||
if ( $this->sanitize_callback ) {
|
||||
add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 );
|
||||
}
|
||||
|
|
@ -464,14 +468,16 @@ class WP_Customize_Setting {
|
|||
* the value of the setting.
|
||||
*
|
||||
* @since 3.4.0
|
||||
* @since 4.6.0 Return the result of updating the value.
|
||||
*
|
||||
* @return false|void False if cap check fails or value isn't set.
|
||||
* @return false|void False if cap check fails or value isn't set or is invalid.
|
||||
*/
|
||||
final public function save() {
|
||||
$value = $this->post_value();
|
||||
|
||||
if ( ! $this->check_capabilities() || ! isset( $value ) )
|
||||
if ( ! $this->check_capabilities() || ! isset( $value ) ) {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fires when the WP_Customize_Setting::save() method is called.
|
||||
|
|
@ -494,7 +500,7 @@ class WP_Customize_Setting {
|
|||
* @since 3.4.0
|
||||
*
|
||||
* @param mixed $default A default value which is used as a fallback. Default is null.
|
||||
* @return mixed The default value on failure, otherwise the sanitized value.
|
||||
* @return mixed The default value on failure, otherwise the sanitized and validated value.
|
||||
*/
|
||||
final public function post_value( $default = null ) {
|
||||
return $this->manager->post_value( $this, $default );
|
||||
|
|
@ -506,7 +512,7 @@ class WP_Customize_Setting {
|
|||
* @since 3.4.0
|
||||
*
|
||||
* @param string|array $value The value to sanitize.
|
||||
* @return string|array|null Null if an input isn't valid, otherwise the sanitized value.
|
||||
* @return string|array|null|WP_Error Sanitized value, or `null`/`WP_Error` if invalid.
|
||||
*/
|
||||
public function sanitize( $value ) {
|
||||
|
||||
|
|
@ -521,6 +527,45 @@ class WP_Customize_Setting {
|
|||
return apply_filters( "customize_sanitize_{$this->id}", $value, $this );
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate an input.
|
||||
*
|
||||
* @since 4.6.0
|
||||
* @access public
|
||||
* @see WP_REST_Request::has_valid_params()
|
||||
*
|
||||
* @param mixed $value Value to validate.
|
||||
* @return true|WP_Error
|
||||
*/
|
||||
public function validate( $value ) {
|
||||
if ( is_wp_error( $value ) ) {
|
||||
return $value;
|
||||
}
|
||||
if ( is_null( $value ) ) {
|
||||
return new WP_Error( 'invalid_value', __( 'Invalid value.' ) );
|
||||
}
|
||||
|
||||
$validity = new WP_Error();
|
||||
|
||||
/**
|
||||
* Validate a Customize setting value.
|
||||
*
|
||||
* Plugins should amend the `$validity` object via its `WP_Error::add()` method.
|
||||
*
|
||||
* @since 4.6.0
|
||||
*
|
||||
* @param WP_Error $validity Filtered from `true` to `WP_Error` when invalid.
|
||||
* @param mixed $value Value of the setting.
|
||||
* @param WP_Customize_Setting $this WP_Customize_Setting instance.
|
||||
*/
|
||||
$validity = apply_filters( "customize_validate_{$this->id}", $validity, $value, $this );
|
||||
|
||||
if ( is_wp_error( $validity ) && empty( $validity->errors ) ) {
|
||||
$validity = true;
|
||||
}
|
||||
return $validity;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the root value for a setting, especially for multidimensional ones.
|
||||
*
|
||||
|
|
@ -699,6 +744,22 @@ class WP_Customize_Setting {
|
|||
return $value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the data to export to the client via JSON.
|
||||
*
|
||||
* @since 4.6.0
|
||||
*
|
||||
* @return array Array of parameters passed to JavaScript.
|
||||
*/
|
||||
public function json() {
|
||||
return array(
|
||||
'value' => $this->js_value(),
|
||||
'transport' => $this->transport,
|
||||
'dirty' => $this->dirty,
|
||||
'type' => $this->type,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate user capabilities whether the theme supports the setting.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -755,6 +755,28 @@ window.wp = window.wp || {};
|
|||
// Add the Events mixin to api.Messenger.
|
||||
$.extend( api.Messenger.prototype, api.Events );
|
||||
|
||||
/**
|
||||
* Notification.
|
||||
*
|
||||
* @class
|
||||
* @augments wp.customize.Class
|
||||
* @since 4.6.0
|
||||
*
|
||||
* @param {string} code The error code.
|
||||
* @param {object} params Params.
|
||||
* @param {string} params.message The error message.
|
||||
* @param {string} [params.type=error] The notification type.
|
||||
* @param {*} [params.data] Any additional data.
|
||||
*/
|
||||
api.Notification = api.Class.extend({
|
||||
initialize: function( code, params ) {
|
||||
this.code = code;
|
||||
this.message = params.message;
|
||||
this.type = params.type || 'error';
|
||||
this.data = params.data || null;
|
||||
}
|
||||
});
|
||||
|
||||
// The main API object is also a collection of all customizer settings.
|
||||
api = $.extend( new api.Values(), api );
|
||||
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -4,7 +4,7 @@
|
|||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '4.6-alpha-37475';
|
||||
$wp_version = '4.6-alpha-37476';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
|
|
|||
Loading…
Reference in New Issue