WordPress.org
Get WordPress

Make WordPress Core

Ticket #21303: diff3.patch

File diff3.patch, 19.5 KB (added by bananastalktome, 12 years ago)

Includes inline docs (or stubs) for all 4 class-wp-customize-*.php files

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

     
    11<?php
    22/**
    3  * Customize Section Class
     3 * Customize Section Class.
    44 *
    55 * @package WordPress
    66 * @subpackage Customize
    77 * @since 3.4.0
    88 */
    9 
    109class WP_Customize_Section {
    1110        public $manager;
    1211        public $id;
    … …  
    2221         *
    2322         * @since 3.4.0
    2423         *
     24         * @param WP_Customize_Manager $manager
    2525         * @param string $id An specific ID of the section.
    2626         * @param array $args Section arguments.
    2727         */
    … …  
    7272                $this->render();
    7373        }
    7474
    75 
    7675        /**
    7776         * Render the section.
    7877         *

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

     
    11<?php
    22/**
    3  * Customize
     3 * Customize Manager.
    44 *
    55 * @package WordPress
    66 * @subpackage Customize
    77 * @since 3.4.0
    88 */
    9 
    109final class WP_Customize_Manager {
    1110        protected $theme;
    1211        protected $original_stylesheet;
    … …  
    5655                add_action( 'customize_controls_enqueue_scripts', array( $this, 'enqueue_control_scripts' ) );
    5756        }
    5857
    59         /**
     58        /**
    6059         * Return true if it's an AJAX request.
    6160         *
    6261         * @since 3.4.0
     62         *
     63         * @return bool
    6364         */
    6465        public function doing_ajax() {
    6566                return isset( $_POST['customized'] ) || ( defined( 'DOING_AJAX' ) && DOING_AJAX );
    … …  
    6970         * Custom wp_die wrapper. Returns either the standard message for UI
    7071         * or the AJAX message.
    7172         *
    72          * @param  mixed $ajax_message AJAX return
    73          * @param  mixed $message      UI message
     73         * @since 3.4.0
    7474         *
    75          * @since 3.4.0
     75         * @param mixed $ajax_message AJAX return
     76         * @param mixed $message UI message
    7677         */
    7778        protected function wp_die( $ajax_message, $message = null ) {
    7879                if ( $this->doing_ajax() )
    … …  
    8889         * Return the AJAX wp_die() handler if it's a customized request.
    8990         *
    9091         * @since 3.4.0
     92         *
     93         * @return string
    9194         */
    9295        public function wp_die_handler() {
    9396                if ( $this->doing_ajax() )
    … …  
    9598
    9699                return '_default_wp_die_handler';
    97100        }
     101       
    98102        /**
    99         * Start preview and customize theme.
    100         *
    101         * Check if customize query variable exist. Init filters to filter the current theme.
     103         * Start preview and customize theme.
    102104         *
     105         * Check if customize query variable exist. Init filters to filter the current theme.
     106         *
    103107         * @since 3.4.0
    104108         */
    105109        public function setup_theme() {
    … …  
    136140
    137141                $this->start_previewing_theme();
    138142        }
    139 
     143       
     144        /**
     145         * Callback to validate a theme once it is loaded
     146         *
     147         * @since 3.4.0
     148         */
    140149        function after_setup_theme() {
    141150                if ( ! $this->doing_ajax() && ! validate_current_theme() ) {
    142151                        wp_redirect( 'themes.php?broken=true' );
    … …  
    279288         * Instead, the JS will sniff out the location header.
    280289         *
    281290         * @since 3.4.0
     291         *
     292         * @param $status
     293         * @return int
    282294         */
    283295        public function wp_redirect_status( $status ) {
    284296                if ( $this->is_preview() && ! is_admin() )
    … …  
    291303         * Decode the $_POST attribute used to override the WP_Customize_Setting values.
    292304         *
    293305         * @since 3.4.0
     306         *
     307         * @param mixed $setting A WP_Customize_Setting derived object
     308         * @return string Sanitized attribute
    294309         */
    295310        public function post_value( $setting ) {
    296311                if ( ! isset( $this->_post_values ) ) {
    … …  
    367382                );
    368383
    369384                if ( 2 == $this->nonce_tick ) {
    370                         $settings['nonce'] = array(
    371                                 'save' => wp_create_nonce( 'save-customize_' . $this->get_stylesheet() ),
    372                                 'preview' => wp_create_nonce( 'preview-customize_' . $this->get_stylesheet() )
    373                         );
    374                 }
     385                        $settings['nonce'] = array(
     386                                'save' => wp_create_nonce( 'save-customize_' . $this->get_stylesheet() ),
     387                                'preview' => wp_create_nonce( 'preview-customize_' . $this->get_stylesheet() )
     388                        );
     389                }
    375390
    376391                foreach ( $this->settings as $id => $setting ) {
    377392                        $settings['values'][ $id ] = $setting->js_value();
    … …  
    464479         *
    465480         * @since 3.4.0
    466481         *
     482         * @param $current_theme {@internal Parameter is not used}
    467483         * @return string Theme name.
    468484         */
    469485        public function current_theme( $current_theme ) {
    … …  
    630646         *
    631647         * @param object $a Object A.
    632648         * @param object $b Object B.
     649         * @return int
    633650         */
    634651        protected final function _cmp_priority( $a, $b ) {
    635652                $ap = $a->priority;
    … …  
    960977         * Accepts 'blank', and otherwise uses sanitize_hex_color_no_hash().
    961978         *
    962979         * @since 3.4.0
     980         *
     981         * @param string $color
     982         * @return string
    963983         */
    964984        public function _sanitize_header_textcolor( $color ) {
    965985                return ( 'blank' === $color ) ? 'blank' : sanitize_hex_color_no_hash( $color );
    … …  
    973993 * For validating values without a #, see sanitize_hex_color_no_hash().
    974994 *
    975995 * @since 3.4.0
     996 *
     997 * @param string $color
     998 * @return string|null
    976999 */
    9771000function sanitize_hex_color( $color ) {
    9781001        if ( '' === $color )
    … …  
    9951018 * Returns either '', a 3 or 6 digit hex color (without a #), or null.
    9961019 *
    9971020 * @since 3.4.0
     1021 * @uses sanitize_hex_color()
     1022 *
     1023 * @param string $color
     1024 * @return string|null
    9981025 */
    9991026function sanitize_hex_color_no_hash( $color ) {
    10001027        $color = ltrim( $color, '#' );
    … …  
    10121039 * This method should only be necessary if using sanitize_hex_color_no_hash().
    10131040 *
    10141041 * @since 3.4.0
     1042 *
     1043 * @param string $color
     1044 * @return string
    10151045 */
    10161046function maybe_hash_hex_color( $color ) {
    10171047        if ( $unhashed = sanitize_hex_color_no_hash( $color ) )

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

     
    66 * @subpackage Customize
    77 * @since 3.4.0
    88 */
    9 
    109class WP_Customize_Control {
     10        /**
     11         * @access public
     12         * @var WP_Customize_Manager
     13         */
    1114        public $manager;
     15       
     16        /**
     17         * @access public
     18         * @var string
     19         */
    1220        public $id;
    1321
    14         // All settings tied to the control.
     22        /**
     23         * All settings tied to the control.
     24         *
     25         * @access public
     26         * @var array
     27         */
    1528        public $settings;
    1629
    17         // The primary setting for the control (if there is one).
     30        /**
     31         * The primary setting for the control (if there is one).
     32         *
     33         * @access public
     34         * @var string
     35         */
    1836        public $setting = 'default';
    1937
     38        /**
     39         * @access public
     40         * @var int
     41         */
    2042        public $priority          = 10;
     43       
     44        /**
     45         * @access public
     46         * @var string
     47         */
    2148        public $section           = '';
     49       
     50        /**
     51         * @access public
     52         * @var string
     53         */
    2254        public $label             = '';
    23         // @todo: remove choices
     55       
     56        /**
     57         * @todo: Remove choices
     58         *
     59         * @access public
     60         * @var array
     61         */
    2462        public $choices           = array();
    2563
     64        /**
     65         * @access public
     66         * @var array
     67         */
    2668        public $json = array();
    2769
     70        /**
     71         * @access public
     72         * @var string
     73         */
    2874        public $type = 'text';
    2975
    3076
    … …  
    3480         * If $args['settings'] is not defined, use the $id as the setting ID.
    3581         *
    3682         * @since 3.4.0
     83         *
     84         * @param WP_Customize_Manager $manager
     85         * @param string $id
     86         * @param array $args
    3787         */
    3888        function __construct( $manager, $id, $args = array() ) {
    3989                $keys = array_keys( get_object_vars( $this ) );
    … …  
    75125         * Grabs the main setting by default.
    76126         *
    77127         * @since 3.4.0
     128         *
     129         * @param string $setting_key
     130         * @return mixed The requested setting's value, if the setting exists.
    78131         */
    79132        public final function value( $setting_key = 'default' ) {
    80133                if ( isset( $this->settings[ $setting_key ] ) )
    … …  
    119172         * Check capabilities and render the control.
    120173         *
    121174         * @since 3.4.0
     175         * @uses WP_Customize_Control::render()
    122176         */
    123177        public final function maybe_render() {
    124178                if ( ! $this->check_capabilities() )
    … …  
    143197                        <?php $this->render_content(); ?>
    144198                </li><?php
    145199        }
    146 
     200       
     201        /**
     202         * Get the data link parameter for a setting.
     203         *
     204         * @since 3.4.0
     205         *
     206         * @param string $setting_key
     207         * @return string Data link parameter, if $setting_key is a valid setting, empty string otherwise.
     208         */
    147209        public function get_link( $setting_key = 'default' ) {
    148210                if ( ! isset( $this->settings[ $setting_key ] ) )
    149211                        return '';
    150212
    151213                return 'data-customize-setting-link="' . esc_attr( $this->settings[ $setting_key ]->id ) . '"';
    152214        }
    153 
     215       
     216        /**
     217         * Render the data link parameter for a setting
     218         *
     219         * @since 3.4.0
     220         * @uses WP_Customize_Control::get_link()
     221         *
     222         * @param string $setting_key
     223         */
    154224        public function link( $setting_key = 'default' ) {
    155225                echo $this->get_link( $setting_key );
    156226        }
    … …  
    238308        }
    239309}
    240310
     311/**
     312 * Customize Color Control Class
     313 *
     314 * @package WordPress
     315 * @subpackage Customize
     316 * @since 3.4.0
     317 */
    241318class WP_Customize_Color_Control extends WP_Customize_Control {
     319        /**
     320         * @access public
     321         * @var string
     322         */
    242323        public $type = 'color';
     324       
     325        /**
     326         * @access public
     327         * @var array
     328         */
    243329        public $statuses;
    244330
     331        /**
     332         * Constructor.
     333         *
     334         * If $args['settings'] is not defined, use the $id as the setting ID.
     335         *
     336         * @since 3.4.0
     337         * @uses WP_Customize_Control::__construct()
     338         *
     339         * @param WP_Customize_Manager $manager
     340         * @param string $id
     341         * @param array $args
     342         */
    245343        public function __construct( $manager, $id, $args = array() ) {
    246344                $this->statuses = array( '' => __('Default') );
    247345                parent::__construct( $manager, $id, $args );
    248346        }
    249347
     348        /**
     349         * Enqueue control related scripts/styles.
     350         *
     351         * @since 3.4.0
     352         */
    250353        public function enqueue() {
    251354                wp_enqueue_script( 'farbtastic' );
    252355                wp_enqueue_style( 'farbtastic' );
    253356        }
    254357
     358        /**
     359         * Refresh the parameters passed to the JavaScript via JSON.
     360         *
     361         * @since 3.4.0
     362         * @uses WP_Customize_Control::to_json()
     363         */
    255364        public function to_json() {
    256365                parent::to_json();
    257366                $this->json['statuses'] = $this->statuses;
    258367        }
    259368
     369        /**
     370         * Render the control's content.
     371         *
     372         * @since 3.4.0
     373         */
    260374        public function render_content() {
    261375                ?>
    262376                <label>
    … …  
    276390        }
    277391}
    278392
     393/**
     394 * Customize Upload Control Class
     395 *
     396 * @package WordPress
     397 * @subpackage Customize
     398 * @since 3.4.0
     399 */
    279400class WP_Customize_Upload_Control extends WP_Customize_Control {
    280401        public $type    = 'upload';
    281402        public $removed = '';
    282403        public $context;
    283404
     405        /**
     406         * Enqueue control related scripts/styles.
     407         *
     408         * @since 3.4.0
     409         */
    284410        public function enqueue() {
    285411                wp_enqueue_script( 'wp-plupload' );
    286412        }
    287 
     413       
     414        /**
     415         * Refresh the parameters passed to the JavaScript via JSON.
     416         *
     417         * @since 3.4.0
     418         * @uses WP_Customize_Control::to_json()
     419         */
    288420        public function to_json() {
    289421                parent::to_json();
    290422
    … …  
    294426                        $this->json['context'] = $this->context;
    295427        }
    296428
     429        /**
     430         * Render the control's content.
     431         *
     432         * @since 3.4.0
     433         */
    297434        public function render_content() {
    298435                ?>
    299436                <label>
    … …  
    307444        }
    308445}
    309446
     447/**
     448 * Customize Image Control Class
     449 *
     450 * @package WordPress
     451 * @subpackage Customize
     452 * @since 3.4.0
     453 */
    310454class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
    311455        public $type = 'image';
    312456        public $get_url;
    … …  
    314458
    315459        protected $tabs = array();
    316460
     461        /**
     462         * Constructor.
     463         *
     464         * If $args['settings'] is not defined, use the $id as the setting ID.
     465         *
     466         * @since 3.4.0
     467         * @uses WP_Customize_Upload_Control::__construct()
     468         *
     469         * @param WP_Customize_Manager $manager
     470         * @param string $id
     471         * @param array $args
     472         */
    317473        public function __construct( $manager, $id, $args ) {
    318474                $this->statuses = array( '' => __('No Image') );
    319475
    … …  
    323479                $this->add_tab( 'uploaded',   __('Uploaded'),   array( $this, 'tab_uploaded' ) );
    324480        }
    325481
     482        /**
     483         * Refresh the parameters passed to the JavaScript via JSON.
     484         *
     485         * @since 3.4.0
     486         * @uses WP_Customize_Upload_Control::to_json()
     487         */
    326488        public function to_json() {
    327489                parent::to_json();
    328490                $this->json['statuses'] = $this->statuses;
    329491        }
    330492
     493        /**
     494         * Render the control's content.
     495         *
     496         * @since 3.4.0
     497         */
    331498        public function render_content() {
    332499                $src = $this->value();
    333500                if ( isset( $this->get_url ) )
    … …  
    372539                </div>
    373540                <?php
    374541        }
    375 
     542       
     543        /**
     544         * Add a tab to the control.
     545         *
     546         * @since 3.4.0
     547         *
     548         * @param string $id
     549         * @param string $label
     550         * @param mixed $callback
     551         */
    376552        public function add_tab( $id, $label, $callback ) {
    377553                $this->tabs[ $id ] = array(
    378554                        'label'    => $label,
    … …  
    380556                );
    381557        }
    382558
     559        /**
     560         * Remove a tab from the control.
     561         *
     562         * @since 3.4.0
     563         *
     564         * @param string $id
     565         */
    383566        public function remove_tab( $id ) {
    384567                unset( $this->tabs[ $id ] );
    385568        }
    386569
     570        /**
     571         * @since 3.4.0
     572         */
    387573        public function tab_upload_new() {
    388574                if ( ! _device_can_upload() ) {
    389575                        ?>
    … …  
    400586                        <?php
    401587                }
    402588        }
    403 
     589       
     590        /**
     591         * @since 3.4.0
     592         */
    404593        public function tab_uploaded() {
    405594                ?>
    406595                <div class="uploaded-target"></div>
    407596                <?php
    408597        }
    409598
     599        /**
     600         * @since 3.4.0
     601         *
     602         * @param string $url
     603         * @param string $thumbnail_url
     604         */
    410605        public function print_tab_image( $url, $thumbnail_url = null ) {
    411606                $url = set_url_scheme( $url );
    412607                $thumbnail_url = ( $thumbnail_url ) ? set_url_scheme( $thumbnail_url ) : $url;
    … …  
    418613        }
    419614}
    420615
     616/**
     617 * Customize Background Image Control Class
     618 *
     619 * @package WordPress
     620 * @subpackage Customize
     621 * @since 3.4.0
     622 */
    421623class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
     624
     625        /**
     626         * Constructor.
     627         *
     628         * @since 3.4.0
     629         * @uses WP_Customize_Image_Control::__construct()
     630         *
     631         * @param WP_Customize_Manager $manager
     632         */
    422633        public function __construct( $manager ) {
    423634                parent::__construct( $manager, 'background_image', array(
    424635                        'label'    => __( 'Background Image' ),
    … …  
    431642                        $this->add_tab( 'default',  __('Default'),  array( $this, 'tab_default_background' ) );
    432643        }
    433644
     645        /**
     646         * @since 3.4.0
     647         */
    434648        public function tab_uploaded() {
    435649                $backgrounds = get_posts( array(
    436650                        'post_type'  => 'attachment',
    … …  
    448662                foreach ( (array) $backgrounds as $background )
    449663                        $this->print_tab_image( esc_url_raw( $background->guid ) );
    450664        }
    451 
     665       
     666        /**
     667         * @since 3.4.0
     668         * @uses WP_Customize_Image_Control::print_tab_image()
     669         */
    452670        public function tab_default_background() {
    453671                $this->print_tab_image( $this->setting->default );
    454672        }
    455673}
    456674
     675/**
     676 * Customize Header Image Control Class
     677 *
     678 * @package WordPress
     679 * @subpackage Customize
     680 * @since 3.4.0
     681 */
    457682class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
     683
     684        /**
     685         * Constructor.
     686         *
     687         * @since 3.4.0
     688         * @uses WP_Customize_Image_Control::__construct()
     689         * @uses WP_Customize_Image_Control::add_tab()
     690         *
     691         * @param WP_Customize_Manager $manager
     692         */
    458693        public function __construct( $manager ) {
    459694                parent::__construct( $manager, 'header_image', array(
    460695                        'label'    => __( 'Header Image' ),
    … …  
    477712                $this->add_tab( 'default',  __('Default'),  array( $this, 'tab_default_headers' ) );
    478713        }
    479714
     715        /**
     716         * @since 3.4.0
     717         *
     718         * @param mixed $choice Which header image to select. (@see Custom_Image_Header::get_header_image() )
     719         * @param array $header
     720         */
    480721        public function print_header_image( $choice, $header ) {
    481722                $header['url']           = set_url_scheme( $header['url'] );
    482723                $header['thumbnail_url'] = set_url_scheme( $header['thumbnail_url'] );
    … …  
    496737                </a>
    497738                <?php
    498739        }
    499 
     740       
     741        /**
     742         * @since 3.4.0
     743         */
    500744        public function tab_uploaded() {
    501745                $headers = get_uploaded_header_images();
    502746
    … …  
    506750                        $this->print_header_image( $choice, $header );
    507751        }
    508752
     753        /**
     754         * @since 3.4.0
     755         */
    509756        public function tab_default_headers() {
    510757                global $custom_image_header;
    511758                $custom_image_header->process_default_headers();

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

     
    11<?php
    22/**
    3  * Customize Setting Class
     3 * Customize Setting Class.
    44 *
    55 * @package WordPress
    66 * @subpackage Customize
    77 * @since 3.4.0
    88 */
    9 
    109class WP_Customize_Setting {
    1110        public $manager;
    1211        public $id;
    … …  
    2827         *
    2928         * @since 3.4.0
    3029         *
     30         * @param WP_Customize_Manager $manager
    3131         * @param string $id An specific ID of the setting. Can be a
    3232         *                   theme mod or option name.
    3333         * @param array $args Setting arguments.
     34         * @return WP_Customize_Setting
    3435         */
    3536        function __construct( $manager, $id, $args = array() ) {
    3637                $keys = array_keys( get_class_vars( __CLASS__ ) );
    … …  
    8788         * Callback function to filter the theme mods and options.
    8889         *
    8990         * @since 3.4.0
     91         * @uses WP_Customize_Setting::multidimensional_replace()
    9092         *
    91          * @param mixed Old value.
     93         * @param mixed $original Old value.
    9294         * @return mixed New or old value.
    9395         */
    9496        public function _preview_filter( $original ) {
    … …  
    118120         *
    119121         * @since 3.4.0
    120122         *
    121          * @param $default mixed A default value which is used as a fallback. Default is null.
    122          * @return mixed Either the default value on failure or sanitized value.
     123         * @param mixed $default A default value which is used as a fallback. Default is null.
     124         * @return mixed The default value on failure, otherwise the sanitized value.
    123125         */
    124126        public final function post_value( $default = null ) {
    125127                if ( isset( $this->_post_value ) )
    … …  
    138140         *
    139141         * @since 3.4.0
    140142         *
    141          * @param $value mixed The value to sanitize.
     143         * @param mixed $value The value to sanitize.
    142144         * @return mixed Null if an input isn't valid, otherwise the sanitized value.
    143145         */
    144146        public function sanitize( $value ) {
    … …  
    151153         *
    152154         * @since 3.4.0
    153155         *
    154          * @param $value mixed The value to update.
     156         * @param mixed $value The value to update.
    155157         * @return mixed The result of saving the value.
    156158         */
    157159        protected function update( $value ) {
    … …  
    172174         *
    173175         * @since 3.4.0
    174176         *
    175          * @param $value mixed The value to update.
     177         * @param mixed $value The value to update.
    176178         * @return mixed The result of saving the value.
    177179         */
    178180        protected function _update_theme_mod( $value ) {
    … …  
    192194         *
    193195         * @since 3.4.0
    194196         *
    195          * @param $value mixed The value to update.
     197         * @param mixed $value The value to update.
    196198         * @return mixed The result of saving the value.
    197199         */
    198200        protected function _update_option( $value ) {
    … …  
    276278         * @param $root
    277279         * @param $keys
    278280         * @param bool $create Default is false.
    279          * @return null|array
     281         * @return null|array Keys are 'root', 'node', and 'key'.
    280282         */
    281283        final protected function multidimensional( &$root, $keys, $create = false ) {
    282284                if ( $create && empty( $root ) )
    … …  
    372374 * A setting that is used to filter a value, but will not save the results.
    373375 *
    374376 * Results should be properly handled using another setting or callback.
     377 *
     378 * @package WordPress
     379 * @subpackage Customize
     380 * @since 3.4.0
    375381 */
    376382class WP_Customize_Filter_Setting extends WP_Customize_Setting {
     383       
     384        /**
     385         * @since 3.4.0
     386         */
    377387        public function update() {}
    378388}
    379389
    … …  
    381391 * A setting that is used to filter a value, but will not save the results.
    382392 *
    383393 * Results should be properly handled using another setting or callback.
     394 *
     395 * @package WordPress
     396 * @subpackage Customize
     397 * @since 3.4.0
    384398 */
    385399final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
    386400        public $id = 'header_image_data';
    387401
     402        /**
     403         * @since 3.4.0
     404         *
     405         * @param $value
     406         */
    388407        public function update( $value ) {
    389408                global $custom_image_header;
    390409
    … …  
    400419        }
    401420}
    402421
     422/**
     423 * @package WordPress
     424 * @subpackage Customize
     425 * @since 3.4.0
     426 */
    403427final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
    404428        public $id = 'background_image_thumb';
    405429
     430        /**
     431         * @since 3.4.0
     432         * @uses remove_theme_mod()
     433         *
     434         * @param $value
     435         */
    406436        public function update( $value ) {
    407437                remove_theme_mod( 'background_image_thumb' );
    408438        }