Make WordPress Core

Changeset 40804


Ignore:
Timestamp:
05/19/2017 08:24:58 PM (7 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.

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.