[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       |  Resolution:
 Keywords:               |     Focuses:  javascript
-------------------------+-----------------------------
Description changed by westonruter:

Old description:

> 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.

New description:

 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 #26061.
 Related #37275.

--

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