WordPress.org

Make WordPress Core

Changeset 21354


Ignore:
Timestamp:
07/26/12 21:45:33 (21 months ago)
Author:
ryan
Message:

phpdoc for Customizer classes and methods. Props bananastalktome. see #21303

Location:
trunk/wp-includes
Files:
4 edited

Legend:

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

    r21037 r21354  
    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 
     
    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() ) { 
     
    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' ) { 
     
    120173     * 
    121174     * @since 3.4.0 
     175     * @uses WP_Customize_Control::render() 
    122176     */ 
    123177    public final function maybe_render() { 
     
    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 ] ) ) 
     
    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 ); 
     
    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') ); 
     
    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' ); 
     
    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(); 
     
    258367    } 
    259368 
     369    /** 
     370     * Render the control's content. 
     371     * 
     372     * @since 3.4.0 
     373     */ 
    260374    public function render_content() { 
    261375        ?> 
     
    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'; 
     
    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(); 
     
    295427    } 
    296428 
     429    /** 
     430     * Render the control's content. 
     431     * 
     432     * @since 3.4.0 
     433     */ 
    297434    public function render_content() { 
    298435        ?> 
     
    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'; 
     
    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') ); 
     
    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(); 
     
    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(); 
     
    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( 
     
    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() ) { 
     
    401587        } 
    402588    } 
    403  
     589     
     590    /** 
     591     * @since 3.4.0 
     592     */ 
    404593    public function tab_uploaded() { 
    405594        ?> 
     
    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 ); 
     
    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( 
     
    432643    } 
    433644 
     645    /** 
     646     * @since 3.4.0 
     647     */ 
    434648    public function tab_uploaded() { 
    435649        $backgrounds = get_posts( array( 
     
    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 ); 
     
    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( 
     
    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'] ); 
     
    497738        <?php 
    498739    } 
    499  
     740     
     741    /** 
     742     * @since 3.4.0 
     743     */ 
    500744    public function tab_uploaded() { 
    501745        $headers = get_uploaded_header_images(); 
     
    507751    } 
    508752 
     753    /** 
     754     * @since 3.4.0 
     755     */ 
    509756    public function tab_default_headers() { 
    510757        global $custom_image_header; 
  • trunk/wp-includes/class-wp-customize-manager.php

    r21135 r21354  
    11<?php 
    22/** 
    3  * Customize 
     3 * Customize Manager. 
    44 * 
    55 * @package WordPress 
     
    77 * @since 3.4.0 
    88 */ 
    9  
    109final class WP_Customize_Manager { 
    1110    protected $theme; 
     
    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() { 
     
    7071     * or the AJAX message. 
    7172     * 
    72      * @param  mixed $ajax_message AJAX return 
    73      * @param  mixed $message      UI message 
    74      * 
    75      * @since 3.4.0 
     73     * @since 3.4.0 
     74     * 
     75     * @param mixed $ajax_message AJAX return 
     76     * @param mixed $message UI message  
    7677     */ 
    7778    protected function wp_die( $ajax_message, $message = null ) { 
     
    8990     * 
    9091     * @since 3.4.0 
     92     * 
     93     * @return string 
    9194     */ 
    9295    public function wp_die_handler() { 
     
    9699        return '_default_wp_die_handler'; 
    97100    } 
    98     /** 
    99     * Start preview and customize theme. 
    100     * 
    101     * Check if customize query variable exist. Init filters to filter the current theme. 
     101     
     102    /** 
     103     * Start preview and customize theme. 
     104     * 
     105     * Check if customize query variable exist. Init filters to filter the current theme. 
    102106     * 
    103107     * @since 3.4.0 
     
    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() ) { 
     
    280289     * 
    281290     * @since 3.4.0 
     291     * 
     292     * @param $status 
     293     * @return int 
    282294     */ 
    283295    public function wp_redirect_status( $status ) { 
     
    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 ) { 
     
    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 ) { 
     
    465480     * @since 3.4.0 
    466481     * 
     482     * @param $current_theme {@internal Parameter is not used} 
    467483     * @return string Theme name. 
    468484     */ 
     
    631647     * @param object $a Object A. 
    632648     * @param object $b Object B. 
     649     * @return int 
    633650     */ 
    634651    protected final function _cmp_priority( $a, $b ) { 
     
    961978     * 
    962979     * @since 3.4.0 
     980     * 
     981     * @param string $color 
     982     * @return string 
    963983     */ 
    964984    public function _sanitize_header_textcolor( $color ) { 
     
    974994 * 
    975995 * @since 3.4.0 
     996 * 
     997 * @param string $color 
     998 * @return string|null 
    976999 */ 
    9771000function sanitize_hex_color( $color ) { 
     
    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 ) { 
     
    10131040 * 
    10141041 * @since 3.4.0 
     1042 * 
     1043 * @param string $color 
     1044 * @return string 
    10151045 */ 
    10161046function maybe_hash_hex_color( $color ) { 
  • trunk/wp-includes/class-wp-customize-section.php

    r20349 r21354  
    11<?php 
    22/** 
    3  * Customize Section Class 
     3 * Customize Section Class. 
    44 * 
    55 * @package WordPress 
     
    77 * @since 3.4.0 
    88 */ 
    9  
    109class WP_Customize_Section { 
    1110    public $manager; 
     
    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. 
     
    7373    } 
    7474 
    75  
    7675    /** 
    7776     * Render the section. 
  • trunk/wp-includes/class-wp-customize-setting.php

    r21053 r21354  
    11<?php 
    22/** 
    3  * Customize Setting Class 
     3 * Customize Setting Class. 
    44 * 
    55 * @package WordPress 
     
    77 * @since 3.4.0 
    88 */ 
    9  
    109class WP_Customize_Setting { 
    1110    public $manager; 
     
    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() ) { 
     
    8889     * 
    8990     * @since 3.4.0 
    90      * 
    91      * @param mixed Old value. 
     91     * @uses WP_Customize_Setting::multidimensional_replace() 
     92     * 
     93     * @param mixed $original Old value. 
    9294     * @return mixed New or old value. 
    9395     */ 
     
    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 ) { 
     
    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     */ 
     
    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     */ 
     
    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     */ 
     
    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     */ 
     
    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 ) { 
     
    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} 
     
    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; 
     
    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' ); 
Note: See TracChangeset for help on using the changeset viewer.