Wordpress 3.5
[autoinstalls/wordpress.git] / wp-includes / class-wp-customize-control.php
index 3189332ac099d678b3d0fa100a14f734c75e0bf2..d24a5f2e7c4e7b6096a06e7aa1f3047834d9058f 100644 (file)
@@ -6,25 +6,71 @@
  * @subpackage Customize
  * @since 3.4.0
  */
-
 class WP_Customize_Control {
+       /**
+        * @access public
+        * @var WP_Customize_Manager
+        */
        public $manager;
+
+       /**
+        * @access public
+        * @var string
+        */
        public $id;
 
-       // All settings tied to the control.
+       /**
+        * All settings tied to the control.
+        *
+        * @access public
+        * @var array
+        */
        public $settings;
 
-       // The primary setting for the control (if there is one).
+       /**
+        * The primary setting for the control (if there is one).
+        *
+        * @access public
+        * @var string
+        */
        public $setting = 'default';
 
+       /**
+        * @access public
+        * @var int
+        */
        public $priority          = 10;
+
+       /**
+        * @access public
+        * @var string
+        */
        public $section           = '';
+
+       /**
+        * @access public
+        * @var string
+        */
        public $label             = '';
-       // @todo: remove choices
+
+       /**
+        * @todo: Remove choices
+        *
+        * @access public
+        * @var array
+        */
        public $choices           = array();
 
+       /**
+        * @access public
+        * @var array
+        */
        public $json = array();
 
+       /**
+        * @access public
+        * @var string
+        */
        public $type = 'text';
 
 
@@ -34,6 +80,10 @@ class WP_Customize_Control {
         * If $args['settings'] is not defined, use the $id as the setting ID.
         *
         * @since 3.4.0
+        *
+        * @param WP_Customize_Manager $manager
+        * @param string $id
+        * @param array $args
         */
        function __construct( $manager, $id, $args = array() ) {
                $keys = array_keys( get_object_vars( $this ) );
@@ -75,6 +125,9 @@ class WP_Customize_Control {
         * Grabs the main setting by default.
         *
         * @since 3.4.0
+        *
+        * @param string $setting_key
+        * @return mixed The requested setting's value, if the setting exists.
         */
        public final function value( $setting_key = 'default' ) {
                if ( isset( $this->settings[ $setting_key ] ) )
@@ -119,6 +172,7 @@ class WP_Customize_Control {
         * Check capabilities and render the control.
         *
         * @since 3.4.0
+        * @uses WP_Customize_Control::render()
         */
        public final function maybe_render() {
                if ( ! $this->check_capabilities() )
@@ -144,6 +198,14 @@ class WP_Customize_Control {
                </li><?php
        }
 
+       /**
+        * Get the data link parameter for a setting.
+        *
+        * @since 3.4.0
+        *
+        * @param string $setting_key
+        * @return string Data link parameter, if $setting_key is a valid setting, empty string otherwise.
+        */
        public function get_link( $setting_key = 'default' ) {
                if ( ! isset( $this->settings[ $setting_key ] ) )
                        return '';
@@ -151,6 +213,14 @@ class WP_Customize_Control {
                return 'data-customize-setting-link="' . esc_attr( $this->settings[ $setting_key ]->id ) . '"';
        }
 
+       /**
+        * Render the data link parameter for a setting
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Control::get_link()
+        *
+        * @param string $setting_key
+        */
        public function link( $setting_key = 'default' ) {
                echo $this->get_link( $setting_key );
        }
@@ -238,53 +308,117 @@ class WP_Customize_Control {
        }
 }
 
+/**
+ * Customize Color Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Color_Control extends WP_Customize_Control {
+       /**
+        * @access public
+        * @var string
+        */
        public $type = 'color';
+
+       /**
+        * @access public
+        * @var array
+        */
        public $statuses;
 
+       /**
+        * Constructor.
+        *
+        * If $args['settings'] is not defined, use the $id as the setting ID.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Control::__construct()
+        *
+        * @param WP_Customize_Manager $manager
+        * @param string $id
+        * @param array $args
+        */
        public function __construct( $manager, $id, $args = array() ) {
                $this->statuses = array( '' => __('Default') );
                parent::__construct( $manager, $id, $args );
        }
 
+       /**
+        * Enqueue control related scripts/styles.
+        *
+        * @since 3.4.0
+        */
        public function enqueue() {
-               wp_enqueue_script( 'farbtastic' );
-               wp_enqueue_style( 'farbtastic' );
+               wp_enqueue_script( 'wp-color-picker' );
+               wp_enqueue_style( 'wp-color-picker' );
        }
 
+       /**
+        * Refresh the parameters passed to the JavaScript via JSON.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Control::to_json()
+        */
        public function to_json() {
                parent::to_json();
                $this->json['statuses'] = $this->statuses;
        }
 
+       /**
+        * Render the control's content.
+        *
+        * @since 3.4.0
+        */
        public function render_content() {
+               $this_default = $this->setting->default;
+               $default_attr = '';
+               if ( $this_default ) {
+                       if ( false === strpos( $this_default, '#' ) )
+                               $this_default = '#' . $this_default;
+                       $default_attr = ' data-default-color="' . esc_attr( $this_default ) . '"';
+               }
+               // The input's value gets set by JS. Don't fill it.
                ?>
                <label>
                        <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
                        <div class="customize-control-content">
-                               <div class="dropdown">
-                                       <div class="dropdown-content">
-                                               <div class="dropdown-status"></div>
-                                       </div>
-                                       <div class="dropdown-arrow"></div>
-                               </div>
-                               <input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e('Hex Value'); ?>" />
+                               <input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>"<?php echo $default_attr ?> />
                        </div>
-                       <div class="farbtastic-placeholder"></div>
                </label>
                <?php
        }
 }
 
+/**
+ * Customize Upload Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Upload_Control extends WP_Customize_Control {
        public $type    = 'upload';
        public $removed = '';
        public $context;
+       public $extensions = array();
 
+       /**
+        * Enqueue control related scripts/styles.
+        *
+        * @since 3.4.0
+        */
        public function enqueue() {
                wp_enqueue_script( 'wp-plupload' );
        }
 
+       /**
+        * Refresh the parameters passed to the JavaScript via JSON.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Control::to_json()
+        */
        public function to_json() {
                parent::to_json();
 
@@ -292,8 +426,16 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
 
                if ( $this->context )
                        $this->json['context'] = $this->context;
+
+               if ( $this->extensions )
+                       $this->json['extensions'] = implode( ',', $this->extensions );
        }
 
+       /**
+        * Render the control's content.
+        *
+        * @since 3.4.0
+        */
        public function render_content() {
                ?>
                <label>
@@ -307,13 +449,33 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
        }
 }
 
+/**
+ * Customize Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
        public $type = 'image';
        public $get_url;
        public $statuses;
+       public $extensions = array( 'jpg', 'jpeg', 'gif', 'png' );
 
        protected $tabs = array();
 
+       /**
+        * Constructor.
+        *
+        * If $args['settings'] is not defined, use the $id as the setting ID.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Upload_Control::__construct()
+        *
+        * @param WP_Customize_Manager $manager
+        * @param string $id
+        * @param array $args
+        */
        public function __construct( $manager, $id, $args ) {
                $this->statuses = array( '' => __('No Image') );
 
@@ -338,11 +500,22 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                        $this->manager->remove_control( $this->id );
        }
 
+       /**
+        * Refresh the parameters passed to the JavaScript via JSON.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Upload_Control::to_json()
+        */
        public function to_json() {
                parent::to_json();
                $this->json['statuses'] = $this->statuses;
        }
 
+       /**
+        * Render the control's content.
+        *
+        * @since 3.4.0
+        */
        public function render_content() {
                $src = $this->value();
                if ( isset( $this->get_url ) )
@@ -353,7 +526,7 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                        <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
 
                        <div class="customize-control-content">
-                               <div class="dropdown preview-thumbnail">
+                               <div class="dropdown preview-thumbnail" tabindex="0">
                                        <div class="dropdown-content">
                                                <?php if ( empty( $src ) ): ?>
                                                        <img style="display:none;" />
@@ -369,7 +542,7 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                        <div class="library">
                                <ul>
                                        <?php foreach ( $this->tabs as $id => $tab ): ?>
-                                               <li data-customize-tab='<?php echo esc_attr( $id ); ?>'>
+                                               <li data-customize-tab='<?php echo esc_attr( $id ); ?>' tabindex='0'>
                                                        <?php echo esc_html( $tab['label'] ); ?>
                                                </li>
                                        <?php endforeach; ?>
@@ -388,6 +561,15 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                <?php
        }
 
+       /**
+        * Add a tab to the control.
+        *
+        * @since 3.4.0
+        *
+        * @param string $id
+        * @param string $label
+        * @param mixed $callback
+        */
        public function add_tab( $id, $label, $callback ) {
                $this->tabs[ $id ] = array(
                        'label'    => $label,
@@ -395,10 +577,20 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                );
        }
 
+       /**
+        * Remove a tab from the control.
+        *
+        * @since 3.4.0
+        *
+        * @param string $id
+        */
        public function remove_tab( $id ) {
                unset( $this->tabs[ $id ] );
        }
 
+       /**
+        * @since 3.4.0
+        */
        public function tab_upload_new() {
                if ( ! _device_can_upload() ) {
                        ?>
@@ -416,12 +608,21 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
                }
        }
 
+       /**
+        * @since 3.4.0
+        */
        public function tab_uploaded() {
                ?>
                <div class="uploaded-target"></div>
                <?php
        }
 
+       /**
+        * @since 3.4.0
+        *
+        * @param string $url
+        * @param string $thumbnail_url
+        */
        public function print_tab_image( $url, $thumbnail_url = null ) {
                $url = set_url_scheme( $url );
                $thumbnail_url = ( $thumbnail_url ) ? set_url_scheme( $thumbnail_url ) : $url;
@@ -433,7 +634,23 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
        }
 }
 
+/**
+ * Customize Background Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
+
+       /**
+        * Constructor.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Image_Control::__construct()
+        *
+        * @param WP_Customize_Manager $manager
+        */
        public function __construct( $manager ) {
                parent::__construct( $manager, 'background_image', array(
                        'label'    => __( 'Background Image' ),
@@ -446,6 +663,9 @@ class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
                        $this->add_tab( 'default',  __('Default'),  array( $this, 'tab_default_background' ) );
        }
 
+       /**
+        * @since 3.4.0
+        */
        public function tab_uploaded() {
                $backgrounds = get_posts( array(
                        'post_type'  => 'attachment',
@@ -464,11 +684,22 @@ class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
                        $this->print_tab_image( esc_url_raw( $background->guid ) );
        }
 
+       /**
+        * @since 3.4.0
+        * @uses WP_Customize_Image_Control::print_tab_image()
+        */
        public function tab_default_background() {
                $this->print_tab_image( $this->setting->default );
        }
 }
 
+/**
+ * Customize Header Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
        /**
         * The processed default headers.
@@ -484,6 +715,15 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
         */
        protected $uploaded_headers;
 
+       /**
+        * Constructor.
+        *
+        * @since 3.4.0
+        * @uses WP_Customize_Image_Control::__construct()
+        * @uses WP_Customize_Image_Control::add_tab()
+        *
+        * @param WP_Customize_Manager $manager
+        */
        public function __construct( $manager ) {
                parent::__construct( $manager, 'header_image', array(
                        'label'    => __( 'Header Image' ),
@@ -533,6 +773,12 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
                return parent::prepare_control();
        }
 
+       /**
+        * @since 3.4.0
+        *
+        * @param mixed $choice Which header image to select. (@see Custom_Image_Header::get_header_image() )
+        * @param array $header
+        */
        public function print_header_image( $choice, $header ) {
                $header['url']           = set_url_scheme( $header['url'] );
                $header['thumbnail_url'] = set_url_scheme( $header['thumbnail_url'] );
@@ -553,6 +799,9 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
                <?php
        }
 
+       /**
+        * @since 3.4.0
+        */
        public function tab_uploaded() {
                ?><div class="uploaded-target"></div><?php
 
@@ -560,6 +809,9 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
                        $this->print_header_image( $choice, $header );
        }
 
+       /**
+        * @since 3.4.0
+        */
        public function tab_default_headers() {
                foreach ( $this->default_headers as $choice => $header )
                        $this->print_header_image( $choice, $header );