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.