WordPress.org
Get WordPress

Make WordPress Core

Changeset 21354


Ignore:
Timestamp:
07/26/2012 09:45:33 PM (12 years 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.