WordPress.org

Make WordPress Core

Changeset 40804


Ignore:
Timestamp:
05/19/17 20:24:58 (5 months 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.

Location:
trunk/src/wp-includes
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-customize-control.php

    r39345 r40804  
    3838 
    3939    /** 
     40     * Customizer manager. 
     41     * 
     42     * @since 3.4.0 
    4043     * @access public 
    4144     * @var WP_Customize_Manager 
     
    4447 
    4548    /** 
     49     * Control ID. 
     50     * 
     51     * @since 3.4.0 
    4652     * @access public 
    4753     * @var string 
     
    5258     * All settings tied to the control. 
    5359     * 
     60     * @since 3.4.0 
    5461     * @access public 
    5562     * @var array 
     
    6067     * The primary setting for the control (if there is one). 
    6168     * 
     69     * @since 3.4.0 
    6270     * @access public 
    6371     * @var string 
     
    7886 
    7987    /** 
     88     * Order priority to load the control in Customizer. 
     89     * 
     90     * @since 3.4.0 
    8091     * @access public 
    8192     * @var int 
     
    8495 
    8596    /** 
     97     * Section the control belongs to. 
     98     * 
     99     * @since 3.4.0 
    86100     * @access public 
    87101     * @var string 
     
    90104 
    91105    /** 
     106     * Label for the control. 
     107     * 
     108     * @since 3.4.0 
    92109     * @access public 
    93110     * @var string 
     
    96113 
    97114    /** 
     115     * Description for the control. 
     116     * 
     117     * @since 4.0.0 
    98118     * @access public 
    99119     * @var string 
     
    102122 
    103123    /** 
    104      * @todo: Remove choices 
    105      * 
     124     * List of choices for 'radio' or 'select' type controls, where values are the keys, and labels are the values. 
     125     * 
     126     * @since 3.4.0 
    106127     * @access public 
    107128     * @var array 
     
    110131 
    111132    /** 
     133     * List of custom input attributes for control output, where attribute names are the keys and values are the values. 
     134     * 
     135     * Not used for 'checkbox', 'radio', 'select', 'textarea', or 'dropdown-pages' control types. 
     136     * 
     137     * @since 4.0.0 
    112138     * @access public 
    113139     * @var array 
     
    126152    /** 
    127153     * @deprecated It is better to just call the json() method 
     154     * @since 3.4.0 
    128155     * @access public 
    129156     * @var array 
     
    132159 
    133160    /** 
     161     * Control's Type. 
     162     * 
     163     * @since 3.4.0 
    134164     * @access public 
    135165     * @var string 
     
    236266     * 
    237267     * @since 4.0.0 
    238      * @access public 
    239268     * 
    240269     * @return bool Whether the control is active to the current preview. 
     
    264293     * 
    265294     * @since 4.0.0 
    266      * @access public 
    267295     * 
    268296     * @return true Always true. 
     
    447475     * 
    448476     * @since 4.0.0 
    449      * @access public 
    450477     */ 
    451478    public function input_attrs() { 
     
    649676} 
    650677 
    651 /** WP_Customize_Color_Control class */ 
     678/** 
     679 * WP_Customize_Color_Control class. 
     680 */ 
    652681require_once( ABSPATH . WPINC . '/customize/class-wp-customize-color-control.php' ); 
    653682 
    654 /** WP_Customize_Media_Control class */ 
     683/** 
     684 * WP_Customize_Media_Control class. 
     685 */ 
    655686require_once( ABSPATH . WPINC . '/customize/class-wp-customize-media-control.php' ); 
    656687 
    657 /** WP_Customize_Upload_Control class */ 
     688/** 
     689 * WP_Customize_Upload_Control class. 
     690 */ 
    658691require_once( ABSPATH . WPINC . '/customize/class-wp-customize-upload-control.php' ); 
    659692 
    660 /** WP_Customize_Image_Control class */ 
     693/** 
     694 * WP_Customize_Image_Control class. 
     695 */ 
    661696require_once( ABSPATH . WPINC . '/customize/class-wp-customize-image-control.php' ); 
    662697 
    663 /** WP_Customize_Background_Image_Control class */ 
     698/** 
     699 * WP_Customize_Background_Image_Control class. 
     700 */ 
    664701require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-control.php' ); 
    665702 
    666 /** WP_Customize_Background_Position_Control class */ 
     703/** 
     704 * WP_Customize_Background_Position_Control class. 
     705 */ 
    667706require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-position-control.php' ); 
    668707 
    669 /** WP_Customize_Cropped_Image_Control class */ 
     708/** 
     709 * WP_Customize_Cropped_Image_Control class. 
     710 */ 
    670711require_once( ABSPATH . WPINC . '/customize/class-wp-customize-cropped-image-control.php' ); 
    671712 
    672 /** WP_Customize_Site_Icon_Control class */ 
     713/** 
     714 * WP_Customize_Site_Icon_Control class. 
     715 */ 
    673716require_once( ABSPATH . WPINC . '/customize/class-wp-customize-site-icon-control.php' ); 
    674717 
    675 /** WP_Customize_Header_Image_Control class */ 
     718/** 
     719 * WP_Customize_Header_Image_Control class. 
     720 */ 
    676721require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-control.php' ); 
    677722 
    678 /** WP_Customize_Theme_Control class */ 
     723/** 
     724 * WP_Customize_Theme_Control class. 
     725 */ 
    679726require_once( ABSPATH . WPINC . '/customize/class-wp-customize-theme-control.php' ); 
    680727 
    681 /** WP_Widget_Area_Customize_Control class */ 
     728/** 
     729 * WP_Widget_Area_Customize_Control class. 
     730 */ 
    682731require_once( ABSPATH . WPINC . '/customize/class-wp-widget-area-customize-control.php' ); 
    683732 
    684 /** WP_Widget_Form_Customize_Control class */ 
     733/** 
     734 * WP_Widget_Form_Customize_Control class. 
     735 */ 
    685736require_once( ABSPATH . WPINC . '/customize/class-wp-widget-form-customize-control.php' ); 
    686737 
    687 /** WP_Customize_Nav_Menu_Control class */ 
     738/** 
     739 * WP_Customize_Nav_Menu_Control class. 
     740 */ 
    688741require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-control.php' ); 
    689742 
    690 /** WP_Customize_Nav_Menu_Item_Control class */ 
     743/** 
     744 * WP_Customize_Nav_Menu_Item_Control class. 
     745 */ 
    691746require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-control.php' ); 
    692747 
    693 /** WP_Customize_Nav_Menu_Location_Control class */ 
     748/** 
     749 * WP_Customize_Nav_Menu_Location_Control class. 
     750 */ 
    694751require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-location-control.php' ); 
    695752 
    696 /** WP_Customize_Nav_Menu_Name_Control class */ 
     753/** 
     754 * WP_Customize_Nav_Menu_Name_Control class. 
     755 */ 
    697756require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-name-control.php' ); 
    698757 
    699 /** WP_Customize_Nav_Menu_Auto_Add_Control class */ 
     758/** 
     759 * WP_Customize_Nav_Menu_Auto_Add_Control class. 
     760 */ 
    700761require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-auto-add-control.php' ); 
    701762 
    702 /** WP_Customize_New_Menu_Control class */ 
     763/** 
     764 * WP_Customize_New_Menu_Control class. 
     765 */ 
    703766require_once( ABSPATH . WPINC . '/customize/class-wp-customize-new-menu-control.php' ); 
  • trunk/src/wp-includes/class-wp-customize-manager.php

    r40704 r40804  
    28112811     * @since 3.4.0 
    28122812     * @since 4.5.0 Return added WP_Customize_Setting instance. 
    2813      * @access public 
    28142813     * 
    28152814     * @param WP_Customize_Setting|string $id   Customize Setting object, or ID. 
    2816      * @param array                       $args Setting arguments; passed to WP_Customize_Setting 
    2817      *                                          constructor. 
     2815     * @param array                       $args { 
     2816     *  Optional. Array of properties for the new WP_Customize_Setting. Default empty array. 
     2817     * 
     2818     *  @type string       $type                  Type of the setting. Default 'theme_mod'. 
     2819     *                                            Default 160. 
     2820     *  @type string       $capability            Capability required for the setting. Default 'edit_theme_options' 
     2821     *  @type string|array $theme_supports        Theme features required to support the panel. Default is none. 
     2822     *  @type string       $default               Default value for the setting. Default is empty string. 
     2823     *  @type string       $transport             Options for rendering the live preview of changes in Theme Customizer. 
     2824     *                                            Using 'refresh' makes the change visible by reloading the whole preview. 
     2825     *                                            Using 'postMessage' allows a custom JavaScript to handle live changes. 
     2826     *                                            @link https://developer.wordpress.org/themes/customize-api 
     2827     *                                            Default is 'refresh' 
     2828     *  @type callable     $validate_callback     Server-side validation callback for the setting's value. 
     2829     *  @type callable     $sanitize_callback     Callback to filter a Customize setting value in un-slashed form. 
     2830     *  @type callable     $sanitize_js_callback  Callback to convert a Customize PHP setting value to a value that is 
     2831     *                                            JSON serializable. 
     2832     *  @type bool         $dirty                 Whether or not the setting is initially dirty when created. 
     2833     * } 
    28182834     * @return WP_Customize_Setting             The instance of the setting that was added. 
    28192835     */ 
     
    29292945     * @since 4.0.0 
    29302946     * @since 4.5.0 Return added WP_Customize_Panel instance. 
    2931      * @access public 
    29322947     * 
    29332948     * @param WP_Customize_Panel|string $id   Customize Panel object, or Panel ID. 
    2934      * @param array                     $args Optional. Panel arguments. Default empty array. 
    2935      * 
     2949     * @param array                     $args { 
     2950     *  Optional. Array of properties for the new Panel object. Default empty array. 
     2951     *  @type int          $priority              Priority of the panel, defining the display order of panels and sections. 
     2952     *                                            Default 160. 
     2953     *  @type string       $capability            Capability required for the panel. Default `edit_theme_options` 
     2954     *  @type string|array $theme_supports        Theme features required to support the panel. 
     2955     *  @type string       $title                 Title of the panel to show in UI. 
     2956     *  @type string       $description           Description to show in the UI. 
     2957     *  @type string       $type                  Type of the panel. 
     2958     *  @type callable     $active_callback       Active callback. 
     2959     * } 
    29362960     * @return WP_Customize_Panel             The instance of the panel that was added. 
    29372961     */ 
     
    30213045     * 
    30223046     * @param WP_Customize_Section|string $id   Customize Section object, or Section ID. 
    3023      * @param array                       $args Section arguments. 
    3024      * 
     3047     * @param array                     $args { 
     3048     *  Optional. Array of properties for the new Panel object. Default empty array. 
     3049     *  @type int          $priority              Priority of the panel, defining the display order of panels and sections. 
     3050     *                                            Default 160. 
     3051     *  @type string       $panel                 Priority of the panel, defining the display order of panels and sections. 
     3052     *  @type string       $capability            Capability required for the panel. Default 'edit_theme_options' 
     3053     *  @type string|array $theme_supports        Theme features required to support the panel. 
     3054     *  @type string       $title                 Title of the panel to show in UI. 
     3055     *  @type string       $description           Description to show in the UI. 
     3056     *  @type string       $type                  Type of the panel. 
     3057     *  @type callable     $active_callback       Active callback. 
     3058     *  @type bool         $description_hidden    Hide the description behind a help icon, instead of . Default false. 
     3059     * } 
    30253060     * @return WP_Customize_Section             The instance of the section that was added. 
    30263061     */ 
     
    30973132     * 
    30983133     * @param WP_Customize_Control|string $id   Customize Control object, or ID. 
    3099      * @param array                       $args Control arguments; passed to WP_Customize_Control 
    3100      *                                          constructor. 
     3134     * @param array                       $args { 
     3135     *  Optional. Array of properties for the new Control object. Default empty array. 
     3136     * 
     3137     *  @type array        $settings              All settings tied to the control. If undefined, defaults to `$setting`. 
     3138     *                                            IDs in the array correspond to the ID of a registered `WP_Customize_Setting`. 
     3139     *  @type string       $setting               The primary setting for the control (if there is one). Default is 'default'. 
     3140     *  @type string       $capability            Capability required to use this control. Normally derived from `$settings`. 
     3141     *  @type int          $priority              Order priority to load the control. Default 10. 
     3142     *  @type string       $section               The section this control belongs to. Default empty. 
     3143     *  @type string       $label                 Label for the control. Default empty. 
     3144     *  @type string       $description           Description for the control. Default empty. 
     3145     *  @type array        $choices               List of choices for 'radio' or 'select' type controls, where values 
     3146     *                                            are the keys, and labels are the values. Default empty array. 
     3147     *  @type array        $input_attrs           List of custom input attributes for control output, where attribute 
     3148     *                                            names are the keys and values are the values. Default empty array. 
     3149     *  @type bool         $allow_addition        Show UI for adding new content, currently only used for the 
     3150     *                                            dropdown-pages control. Default false. 
     3151     *  @type string       $type                  The type of the control. Default 'text'. 
     3152     *  @type callback     $active_callback       Active callback. 
     3153     * } 
    31013154     * @return WP_Customize_Control             The instance of the control that was added. 
    31023155     */ 
     
    34973550     * 
    34983551     * @since 4.5.0 
     3552     * 
    34993553     * @return array Nonces. 
    35003554     */ 
     
    36373691     * Returns a list of devices to allow previewing. 
    36383692     * 
    3639      * @access public 
    36403693     * @since 4.5.0 
    36413694     * 
     
    41894242     * Used as active callback for static front page section and controls. 
    41904243     * 
    4191      * @access private 
    41924244     * @since 4.7.0 
    41934245     * 
     
    42464298     * 
    42474299     * @since 4.7.0 
    4248      * @access private 
    42494300     * 
    42504301     * @param string $value Repeat value. 
     
    43804431     * 
    43814432     * @since 4.5.0 
    4382      * @access private 
    43834433     * 
    43844434     * @return string Custom logo. 
  • trunk/src/wp-includes/class-wp-customize-setting.php

    r40036 r40804  
    1919class WP_Customize_Setting { 
    2020    /** 
     21     * Customizer bootstrap instance. 
     22     * 
     23     * @since 3.4.0 
    2124     * @access public 
    2225     * @var WP_Customize_Manager 
     
    2730     * Unique string identifier for the setting. 
    2831     * 
     32     * @since 3.4.0 
    2933     * @access public 
    3034     * @var string 
     
    3337 
    3438    /** 
     39     * Type of customize settings. 
     40     * 
     41     * @since 3.4.0 
    3542     * @access public 
    3643     * @var string 
     
    4148     * Capability required to edit this setting. 
    4249     * 
     50     * @since 3.4.0 
     51     * @access public 
     52     * @var string|array 
     53     */ 
     54    public $capability = 'edit_theme_options'; 
     55 
     56    /** 
     57     * Feature a theme is required to support to enable this setting. 
     58     * 
     59     * @since 3.4.0 
     60     * @access public 
    4361     * @var string 
    4462     */ 
    45     public $capability = 'edit_theme_options'; 
    46  
    47     /** 
    48      * Feature a theme is required to support to enable this setting. 
    49      * 
     63    public $theme_supports = ''; 
     64 
     65    /** 
     66     * The default value for the setting. 
     67     * 
     68     * @since 3.4.0 
    5069     * @access public 
    5170     * @var string 
    5271     */ 
    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    = ''; 
     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     */ 
    64113    public $sanitize_js_callback = ''; 
    65114 
     
    79128 
    80129    /** 
     130     * ID Data. 
     131     * 
     132     * @since 3.4.0 
     133     * @access protected 
    81134     * @var array 
    82135     */ 
     
    96149     * 
    97150     * @since 4.4.0 
     151     * @static 
    98152     * @access protected 
    99153     * @var array 
    100      * @static 
    101154     */ 
    102155    protected static $aggregated_multidimensionals = array(); 
     
    169222     * 
    170223     * @since 4.4.0 
    171      * @access public 
    172224     * 
    173225     * @return array { 
     
    189241     * 
    190242     * @since 4.4.0 
    191      * @access protected 
    192243     */ 
    193244    protected function aggregate_multidimensional() { 
     
    217268     * 
    218269     * @since 4.5.0 
    219      * @access public 
    220270     * @ignore 
    221271     */ 
     
    237287     * 
    238288     * @since 4.2.0 
    239      * @access public 
    240289     * 
    241290     * @return bool If preview() has been called. 
     
    253302     * @see WP_Customize_Setting::preview() 
    254303     * @since 4.1.1 
     304     * @access protected 
    255305     * @var mixed 
    256306     */ 
     
    266316     * @since 3.4.0 
    267317     * @since 4.4.0 Added boolean return value. 
    268      * @access public 
    269318     * 
    270319     * @return bool False when preview short-circuits due no change needing to be previewed. 
     
    380429     * 
    381430     * @since 4.4.0 
    382      * @access private 
     431     * 
    383432     * @see WP_Customize_Manager::set_post_value() 
    384433     * @see WP_Customize_Setting::_multidimensional_preview_filter() 
     
    427476     * 
    428477     * @since 4.4.0 
    429      * @access private 
    430478     * 
    431479     * @see WP_Customize_Setting::$aggregated_multidimensionals 
     
    470518     * @since 3.4.0 
    471519     * 
    472      * @access public 
    473      * 
    474520     * @return false|void False if cap check fails or value isn't set or is invalid. 
    475521     */ 
     
    537583     * 
    538584     * @since 4.6.0 
    539      * @access public 
    540585     * 
    541586     * @see WP_REST_Request::has_valid_params() 
     
    579624     * 
    580625     * @since 4.4.0 
    581      * @access protected 
    582626     * 
    583627     * @param mixed $default Value to return if root does not exist. 
     
    604648     * 
    605649     * @since 4.4.0 
    606      * @access protected 
    607650     * 
    608651     * @param mixed $value Value to set as root of multidimensional setting. 
     
    771814     * 
    772815     * @since 4.6.0 
    773      * @access public 
    774816     * 
    775817     * @return array Array of parameters passed to JavaScript. 
     
    908950} 
    909951 
    910 /** WP_Customize_Filter_Setting class */ 
     952/** 
     953 * WP_Customize_Filter_Setting class. 
     954 */ 
    911955require_once( ABSPATH . WPINC . '/customize/class-wp-customize-filter-setting.php' ); 
    912956 
    913 /** WP_Customize_Header_Image_Setting class */ 
     957/** 
     958 * WP_Customize_Header_Image_Setting class. 
     959 */ 
    914960require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-setting.php' ); 
    915961 
    916 /** WP_Customize_Background_Image_Setting class */ 
     962/** 
     963 * WP_Customize_Background_Image_Setting class. 
     964 */ 
    917965require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-setting.php' ); 
    918966 
    919 /** WP_Customize_Nav_Menu_Item_Setting class */ 
     967/** 
     968 * WP_Customize_Nav_Menu_Item_Setting class. 
     969 */ 
    920970require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-setting.php' ); 
    921971 
    922 /** WP_Customize_Nav_Menu_Setting class */ 
     972/** 
     973 * WP_Customize_Nav_Menu_Setting class. 
     974 */ 
    923975require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-setting.php' ); 
  • trunk/src/wp-includes/customize/class-wp-customize-selective-refresh.php

    r40316 r40804  
    8989     * 
    9090     * @since 4.5.0 
    91      * @access public 
    9291     * 
    9392     * @param WP_Customize_Partial|string $id   Customize Partial object, or Panel ID. 
    94      * @param array                       $args Optional. Partial arguments. Default empty array. 
     93     * @param array                       $args { 
     94     *  Optional. Array of properties for the new Partials object. Default empty array. 
     95     * 
     96     *  @type string   $type                  Type of the partial to be created. 
     97     *  @type string   $selector              The jQuery selector to find the container element for the partial, that is, a partial's placement. 
     98     *  @type array    $settings              IDs for settings tied to the partial. 
     99     *  @type string   $primary_setting       The ID for the setting that this partial is primarily responsible for 
     100     *                                        rendering. If not supplied, it will default to the ID of the first setting. 
     101     *  @type string   $capability            Capability required to edit this partial. 
     102     *                                        Normally this is empty and the capability is derived from the capabilities 
     103     *                                        of the associated `$settings`. 
     104     *  @type callable $render_callback       Render callback. 
     105     *                                        Callback is called with one argument, the instance of WP_Customize_Partial. 
     106     *                                        The callback can either echo the partial or return the partial as a string, 
     107     *                                        or return false if error. 
     108     *  @type bool     $container_inclusive   Whether the container element is included in the partial, or if only 
     109     *                                        the contents are rendered. 
     110     *  @type bool     $fallback_refresh      Whether to refresh the entire preview in case a partial cannot be refreshed. 
     111     *                                        A partial render is considered a failure if the render_callback returns 
     112     *                                        false. 
     113     * } 
    95114     * @return WP_Customize_Partial             The instance of the panel that was added. 
    96115     */ 
Note: See TracChangeset for help on using the changeset viewer.