← Back to branch summary

~canonical-sysadmins/wordpress/4.9

« back to all changes in this revision

Viewing changes to wp-includes/class-wp-customize-setting.php

  • Committer: Barry Price
  • Date: 2017-06-09 02:09:58 UTC
  • mfrom: (1.1.26 upstream)
  • Revision ID: barry.price@canonical.com-20170609020958-838whhwt2196f2vk
Merge WP4.8 from upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
wp-includes/class-wp-customize-setting.php
18
18
 */
19
19
class WP_Customize_Setting {
20
20
        /**
 
21
         * Customizer bootstrap instance.
 
22
         *
 
23
         * @since 3.4.0
21
24
         * @access public
22
25
         * @var WP_Customize_Manager
23
26
         */
26
29
        /**
27
30
         * Unique string identifier for the setting.
28
31
         *
 
32
         * @since 3.4.0
29
33
         * @access public
30
34
         * @var string
31
35
         */
32
36
        public $id;
33
37
 
34
38
        /**
 
39
         * Type of customize settings.
 
40
         *
 
41
         * @since 3.4.0
35
42
         * @access public
36
43
         * @var string
37
44
         */
40
47
        /**
41
48
         * Capability required to edit this setting.
42
49
         *
43
 
         * @var string
 
50
         * @since 3.4.0
 
51
         * @access public
 
52
         * @var string|array
44
53
         */
45
54
        public $capability = 'edit_theme_options';
46
55
 
47
56
        /**
48
57
         * Feature a theme is required to support to enable this setting.
49
58
         *
50
 
         * @access public
51
 
         * @var string
52
 
         */
53
 
        public $theme_supports  = '';
54
 
        public $default         = '';
55
 
        public $transport       = 'refresh';
56
 
 
57
 
        /**
58
 
         * Server-side sanitization callback for the setting's value.
59
 
         *
60
 
         * @var callback
61
 
         */
62
 
        public $validate_callback    = '';
63
 
        public $sanitize_callback    = '';
 
59
         * @since 3.4.0
 
60
         * @access public
 
61
         * @var string
 
62
         */
 
63
        public $theme_supports = '';
 
64
 
 
65
        /**
 
66
         * The default value for the setting.
 
67
         *
 
68
         * @since 3.4.0
 
69
         * @access public
 
70
         * @var string
 
71
         */
 
72
        public $default = '';
 
73
 
 
74
        /**
 
75
         * Options for rendering the live preview of changes in Theme Customizer.
 
76
         *
 
77
         * Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting
 
78
         * as opposed to reloading the whole page.
 
79
         *
 
80
         * @link https://developer.wordpress.org/themes/customize-api
 
81
         *
 
82
         * @since 3.4.0
 
83
         * @access public
 
84
         * @var string
 
85
         */
 
86
        public $transport = 'refresh';
 
87
 
 
88
        /**
 
89
         * Server-side validation callback for the setting's value.
 
90
         *
 
91
         * @since 4.6.0
 
92
         * @access public
 
93
         * @var callable
 
94
         */
 
95
        public $validate_callback = '';
 
96
 
 
97
        /**
 
98
         * Callback to filter a Customize setting value in un-slashed form.
 
99
         *
 
100
         * @since 3.4.0
 
101
         * @access public
 
102
         * @var callable
 
103
         */
 
104
        public $sanitize_callback = '';
 
105
 
 
106
        /**
 
107
         * Callback to convert a Customize PHP setting value to a value that is JSON serializable.
 
108
         *
 
109
         * @since 3.4.0
 
110
         * @access public
 
111
         * @var string
 
112
         */
64
113
        public $sanitize_js_callback = '';
65
114
 
66
115
        /**
78
127
        public $dirty = false;
79
128
 
80
129
        /**
 
130
         * ID Data.
 
131
         *
 
132
         * @since 3.4.0
 
133
         * @access protected
81
134
         * @var array
82
135
         */
83
136
        protected $id_data = array();
95
148
         * Cache of multidimensional values to improve performance.
96
149
         *
97
150
         * @since 4.4.0
98
 
         * @access protected
99
 
         * @var array
100
151
         * @static
 
152
         * @access protected
 
153
         * @var array
101
154
         */
102
155
        protected static $aggregated_multidimensionals = array();
103
156
 
168
221
         * Get parsed ID data for multidimensional setting.
169
222
         *
170
223
         * @since 4.4.0
171
 
