WordPress.org

Make WordPress Core

Ticket #39671: 39671-1.patch

File 39671-1.patch, 26.0 KB (added by 4nickpick, 3 years ago)

Adds and expands inline docs for partials, settings, sections, controls and panels.

  • wp-includes/class-wp-customize-control.php

    diff --git wp-includes/class-wp-customize-control.php wp-includes/class-wp-customize-control.php
    index 07c6dcfce..3851fc0aa 100644
    class WP_Customize_Control { 
    7777        public $capability;
    7878
    7979        /**
     80         * Order priority to load the control.
     81         *
    8082         * @access public
    8183         * @var int
    8284         */
    8385        public $priority = 10;
    8486
    8587        /**
     88         * Section the control belongs to.
     89         *
    8690         * @access public
    8791         * @var string
    8892         */
    8993        public $section = '';
    9094
    9195        /**
     96         * Label for the control.
     97         *
    9298         * @access public
    9399         * @var string
    94100         */
    95101        public $label = '';
    96102
    97103        /**
     104         * Description for the control.
     105         *
    98106         * @access public
    99107         * @var string
    100108         */
    class WP_Customize_Control { 
    102110
    103111        /**
    104112         * @todo: Remove choices
     113         * List of choices for 'radio' or 'select' type controls, where values are the keys, and labels are the values.
    105114         *
    106115         * @access public
    107116         * @var array
    class WP_Customize_Control { 
    109118        public $choices = array();
    110119
    111120        /**
     121         * List of custom input attributes for control output, where attribute names are the keys and values are the values.
     122         *
     123         * Not used for 'checkbox', 'radio', 'select', 'textarea', or 'dropdown-pages' control types.
     124         *
    112125         * @access public
    113126         * @var array
    114127         */
  • wp-includes/class-wp-customize-manager.php

    diff --git wp-includes/class-wp-customize-manager.php wp-includes/class-wp-customize-manager.php
    index 229a2484b..1161a5eb0 100644
    final class WP_Customize_Manager { 
    27932793         * @access public
    27942794         *
    27952795         * @param WP_Customize_Setting|string $id   Customize Setting object, or ID.
    2796          * @param array                       $args Setting arguments; passed to WP_Customize_Setting
    2797          *                                          constructor.
     2796         * @param array                       $args {
     2797         *     Optional. Array of properties for the new WP_Customize_Setting. Default empty array.
     2798         *
     2799         *     @type string       $type                  Type of the setting. Default 'theme_mod'.
     2800         *                                               Default 160.
     2801         *     @type string       $capability            Capability required for the setting. Default 'edit_theme_options'
     2802         *     @type string|array $theme_supports        Theme features required to support the panel. Default is none.
     2803         *     @type string       $default               Default value for the setting. Default is empty string.
     2804         *     @type string       $transport             Options for rendering the live preview of changes in Theme Customizer.
     2805         *                                               Using 'refresh' makes the change visible by reloading the whole preview.
     2806         *                                               Using 'postMessage' allows a custom JavaScript to handle live changes.
     2807         *                                               @see https://codex.wordpress.org/Theme_Customization_API
     2808         *                                               Default is 'refresh'
     2809         *     @type callable     $validate_callback     Server-side validation callback for the setting's value.
     2810         *     @type callable     $sanitize_callback     Callback to filter a Customize setting value in un-slashed form.
     2811         *     @type callable     $sanitize_js_callback  Callback to filter a Customize setting value for use in Javascript.
     2812         *     @type bool         $dirty                 Whether or not the setting is initially dirty when created.
     2813         * }
    27982814         * @return WP_Customize_Setting             The instance of the setting that was added.
    27992815         */
    28002816        public function add_setting( $id, $args = array() ) {
    final class WP_Customize_Manager { 
    29112927         * @access public
    29122928         *
    29132929         * @param WP_Customize_Panel|string $id   Customize Panel object, or Panel ID.
    2914          * @param array                     $args Optional. Panel arguments. Default empty array.
     2930         * @param array                     $args {
     2931         *     Optional. Array of properties for the new Panel object. Default empty array.
     2932         *
     2933         *     @type int          $priority              Priority of the panel, defining the display order of panels and sections.
     2934         *                                               Default 160.
     2935         *     @type string       $capability            Capability required for the panel. Default `edit_theme_options`
     2936         *     @type string|array $theme_supports        Theme features required to support the panel.
     2937         *     @type string       $title                 Title of the panel to show in UI.
     2938         *     @type string       $description           Description to show in the UI.
     2939         *     @type string       $type                  Type of the panel.
     2940         *     @type callable     $active_callback       Active callback.
     2941         * }
    29152942         *
    29162943         * @return WP_Customize_Panel             The instance of the panel that was added.
    29172944         */
    final class WP_Customize_Manager { 
    30003027         * @access public
    30013028         *
    30023029         * @param WP_Customize_Section|string $id   Customize Section object, or Section ID.
    3003          * @param array                       $args Section arguments.
     3030         * @param array                     $args {
     3031         *     Optional. Array of properties for the new Panel object. Default empty array.
     3032         *
     3033         *     @type int          $priority              Priority of the panel, defining the display order of panels and sections.
     3034         *                                               Default 160.
     3035         *     @type string       $panel                 Priority of the panel, defining the display order of panels and sections.
     3036         *     @type string       $capability            Capability required for the panel. Default 'edit_theme_options'
     3037         *     @type string|array $theme_supports        Theme features required to support the panel.
     3038         *     @type string       $title                 Title of the panel to show in UI.
     3039         *     @type string       $description           Description to show in the UI.
     3040         *     @type string       $type                  Type of the panel.
     3041         *     @type callable     $active_callback       Active callback.
     3042         *     @type bool         $description_hidden    Hide the description behind a help icon, instead of . Default false.
     3043         * }
    30043044         *
    30053045         * @return WP_Customize_Section             The instance of the section that was added.
    30063046         */
    final class WP_Customize_Manager { 
    30763116         * @access public
    30773117         *
    30783118         * @param WP_Customize_Control|string $id   Customize Control object, or ID.
    3079          * @param array                       $args Control arguments; passed to WP_Customize_Control
    3080          *                                          constructor.
     3119         * @param array                       $args {
     3120         *     Optional. Array of properties for the new Control object. Default empty array.
     3121         *
     3122         *     @type array        $settings              All settings tied to the control. If undefined, defaults to `$setting`.
     3123         *                                               IDs in the array correspond to the ID of a registered `WP_Customize_Setting`.
     3124         *     @type string       $setting               The primary setting for the control (if there is one). Default is 'default'.
     3125         *     @type string       $capability            Capability required to use this control. Normally derived from `$settings`.
     3126         *     @type int          $priority              Order priority to load the control. Default 10.
     3127         *     @type string       $section               The section this control belongs to. Default empty.
     3128         *     @type string       $label                 Label for the control. Default empty.
     3129         *     @type string       $description           Description for the control. Default empty.
     3130         *     @type array        $choices               List of choices for 'radio' or 'select' type controls, where values
     3131         *                                               are the keys, and labels are the values. Default empty array.
     3132         *     @type array        $input_attrs           List of custom input attributes for control output, where attribute
     3133         *                                               names are the keys and values are the values. Default empty array.
     3134         *     @type bool         $allow_addition        Show UI for adding new content, currently only used for the
     3135         *                                               dropdown-pages control. Default false.
     3136         *     @type string       $type                  The type of the control. Default 'text'.
     3137         *     @type callback     $active_callback       Active callback.
     3138         * }
     3139         *
    30813140         * @return WP_Customize_Control             The instance of the control that was added.
    30823141         */
    30833142        public function add_control( $id, $args = array() ) {
  • wp-includes/class-wp-customize-setting.php

    diff --git wp-includes/class-wp-customize-setting.php wp-includes/class-wp-customize-setting.php
    index 83a5b76d6..46e3c5ab3 100644
    class WP_Customize_Setting { 
    4040        /**
    4141         * Capability required to edit this setting.
    4242         *
    43          * @var string
     43         * @var string|array
    4444         */
    4545        public $capability = 'edit_theme_options';
    4646
    class WP_Customize_Setting { 
    5151         * @var string
    5252         */
    5353        public $theme_supports  = '';
     54
     55        /**
     56         * The default value for the setting.
     57         *
     58         * @access public
     59         * @var string
     60         */
    5461        public $default         = '';
     62
     63        /**
     64         * Options for rendering the live preview of changes in Theme Customizer.
     65         *
     66         * Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting
     67         * as opposed to reloading the whole page.
     68         *
     69         * @see https://codex.wordpress.org/Theme_Customization_API
     70         *
     71         * @access public
     72         * @var string
     73         */
    5574        public $transport       = 'refresh';
    5675
    5776        /**
    58          * Server-side sanitization callback for the setting's value.
     77         * Server-side validation callback for the setting's value.
    5978         *
    60          * @var callback
     79         * @var callable
    6180         */
    6281        public $validate_callback    = '';
     82
     83        /**
     84         * Callback to filter a Customize setting value in un-slashed form.
     85         *
     86         * @var callable
     87         */
    6388        public $sanitize_callback    = '';
     89
     90        /**
     91         * Callback to filter a Customize setting value for use in Javascript.
     92         *
     93         * @var callable
     94         */
    6495        public $sanitize_js_callback = '';
    6596
    6697        /**
  • wp-includes/customize/class-wp-customize-selective-refresh.php

    diff --git wp-includes/customize/class-wp-customize-selective-refresh.php wp-includes/customize/class-wp-customize-selective-refresh.php
    index 23d5a9488..32c201d8e 100644
    final class WP_Customize_Selective_Refresh { 
    9191         * @access public
    9292         *
    9393         * @param WP_Customize_Partial|string $id   Customize Partial object, or Panel ID.
    94          * @param array                       $args Optional. Partial arguments. Default empty array.
     94         * @param array                       $args {
     95         *     Optional. Array of properties for the new Partials object. Default empty array.
     96         *
     97         *     @type string   $type                  Type of the partial to be created. Default 'default'.
     98         *     @type string   $selector              The jQuery selector to find the container element for the partial.
     99         *     @type array    $settings              IDs for settings tied to the partial. If undefined, `$id` will be used.
     100         *                                           IDs in the array correspond to the ID of a registered instance
     101         *                                           of `WP_Customize_Setting`
     102         *     @type string   $primary_setting       The ID for the setting that this partial is primarily responsible for
     103         *                                           rendering. If not supplied, it will default to the ID of the first setting.
     104         *     @type string   $capability            Capability required to edit this partial.
     105         *                                           Normally this is empty and the capability is derived from the capabilities
     106         *                                           of the associated `$settings`.
     107         *     @type callable $render_callback       Render callback.
     108         *                                           Callback is called with one argument, the instance of WP_Customize_Partial.
     109         *                                           The callback can either echo the partial or return the partial as a string,
     110         *                                           or return false if error.
     111         *     @type bool     $container_inclusive   Whether the container element is included in the partial, or if only
     112         *                                           the contents are rendered. Default false.
     113         *     @type bool     $fallback_refresh      Whether to refresh the entire preview in case a partial cannot be refreshed.
     114         *                                           A partial render is considered a failure if the render_callback returns
     115         *                                           false. Default true.
     116         * }
     117         *
    95118         * @return WP_Customize_Partial             The instance of the panel that was added.
    96119         */
    97120        public function add_partial( $id, $args = array() ) {