Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

git-svn-id: http://core.svn.wordpress.org/trunk@21354 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
ryan 2012-07-26 21:45:33 +00:00
parent 44ef6d8e80
commit 564a7db2cb
4 changed files with 345 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

269
wp-includes/class-wp-customize-control.php
View 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() )
@ -143,14 +197,30 @@ class WP_Customize_Control {
<?php $this->render_content(); ?>
</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 '';
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,25 +308,69 @@ 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' );
}
/**
* 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() {
?>
<label>
@ -276,15 +390,33 @@ class WP_Customize_Color_Control extends WP_Customize_Control {
}
}
/**
* 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;
/**
* 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();
@ -294,6 +426,11 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
$this->json['context'] = $this->context;
}
/**
* Render the control's content.
*
* @since 3.4.0
*/
public function render_content() {
?>
<label>
@ -307,6 +444,13 @@ 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;
@ -314,6 +458,18 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
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') );
@ -323,11 +479,22 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
$this->add_tab( 'uploaded', __('Uploaded'), array( $this, 'tab_uploaded' ) );
}
/**
* 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 ) )
@ -372,7 +539,16 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
</div>
<?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,
@ -380,10 +556,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() ) {
?>
@ -400,13 +586,22 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
<?php
}
}
/**
* @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;
@ -418,7 +613,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' ),
@ -431,6 +642,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',
@ -448,13 +662,34 @@ class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
foreach ( (array) $backgrounds as $background )
$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 {
/**
* 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' ),
@ -477,6 +712,12 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
$this->add_tab( 'default', __('Default'), array( $this, 'tab_default_headers' ) );
}
/**
* @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'] );
@ -496,7 +737,10 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
</a>
<?php
}
/**
* @since 3.4.0
*/
public function tab_uploaded() {
$headers = get_uploaded_header_images();
@ -506,6 +750,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() {
global $custom_image_header;
$custom_image_header->process_default_headers();

60
wp-includes/class-wp-customize-manager.php
View File

@ -1,12 +1,11 @@
<?php
/**
* Customize
* Customize Manager.
*
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
final class WP_Customize_Manager {
protected $theme;
protected $original_stylesheet;
@ -56,10 +55,12 @@ final class WP_Customize_Manager {
add_action( 'customize_controls_enqueue_scripts', array( $this, 'enqueue_control_scripts' ) );
}
/**
/**
* Return true if it's an AJAX request.
*
* @since 3.4.0
*
* @return bool
*/
public function doing_ajax() {
return isset( $_POST['customized'] ) || ( defined( 'DOING_AJAX' ) && DOING_AJAX );
@ -69,10 +70,10 @@ final class WP_Customize_Manager {
* Custom wp_die wrapper. Returns either the standard message for UI
* or the AJAX message.
*
* @param mixed $ajax_message AJAX return
* @param mixed $message UI message
*
* @since 3.4.0
*
* @param mixed $ajax_message AJAX return
* @param mixed $message UI message
*/
protected function wp_die( $ajax_message, $message = null ) {
if ( $this->doing_ajax() )
@ -88,6 +89,8 @@ final class WP_Customize_Manager {
* Return the AJAX wp_die() handler if it's a customized request.
*
* @since 3.4.0
*
* @return string
*/
public function wp_die_handler() {
if ( $this->doing_ajax() )
@ -95,10 +98,11 @@ final class WP_Customize_Manager {
return '_default_wp_die_handler';
}
/**
* Start preview and customize theme.
*
* Check if customize query variable exist. Init filters to filter the current theme.
* Start preview and customize theme.
*
* Check if customize query variable exist. Init filters to filter the current theme.
*
* @since 3.4.0
*/
@ -136,7 +140,12 @@ final class WP_Customize_Manager {
$this->start_previewing_theme();
}
/**
* Callback to validate a theme once it is loaded
*
* @since 3.4.0
*/
function after_setup_theme() {
if ( ! $this->doing_ajax() && ! validate_current_theme() ) {
wp_redirect( 'themes.php?broken=true' );
@ -279,6 +288,9 @@ final class WP_Customize_Manager {
* Instead, the JS will sniff out the location header.
*
* @since 3.4.0
*
* @param $status
* @return int
*/
public function wp_redirect_status( $status ) {
if ( $this->is_preview() && ! is_admin() )
@ -291,6 +303,9 @@ final class WP_Customize_Manager {
* Decode the $_POST attribute used to override the WP_Customize_Setting values.
*
* @since 3.4.0
*
* @param mixed $setting A WP_Customize_Setting derived object
* @return string Sanitized attribute
*/
public function post_value( $setting ) {
if ( ! isset( $this->_post_values ) ) {
@ -367,11 +382,11 @@ final class WP_Customize_Manager {
);
if ( 2 == $this->nonce_tick ) {
$settings['nonce'] = array(
'save' => wp_create_nonce( 'save-customize_' . $this->get_stylesheet() ),
'preview' => wp_create_nonce( 'preview-customize_' . $this->get_stylesheet() )
);
}
$settings['nonce'] = array(
'save' => wp_create_nonce( 'save-customize_' . $this->get_stylesheet() ),
'preview' => wp_create_nonce( 'preview-customize_' . $this->get_stylesheet() )
);
}
foreach ( $this->settings as $id => $setting ) {
$settings['values'][ $id ] = $setting->js_value();
@ -464,6 +479,7 @@ final class WP_Customize_Manager {
*
* @since 3.4.0
*
* @param $current_theme {@internal Parameter is not used}
* @return string Theme name.
*/
public function current_theme( $current_theme ) {
@ -630,6 +646,7 @@ final class WP_Customize_Manager {
*
* @param object $a Object A.
* @param object $b Object B.
* @return int
*/
protected final function _cmp_priority( $a, $b ) {
$ap = $a->priority;
@ -960,6 +977,9 @@ final class WP_Customize_Manager {
* Accepts 'blank', and otherwise uses sanitize_hex_color_no_hash().
*
* @since 3.4.0
*
* @param string $color
* @return string
*/
public function _sanitize_header_textcolor( $color ) {
return ( 'blank' === $color ) ? 'blank' : sanitize_hex_color_no_hash( $color );
@ -973,6 +993,9 @@ final class WP_Customize_Manager {
* For validating values without a #, see sanitize_hex_color_no_hash().
*
* @since 3.4.0
*
* @param string $color
* @return string|null
*/
function sanitize_hex_color( $color ) {
if ( '' === $color )
@ -995,6 +1018,10 @@ function sanitize_hex_color( $color ) {
* Returns either '', a 3 or 6 digit hex color (without a #), or null.
*
* @since 3.4.0
* @uses sanitize_hex_color()
*
* @param string $color
* @return string|null
*/
function sanitize_hex_color_no_hash( $color ) {
$color = ltrim( $color, '#' );
@ -1012,6 +1039,9 @@ function sanitize_hex_color_no_hash( $color ) {
* This method should only be necessary if using sanitize_hex_color_no_hash().
*
* @since 3.4.0
*
* @param string $color
* @return string
*/
function maybe_hash_hex_color( $color ) {
if ( $unhashed = sanitize_hex_color_no_hash( $color ) )

5
wp-includes/class-wp-customize-section.php
View File

@ -1,12 +1,11 @@
<?php
/**
* Customize Section Class
* Customize Section Class.
*
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
class WP_Customize_Section {
public $manager;
public $id;
@ -22,6 +21,7 @@ class WP_Customize_Section {
*
* @since 3.4.0
*
* @param WP_Customize_Manager $manager
* @param string $id An specific ID of the section.
* @param array $args Section arguments.
*/
@ -72,7 +72,6 @@ class WP_Customize_Section {
$this->render();
}
/**
* Render the section.
*

50
wp-includes/class-wp-customize-setting.php
View File

@ -1,12 +1,11 @@
<?php
/**
* Customize Setting Class
* Customize Setting Class.
*
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
class WP_Customize_Setting {
public $manager;
public $id;
@ -28,9 +27,11 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param WP_Customize_Manager $manager
* @param string $id An specific ID of the setting. Can be a
* theme mod or option name.
* @param array $args Setting arguments.
* @return WP_Customize_Setting
*/
function __construct( $manager, $id, $args = array() ) {
$keys = array_keys( get_class_vars( __CLASS__ ) );
@ -87,8 +88,9 @@ class WP_Customize_Setting {
* Callback function to filter the theme mods and options.
*
* @since 3.4.0
* @uses WP_Customize_Setting::multidimensional_replace()
*
* @param mixed Old value.
* @param mixed $original Old value.
* @return mixed New or old value.
*/
public function _preview_filter( $original ) {
@ -118,8 +120,8 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param $default mixed A default value which is used as a fallback. Default is null.
* @return mixed Either the default value on failure or sanitized value.
* @param mixed $default A default value which is used as a fallback. Default is null.
* @return mixed The default value on failure, otherwise the sanitized value.
*/
public final function post_value( $default = null ) {
if ( isset( $this->_post_value ) )
@ -138,7 +140,7 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param $value mixed The value to sanitize.
* @param mixed $value The value to sanitize.
* @return mixed Null if an input isn't valid, otherwise the sanitized value.
*/
public function sanitize( $value ) {
@ -151,7 +153,7 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param $value mixed The value to update.
* @param mixed $value The value to update.
* @return mixed The result of saving the value.
*/
protected function update( $value ) {
@ -172,7 +174,7 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param $value mixed The value to update.
* @param mixed $value The value to update.
* @return mixed The result of saving the value.
*/
protected function _update_theme_mod( $value ) {
@ -192,7 +194,7 @@ class WP_Customize_Setting {
*
* @since 3.4.0
*
* @param $value mixed The value to update.
* @param mixed $value The value to update.
* @return mixed The result of saving the value.
*/
protected function _update_option( $value ) {
@ -276,7 +278,7 @@ class WP_Customize_Setting {
* @param $root
* @param $keys
* @param bool $create Default is false.
* @return null|array
* @return null|array Keys are 'root', 'node', and 'key'.
*/
final protected function multidimensional( &$root, $keys, $create = false ) {
if ( $create && empty( $root ) )
@ -372,8 +374,16 @@ class WP_Customize_Setting {
* A setting that is used to filter a value, but will not save the results.
*
* Results should be properly handled using another setting or callback.
*
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
class WP_Customize_Filter_Setting extends WP_Customize_Setting {
/**
* @since 3.4.0
*/
public function update() {}
}
@ -381,10 +391,19 @@ class WP_Customize_Filter_Setting extends WP_Customize_Setting {
* A setting that is used to filter a value, but will not save the results.
*
* Results should be properly handled using another setting or callback.
*
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
public $id = 'header_image_data';
/**
* @since 3.4.0
*
* @param $value
*/
public function update( $value ) {
global $custom_image_header;
@ -400,9 +419,20 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
}
}
/**
* @package WordPress
* @subpackage Customize
* @since 3.4.0
*/
final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
public $id = 'background_image_thumb';
/**
* @since 3.4.0
* @uses remove_theme_mod()
*
* @param $value
*/
public function update( $value ) {
remove_theme_mod( 'background_image_thumb' );
}