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
Adds parity with setting instance being passed as second argument to `customize_sanitize_{$id}` and `customize_sanitize_js_{$id}`. Allows the actual ID of the (multidimensional) setting value being filtered to be inspected.
Props celloexpressions, westonruter.
Fixes#36452.
Built from https://develop.svn.wordpress.org/trunk@37350
git-svn-id: http://core.svn.wordpress.org/trunk@37316 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Known functions, classes, and methods are now auto-linked in Code Reference pages following #meta1483.
Note: Hook references are still linked via inline `@see` tags due to the unlikelihood of reliably matching for known hooks based on a RegEx pattern.
See #32246.
Built from https://develop.svn.wordpress.org/trunk@37342
git-svn-id: http://core.svn.wordpress.org/trunk@37308 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Theme support for `customize-selective-refresh-widgets` can be added _after_ the logic for registering the settings for incoming widgets that have been changed. This is due to themes adding the theme support in `after_setup_theme` which is also the action where `WP_Customize_Widgets::register_settings()` is called. If these both happen at priority 10, which one is called first depends on which one was added first. The other issue is that at the time that `WP_Customize_Widgets::register_settings()` is called at `after_setup_theme`, it is called before `widgets_init` and thus no widgets are yet registered. This means that any settings registered at this point will always have a `refresh` transport even if the theme supports `customize-selective-refresh-widgets`, since the `WP_Widget` instance is not visible yet to see if it supports selective refresh.
The fix: Defer `WP_Customize_Widgets::register_settings()` from `after_setup_theme` to `widgets_init` at priority 95 when the widget objects have all been registered. Also, ensure that the preview filter for `sidebars_widgets` is added before the sidebars are iterated for adding the controls.
Props westonruter.
Fixes#36389.
Built from https://develop.svn.wordpress.org/trunk@37166
git-svn-id: http://core.svn.wordpress.org/trunk@37133 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Ensures that intentional backslashes (e.g. "\o/") can be used in:
* Site title
* Site description
* Nav menu name
* Custom Menu widget title
* Tag Cloud widget title
* Text widget body if can't `unfiltered_html`
The latter three are also fixed on the widgets admin page.
Fixes#35898.
Built from https://develop.svn.wordpress.org/trunk@36622
git-svn-id: http://core.svn.wordpress.org/trunk@36589 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Multisite functions use the term "blog" to refer to what we now call a "site," e.g. `get_current_blog_id()`. These functions are here to stay because of our commitment to backwards compatibility. What we can do is set the documentation straight.
See #35417.
Built from https://develop.svn.wordpress.org/trunk@36416
git-svn-id: http://core.svn.wordpress.org/trunk@36383 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* Introduce `customize_post_value_set_{$setting_id}` and `customize_post_value_set` actions which are done when `WP_Customize_Manager::set_post_value()` is called.
* Clear the `preview_applied` flag for aggregated multidimensional settings when a post value is set. This ensures the new value is used instead of a previously-cached previewed value.
* Move `$is_preview` property from subclasses to `WP_Customize_Setting` parent class.
* Deferred preview: Ensure that when `preview()` short-circuits due to not being applicable that it will be called again later when the post value is set.
* Populate post value for updated-widget with the (unsanitized) JS-value in `WP_Customize_Widgets::call_widget_update()` so that value will be properly sanitized when accessed in `WP_Customize_Manager::post_value()`.
Includes unit tests with assertions to check the reported issues and validate the fixes.
Fixes defect introduced in [35007].
See #32103.
Fixes#34738.
Built from https://develop.svn.wordpress.org/trunk@35724
git-svn-id: http://core.svn.wordpress.org/trunk@35688 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Since `wp_setup_nav_menu_item()` returns the `classes` property as an array but the Customizer manages the value as a string, the setting needs to initially export the value as a string. This prevents the `classes` property type change from causing the setting to get marked as dirty even though nothing changed. This is a regression from [34788].
See #34111.
Built from https://develop.svn.wordpress.org/trunk@35308
git-svn-id: http://core.svn.wordpress.org/trunk@35274 1a063a9b-81f0-0310-95a4-ce76da25c4cd
The same indicator on the nav menus admin page is now present for nav menu items in the Customizer. When a menu item is present for a post type that is no longer registered, the menu item will appear with the indicator.
Props kucrut, westonruter.
Fixes#33665.
Built from https://develop.svn.wordpress.org/trunk@35302
git-svn-id: http://core.svn.wordpress.org/trunk@35268 1a063a9b-81f0-0310-95a4-ce76da25c4cd
As the number of multidimensional settings (serialized options and theme mods) increase for a given ID base (e.g. a widget of a certain type), the number of calls to the `multidimensional` methods on `WP_Customize_Setting` increase exponentially, and the time for the preview to refresh grows in time exponentially as well.
To improve performance, this change reduces the number of filters needed to preview the settings off of a multidimensional root from N to 1. This improves performance from `O(n^2)` to `O(n)`, but the linear increase is so low that the performance is essentially `O(1)` in comparison. This is achieved by introducing the concept of an "aggregated multidimensional" setting, where the root value of the multidimensional serialized setting value gets cached in a static array variable shared across all settings.
Also improves performance by only adding preview filters if there is actually a need to do so: there is no need to add a filter if there is an initial value and if there is no posted value for a given setting (if it is not dirty).
Fixes#32103.
Built from https://develop.svn.wordpress.org/trunk@35007
git-svn-id: http://core.svn.wordpress.org/trunk@34972 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* Ensure that a Custom Menu widget selecting a newly-inserted menu gets updated to use the new menu ID upon Save & Publish.
* Dynamically update the visibility of the Custom Menu widget's "no menus" message when the number of menus changes between 0 and 1+.
* Send all dirty Customized settings in `update-widget` Ajax request and `preview()` them so that the widget update/form callbacks have access to any data dependencies in the current Customizer session (such as newly created unsaved menus).
* Update link in Custom Menu widget to point to Menus panel as opposed to Menus admin page, when in the Customizer.
* Fix an issue with extra space at top immediately after creating new menu.
* Fix doubled `update-widget` Ajax requests when changing select dropdown; prevent initial from being aborted.
* Add missing `wp_get_nav_menus()` hooks to preview Customizer updates/inserts for `nav_menu` settings; includes tests.
* Update `wp_get_nav_menu_object()` to allow a menu object to be passed in (and thus passed through).
Props westonruter, adamsilverstein.
Fixes#32814.
Built from https://develop.svn.wordpress.org/trunk@33488
git-svn-id: http://core.svn.wordpress.org/trunk@33455 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Adds validation for initially-supplied nav menu name, blocking empty names from being supplied. If later an empty name is supplied and the nav menu is saved, the name "(unnamed)" will be supplied instead and supplied back to the client. If a name is supplied for the menu which is currently used by another menu, then the name conflict is resolved by adding a numerical counter similar to how `post_name` conflicts are resolved. Includes unit tests.
Fixes#32760.
Built from https://develop.svn.wordpress.org/trunk@33071
git-svn-id: http://core.svn.wordpress.org/trunk@33042 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* Unset `wp_get_sidebars_widgets()`' non-admin cache var `$_wp_sidebars_widgets` in Customize theme preview.
* Add `WP_Customize_Setting::$dirty` so that settings can be initially-dirty when the Customizer loads.
* Mark `old_sidebars_widgets_data` setting initially-dirty.
* Mark all `sidebars_widgets` settings as initially-dirty during theme switch.
props westonruter.
see #31484.
Built from https://develop.svn.wordpress.org/trunk@31705
git-svn-id: http://core.svn.wordpress.org/trunk@31686 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* Adds a file header separate from the `WP_Customize_Setting` class block
* Fixes formatting for the `WP_Customize_Setting`, `WP_Customize_Filter_Setting`, `WP_Customize_Header_Image_Setting`, and `WP_Customize_Background_Image_Setting` class DocBlocks.
See #31446.
Built from https://develop.svn.wordpress.org/trunk@31543
git-svn-id: http://core.svn.wordpress.org/trunk@31524 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* Introduce WP_Customize_Manager::add_dynamic_settings() to register dynamically-created settings.
* Introduce `customize_dynamic_setting_args` filter to pass an array of args to a dynamic setting's constructor.
* Add unit tests for WP_Customize_Manager and WP_Customize_Widgets.
* See WP_Customize_Widgets as an example.
props westonruter.
fixes#30936.
Built from https://develop.svn.wordpress.org/trunk@31370
git-svn-id: http://core.svn.wordpress.org/trunk@31351 1a063a9b-81f0-0310-95a4-ce76da25c4cd
There was regression introduced by #28580 where only changed (dirty) settings now are POST'ed to the Customizer preview.
* Allow WP_Customize_Manager::post_value() to accept a second $default argument.
* Introduce WP_Customize_Manager::unsanitized_post_values() for accessing previously-private member variable _post_values.
* Do require_once instead of require for Customizer classes.
* Add unit tests for WP_Customize_Manager and WP_Customize_Setting.
props westonruter.
fixes#30988.
Built from https://develop.svn.wordpress.org/trunk@31329
git-svn-id: http://core.svn.wordpress.org/trunk@31310 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Per our inline documentation standards, no further use of the `@uses` tag is recommended as used and used-by relationships can be derived through other means. This removes most uses of the tag in core documentation, with remaining tags to be converted to `@global` or `@see` as they apply.
Fixes#30191.
Built from https://develop.svn.wordpress.org/trunk@30105
git-svn-id: http://core.svn.wordpress.org/trunk@30105 1a063a9b-81f0-0310-95a4-ce76da25c4cd
John Blackbourn
Drew Jaynes
Weston Ruter
Dominik Schilling
Eric Lewis
Scott Taylor
Aaron Jorbin
Sergey Biryukov