[wp-trac] [WordPress Trac] #37274: Facilitate updating/extending Customizer setting values that are objects

[WordPress Trac]

#37274: Facilitate updating/extending Customizer setting values that are objects
-------------------------+----------------------------
 Reporter:  westonruter  |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Future Release
Component:  Customize    |    Version:  3.4
 Severity:  normal       |   Keywords:
  Focuses:  javascript   |
-------------------------+----------------------------
 There is bit of a dance to work with setting values that are objects.

 Consider a `mailing_address` setting that represents a street address:

 {{{#!json
 {
     "street": "123 Fictional St.",
     "city": "Portland",
     "state": "OR",
     "zip": "97201"
 }
 }}}

 Getting the value is as simple as `wp.customize( 'mailing_address'
 ).get()`, but updating the value is not so simple. To change the `street`
 part of this setting, the following is required:

 {{{#!js
 var value = wp.customize( 'mailing_address' ).get();
 value = _.clone( value );
 value.street = '123 Imaginary Ave';
 wp.customize( 'mailing_address' ).set( value );
 }}}

 The clone is required because objects are passed by reference, and if the
 `value` were to set directly, the subsequent `set` would not trigger a
 `change` event.

 Widgets and nav menus use objects as values in Core. Widgets aren't
 manipulated directly in JS (until #33507) but nav menus and nav menu items
 are. Here's the code for managing how a nav menu's name gets changed when
 the nav menu's name field is updated:

 {{{#!js
 control.nameElement.bind(function( value ) {
         var settingValue = control.setting();
         if ( settingValue && settingValue.name !== value ) {
                 settingValue = _.clone( settingValue );
                 settingValue.name = value;
                 control.setting.set( settingValue );
         }
 });
 }}}

 To make it easier to work with setting values as objects, we could
 introduce a `wp.customize.Value#setExtend` method that allows an object
 value to be extended in the same way that `setState` works in React, take
 an object of key/value pairs that are merged on top of the existing value.

 Here is an example implementation:

 {{{#!js
 wp.customize.Value.prototype.setExtend = function( props ) {
     var value = _.clone( this.get() );
     _.extend( value, props );
     this.set( value );
 };
 }}}

 With this, to update the `mailing_address` setting value property in the
 above example could be changed to simply:

 {{{#!js
 wp.customize( 'mailing_address' ).setExtend( { street: '123 Imaginary Ave'
 } )
 }}}

 See also #26061.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/37274>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform