Changeset 40804 for trunk/src/wp-includes/class-wp-customize-setting.php

Timestamp:

05/19/2017 08:24:58 PM (8 years ago)

Author:

westonruter

Message:

Docs: Improve phpdoc for WP_Customize_Manager, WP_Customize_Control, WP_Customize_Setting, and WP_Customize_Selective_Refresh.

Props 4nickpick, sagarprajapati, ketuchetan, BharatKambariya, mrahmadawais, westonruter.
Fixes #39671.

File:

• trunk/src/wp-includes/class-wp-customize-setting.php (modified) (20 diffs)

trunk/src/wp-includes/class-wp-customize-setting.php

@@ -19 +19 @@
 class WP_Customize_Setting {
     /**
+     * Customizer bootstrap instance.
+     *
+     * @since 3.4.0
      * @access public
      * @var WP_Customize_Manager
@@ -27 +30 @@
      * Unique string identifier for the setting.
      *
+     * @since 3.4.0
      * @access public
      * @var string
@@ -33 +37 @@
 
     /**
+     * Type of customize settings.
+     *
+     * @since 3.4.0
      * @access public
      * @var string
@@ -41 +48 @@
      * Capability required to edit this setting.
      *
+     * @since 3.4.0
+     * @access public
+     * @var string|array
+     */
+    public $capability = 'edit_theme_options';
+
+    /**
+     * Feature a theme is required to support to enable this setting.
+     *
+     * @since 3.4.0
+     * @access public
      * @var string
      */
-    public $capability = 'edit_theme_options';
-
-    /**
-     * Feature a theme is required to support to enable this setting.
-     *
+    public $theme_supports = '';
+
+    /**
+     * The default value for the setting.
+     *
+     * @since 3.4.0
      * @access public
      * @var string
      */
-    public $theme_supports  = '';
-    public $default         = '';
-    public $transport       = 'refresh';
-
-    /**
-     * Server-side sanitization callback for the setting's value.
-     *
-     * @var callback
-     */
-    public $validate_callback    = '';
-    public $sanitize_callback    = '';
+    public $default = '';
+
+    /**
+     * Options for rendering the live preview of changes in Theme Customizer.
+     *
+     * Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting
+     * as opposed to reloading the whole page.
+     *
+     * @link https://developer.wordpress.org/themes/customize-api
+     *
+     * @since 3.4.0
+     * @access public
+     * @var string
+     */
+    public $transport = 'refresh';
+
+    /**
+     * Server-side validation callback for the setting's value.
+     *
+     * @since 4.6.0
+     * @access public
+     * @var callable
+     */
+    public $validate_callback = '';
+
+    /**
+     * Callback to filter a Customize setting value in un-slashed form.
+     *
+     * @since 3.4.0
+     * @access public
+     * @var callable
+     */
+    public $sanitize_callback = '';
+
+    /**
+     * Callback to convert a Customize PHP setting value to a value that is JSON serializable.
+     *
+     * @since 3.4.0
+     * @access public
+     * @var string
+     */
     public $sanitize_js_callback = '';
 
@@ -79 +128 @@
 
     /**
+     * ID Data.
+     *
+     * @since 3.4.0
+     * @access protected
      * @var array
      */
@@ -96 +149 @@
      *
      * @since 4.4.0
+     * @static
      * @access protected
      * @var array
-     * @static
      */
     protected static $aggregated_multidimensionals = array();
@@ -169 +222 @@
      *
      * @since 4.4.0
-     * @access public
      *
      * @return array {
@@ -189 +241 @@
      *
      * @since 4.4.0
-     * @access protected
      */
     protected function aggregate_multidimensional() {
@@ -217 +268 @@
      *
      * @since 4.5.0
-     * @access public
      * @ignore
      */
@@ -237 +287 @@
      *
      * @since 4.2.0
-     * @access public
      *
      * @return bool If preview() has been called.
@@ -253 +302 @@
      * @see WP_Customize_Setting::preview()
      * @since 4.1.1
+     * @access protected
      * @var mixed
      */
@@ -266 +316 @@
      * @since 3.4.0
      * @since 4.4.0 Added boolean return value.
-     * @access public
      *
      * @return bool False when preview short-circuits due no change needing to be previewed.
@@ -380 +429 @@
      *
      * @since 4.4.0
-     * @access private
+     *
      * @see WP_Customize_Manager::set_post_value()
      * @see WP_Customize_Setting::_multidimensional_preview_filter()
@@ -427 +476 @@
      *
      * @since 4.4.0
-     * @access private
      *
      * @see WP_Customize_Setting::$aggregated_multidimensionals
@@ -470 +518 @@
      * @since 3.4.0
      *
-     * @access public
-     *
      * @return false|void False if cap check fails or value isn't set or is invalid.
      */
@@ -537 +583 @@
      *
      * @since 4.6.0
-     * @access public
      *
      * @see WP_REST_Request::has_valid_params()
@@ -579 +624 @@
      *
      * @since 4.4.0
-     * @access protected
      *
      * @param mixed $default Value to return if root does not exist.
@@ -604 +648 @@
      *
      * @since 4.4.0
-     * @access protected
      *
      * @param mixed $value Value to set as root of multidimensional setting.
@@ -771 +814 @@
      *
      * @since 4.6.0
-     * @access public
      *
      * @return array Array of parameters passed to JavaScript.
@@ -908 +950 @@
 }
 
-/** WP_Customize_Filter_Setting class */
+/**
+ * WP_Customize_Filter_Setting class.
+ */
 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-filter-setting.php' );
 
-/** WP_Customize_Header_Image_Setting class */
+/**
+ * WP_Customize_Header_Image_Setting class.
+ */
 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-setting.php' );
 
-/** WP_Customize_Background_Image_Setting class */
+/**
+ * WP_Customize_Background_Image_Setting class.
+ */
 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-setting.php' );
 
-/** WP_Customize_Nav_Menu_Item_Setting class */
+/**
+ * WP_Customize_Nav_Menu_Item_Setting class.
+ */
 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-setting.php' );
 
-/** WP_Customize_Nav_Menu_Setting class */
+/**
+ * WP_Customize_Nav_Menu_Setting class.
+ */
 require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-setting.php' );