Make WordPress Core

Opened 10 months ago

Last modified 7 months ago

#37275 new enhancement

Facilitate creating controls that manipulate settings with object values

Reported by: westonruter Owned by:
Milestone: Future Release Priority: low
Severity: normal Version: 3.4
Component: Customize Keywords: needs-patch
Focuses: Cc:


While #37274 addresses the difficulty to manipulate updating settings that have object values, the Customizer JS API also does not facilitate creating controls that have fields which manage a setting that has a object value.

The MenuNameControl provides a good example of a control that has a text field for managing a nav menu setting's name property:

control.nameElement = new api.Element( control.container.find( '.menu-name-field' ) );
control.nameElement.bind(function( value ) {
        var settingValue = control.setting();
        if ( settingValue && settingValue.name !== value ) {
                settingValue = _.clone( settingValue );
                settingValue.name = value;
                control.setting.set( settingValue );
control.setting.bind(function( object ) {
        control.nameElement.set( object.name );

This works but it is tedious when scaling and makes it difficult to extend, as can be seen in the MenuItemControl. There should be a more declarative way to link a field to a property of a setting value object. One implementation of this can be seen in the Dynamic control as seen in the Customize Posts plugin. While Core supports a data-customize-setting-link attribute in a control template to declaratively link an input field to a setting value, the Dynamic control Dynamic adds support for a data-customize-setting-property-link attribute which will link the input field to the a property of the (default) setting. This eliminates the need for custom JS logic to link the input elements.

See an example control which has fields which manipulate a setting value containing a street address: https://github.com/xwp/standalone-customizer-controls/blob/master/class-customize-address-control.php

This will facilitate extending nav menu items in the Customizer: #18584.

Change History (4)

#1 @westonruter
10 months ago

  • Summary changed from Facilitate creating controls that manipulate settings that have object values to Facilitate creating controls that manipulate settings with object values

#2 @westonruter
8 months ago

Instead of data-customize-setting-property-link I think it would be better if the existing data-customize-setting-link supported multidimensional paths. For example, let's say a control is associated with a setting which represents a WP_Post object with a setting ID. Then a textarea control could be added with the field element having data-customize-setting-link="default[post_content]" to link it to the property of the default setting, which here would be something like post[page][123]. This is better over the existing implementation in Customize Posts for data-customize-setting-property-link in that it will continue to allow us to associate a control with multiple settings, as opposed to introducing a limitation whereby only one setting's properties can be synced with.

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.

7 months ago

#4 @celloexpressions
7 months ago

  • Keywords needs-patch added
  • Priority changed from normal to low

This would be nice to have if there's time in a future release.

Note: See TracTickets for help on using tickets.