         * @access public
172
224
         *
173
225
         * @return array {
174
226
         *     ID data for multidimensional setting.
188
240
         * calls get combined into one call, greatly improving performance.
189
241
         *
190
242
         * @since 4.4.0
191
 
         * @access protected
192
243
         */
193
244
        protected function aggregate_multidimensional() {
194
245
                $id_base = $this->id_data['base'];
216
267
         * This is intended only for use by unit tests.
217
268
         *
218
269
         * @since 4.5.0
219
 
         * @access public
220
270
         * @ignore
221
271
         */
222
272
        static public function reset_aggregated_multidimensionals() {
236
286
         * Return true if the current site is not the same as the previewed site.
237
287
         *
238
288
         * @since 4.2.0
239
 
         * @access public
240
289
         *
241
290
         * @return bool If preview() has been called.
242
291
         */
252
301
         *
253
302
         * @see WP_Customize_Setting::preview()
254
303
         * @since 4.1.1
 
304
         * @access protected
255
305
         * @var mixed
256
306
         */
257
307
        protected $_original_value;
265
315
         *
266
316
         * @since 3.4.0
267
317
         * @since 4.4.0 Added boolean return value.
268
 
         * @access public
269
318
         *
270
319
         * @return bool False when preview short-circuits due no change needing to be previewed.
271
320
         */
379
428
         * is called for this setting.
380
429
         *
381
430
         * @since 4.4.0
382
 
         * @access private
 
431
         *
383
432
         * @see WP_Customize_Manager::set_post_value()
384
433
         * @see WP_Customize_Setting::_multidimensional_preview_filter()
385
434
         */
426
475
         * the first setting previewed will be used to apply the values for the others.
427
476
         *
428
477
         * @since 4.4.0
429
 
         * @access private
430
478
         *
431
479
         * @see WP_Customize_Setting::$aggregated_multidimensionals
432
480
         * @param mixed $original Original root value.
469
517
         *
470
518
         * @since 3.4.0
471
519
         *
472
 
         * @access public
473
 
         *
474
520
         * @return false|void False if cap check fails or value isn't set or is invalid.
475
521
         */
476
522
        final public function save() {
480
526
                        return false;
481
527
                }
482
528
 
 
529
                $id_base = $this->id_data['base'];
 
530
 
483
531
                /**
484
532
                 * Fires when the WP_Customize_Setting::save() method is called.
485
533
                 *
486
 
                 * The dynamic portion of the hook name, `$this->id_data['base']` refers to
 
534
                 * The dynamic portion of the hook name, `$id_base` refers to
487
535
                 * the base slug of the setting name.
488
536
                 *
489
537
                 * @since 3.4.0
490
538
                 *
491
539
                 * @param WP_Customize_Setting $this WP_Customize_Setting instance.
492
540
                 */
493
 
                do_action( 'customize_save_' . $this->id_data['base'], $this );
 
541
                do_action( "customize_save_{$id_base}", $this );
494
542
 
495
543
                $this->update( $value );
496
544
        }
534
582
         * Validates an input.
535
583
         *
536
584
         * @since 4.6.0
537
 
         * @access public
538
585
         *
539
586
         * @see WP_REST_Request::has_valid_params()
540
587
         *
576
623
         * Get the root value for a setting, especially for multidimensional ones.
577
624
         *
578
625
         * @since 4.4.0
579
 
         * @access protected
580
626
         *
581
627
         * @param mixed $default Value to return if root does not exist.
582
628
         * @return mixed
601
647
         * Set the root value for a setting, especially for multidimensional ones.
602
648
         *
603
649
         * @since 4.4.0
604
 
         * @access protected
605
650
         *
606
651
         * @param mixed $value Value to set as root of multidimensional setting.
607
652
         * @return bool Whether the multidimensional root was updated successfully.
768
813
         * Retrieves the data to export to the client via JSON.
769
814
         *
770
815
         * @since 4.6.0
771
 
         * @access public
772
816
         *
773
817
         * @return array Array of parameters passed to JavaScript.
774
818
         */
905
949
        }
906
950
}
907
951
 
908
 
/** WP_Customize_Filter_Setting class */
 
952
/**
 
953
 * WP_Customize_Filter_Setting class.
 
954
 */
909
955
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-filter-setting.php' );
910
956
 
911
 
/** WP_Customize_Header_Image_Setting class */
 
957
/**
 
958
 * WP_Customize_Header_Image_Setting class.
 
959
 */
912
960
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-setting.php' );
913
961
 
914
 
/** WP_Customize_Background_Image_Setting class */
 
962
/**
 
963
 * WP_Customize_Background_Image_Setting class.
 
964
 */
915
965
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-setting.php' );
916
966
 
917
 
/** WP_Customize_Nav_Menu_Item_Setting class */
 
967
/**
 
968
 * WP_Customize_Nav_Menu_Item_Setting class.
 
969
 */
918
970
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-setting.php' );
919
971
 
920
 
/** WP_Customize_Nav_Menu_Setting class */
 
972
/**
 
973
 * WP_Customize_Nav_Menu_Setting class.
 
974
 */
921
975
require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-setting.php' );