mirror of
https://github.com/WordPress/WordPress.git
synced 2024-06-25 22:35:02 +02:00
Docs: Improve JavaScript documentation in color-picker.js.
Add and improve JSDOC blocks. Props carolinegeven, jjcomack, jipmoors. Fixes #41063. Built from https://develop.svn.wordpress.org/trunk@41264 git-svn-id: http://core.svn.wordpress.org/trunk@41104 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Adam Silverstein
parent
61d683989f
commit
d856eda571
|
|
@ -2,13 +2,18 @@
|
|||
( function( $, undef ){
|
||||
|
||||
var ColorPicker,
|
||||
// html stuff
|
||||
_before = '<a tabindex="0" class="wp-color-result" />',
|
||||
_after = '<div class="wp-picker-holder" />',
|
||||
_wrap = '<div class="wp-picker-container" />',
|
||||
_button = '<input type="button" class="button button-small hidden" />';
|
||||
|
||||
// jQuery UI Widget constructor
|
||||
/**
|
||||
* @summary Creates a jQuery UI color picker.
|
||||
*
|
||||
* Creates a jQuery UI color picker that is used in the theme customizer.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*/
|
||||
ColorPicker = {
|
||||
options: {
|
||||
defaultColor: false,
|
||||
|
|
@ -21,21 +26,39 @@
|
|||
type: 'full',
|
||||
slider: 'horizontal'
|
||||
},
|
||||
/**
|
||||
* @summary Creates a color picker that only allows you to adjust the hue.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @access private
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
_createHueOnly: function() {
|
||||
var self = this,
|
||||
el = self.element,
|
||||
color;
|
||||
|
||||
// hide input
|
||||
el.hide();
|
||||
// max saturated color for hue to be obvious
|
||||
|
||||
// Set the saturation to the maximum level.
|
||||
color = 'hsl(' + el.val() + ', 100, 50)';
|
||||
|
||||
// Create an instance of the color picker, using the hsl mode.
|
||||
el.iris( {
|
||||
mode: 'hsl',
|
||||
type: 'hue',
|
||||
hide: false,
|
||||
color: color,
|
||||
/**
|
||||
* @summary Handles the onChange event if one has been defined in the options.
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
* @param {HTMLElement} ui The HTMLElement containing the color picker.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
change: function( event, ui ) {
|
||||
if ( $.isFunction( self.options.change ) ) {
|
||||
self.options.change.call( this, event, ui );
|
||||
|
|
@ -45,8 +68,19 @@
|
|||
slider: self.options.slider
|
||||
} );
|
||||
},
|
||||
/**
|
||||
* @summary Creates the color picker.
|
||||
*
|
||||
* Creates the color picker, sets default values, css classes and wraps it all in HTML.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @access private
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
_create: function() {
|
||||
// bail early for unsupported Iris.
|
||||
// Return early if Iris support is missing.
|
||||
if ( ! $.support.iris ) {
|
||||
return;
|
||||
}
|
||||
|
|
@ -54,19 +88,20 @@
|
|||
var self = this,
|
||||
el = self.element;
|
||||
|
||||
// Override default options with options bound to the element.
|
||||
$.extend( self.options, el.data() );
|
||||
|
||||
// hue-only gets created differently
|
||||
// Create a color picker which only allows adjustments to the hue.
|
||||
if ( self.options.type === 'hue' ) {
|
||||
return self._createHueOnly();
|
||||
}
|
||||
|
||||
// keep close bound so it can be attached to a body listener
|
||||
// Bind the close event.
|
||||
self.close = $.proxy( self.close, self );
|
||||
|
||||
self.initialValue = el.val();
|
||||
|
||||
// Set up HTML structure, hide things
|
||||
// Set up HTML structure and hide the color picker.
|
||||
el.addClass( 'wp-color-picker' ).hide().wrap( _wrap );
|
||||
self.wrap = el.parent();
|
||||
self.toggler = $( _before ).insertBefore( el ).css( { backgroundColor: self.initialValue } ).attr( 'title', wpColorPickerL10n.pick ).attr( 'data-current', wpColorPickerL10n.current );
|
||||
|
|
@ -79,7 +114,7 @@
|
|||
self.button.addClass( 'wp-picker-clear' ).val( wpColorPickerL10n.clear );
|
||||
}
|
||||
|
||||
el.wrap( '<span class="wp-picker-input-wrap" />' ).after(self.button);
|
||||
el.wrap( '<span class="wp-picker-input-wrap" />' ).after( self.button );
|
||||
|
||||
el.iris( {
|
||||
target: self.pickerContainer,
|
||||
|
|
@ -87,9 +122,22 @@
|
|||
width: self.options.width,
|
||||
mode: self.options.mode,
|
||||
palettes: self.options.palettes,
|
||||
/**
|
||||
* @summary Handles the onChange event if one has been defined in the options.
|
||||
*
|
||||
* Handles the onChange event if one has been defined in the options and additionally
|
||||
* sets the background color for the toggler element.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
* @param {HTMLElement} ui The HTMLElement containing the color picker.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
change: function( event, ui ) {
|
||||
self.toggler.css( { backgroundColor: ui.color.toString() } );
|
||||
// check for a custom cb
|
||||
|
||||
if ( $.isFunction( self.options.change ) ) {
|
||||
self.options.change.call( this, event, ui );
|
||||
}
|
||||
|
|
@ -98,18 +146,42 @@
|
|||
|
||||
el.val( self.initialValue );
|
||||
self._addListeners();
|
||||
|
||||
// Force the color picker to always be closed on initial load.
|
||||
if ( ! self.options.hide ) {
|
||||
self.toggler.click();
|
||||
}
|
||||
},
|
||||
/**
|
||||
* @summary Binds event listeners to the color picker.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @access private
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
_addListeners: function() {
|
||||
var self = this;
|
||||
|
||||
// prevent any clicks inside this widget from leaking to the top and closing it
|
||||
/**
|
||||
* @summary Prevent any clicks inside this widget from leaking to the top and closing it.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
*
|
||||
* @returs {void}
|
||||
*/
|
||||
self.wrap.on( 'click.wpcolorpicker', function( event ) {
|
||||
event.stopPropagation();
|
||||
});
|
||||
|
||||
/**
|
||||
* @summary Open or close the color picker depending on the class.
|
||||
*
|
||||
* @since 3.5
|
||||
*/
|
||||
self.toggler.click( function(){
|
||||
if ( self.toggler.hasClass( 'wp-picker-open' ) ) {
|
||||
self.close();
|
||||
|
|
@ -118,20 +190,43 @@
|
|||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* @summary Checks if value is empty when changing the color in the color picker.
|
||||
*
|
||||
* Checks if value is empty when changing the color in the color picker.
|
||||
* If so, the background color is cleared.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
self.element.change( function( event ) {
|
||||
var me = $( this ),
|
||||
val = me.val();
|
||||
// Empty = clear
|
||||
|
||||
if ( val === '' || val === '#' ) {
|
||||
self.toggler.css( 'backgroundColor', '' );
|
||||
// fire clear callback if we have one
|
||||
// Fire clear callback if we have one.
|
||||
if ( $.isFunction( self.options.clear ) ) {
|
||||
self.options.clear.call( this, event );
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// open a keyboard-focused closed picker with space or enter
|
||||
/**
|
||||
* @summary Enables the user to open the color picker with their keyboard.
|
||||
*
|
||||
* Enables the user to open the color picker with their keyboard.
|
||||
* This is possible by using the space or enter key.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
self.toggler.on( 'keyup', function( event ) {
|
||||
if ( event.keyCode === 13 || event.keyCode === 32 ) {
|
||||
event.preventDefault();
|
||||
|
|
@ -139,6 +234,17 @@
|
|||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* @summary Enables the user to clear or revert the color in the color picker.
|
||||
*
|
||||
* Enables the user to either clear the color in the color picker or revert back to the default color.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @param {Event} event The event that's being called.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
self.button.click( function( event ) {
|
||||
var me = $( this );
|
||||
if ( me.hasClass( 'wp-picker-clear' ) ) {
|
||||
|
|
@ -152,6 +258,13 @@
|
|||
}
|
||||
});
|
||||
},
|
||||
/**
|
||||
* @summary Opens the color picker dialog.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
open: function() {
|
||||
this.element.show().iris( 'toggle' ).focus();
|
||||
this.button.removeClass( 'hidden' );
|
||||
|
|
@ -159,6 +272,13 @@
|
|||
this.toggler.addClass( 'wp-picker-open' );
|
||||
$( 'body' ).trigger( 'click.wpcolorpicker' ).on( 'click.wpcolorpicker', this.close );
|
||||
},
|
||||
/**
|
||||
* @summary Closes the color picker dialog.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
close: function() {
|
||||
this.element.hide().iris( 'toggle' );
|
||||
this.button.addClass( 'hidden' );
|
||||
|
|
@ -166,16 +286,35 @@
|
|||
this.toggler.removeClass( 'wp-picker-open' );
|
||||
$( 'body' ).off( 'click.wpcolorpicker', this.close );
|
||||
},
|
||||
// $("#input").wpColorPicker('color') returns the current color
|
||||
// $("#input").wpColorPicker('color', '#bada55') to set
|
||||
/**
|
||||
* @summary Returns iris object or sets new color.
|
||||
*
|
||||
* Returns the iris object if no new color is provided. If a new color is provided, it sets the new color.
|
||||
*
|
||||
* @param newColor {string|*} The new color to use. Can be undefined.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @returns {string} The element's color
|
||||
*/
|
||||
color: function( newColor ) {
|
||||
if ( newColor === undef ) {
|
||||
return this.element.iris( 'option', 'color' );
|
||||
}
|
||||
this.element.iris( 'option', 'color', newColor );
|
||||
},
|
||||
//$("#input").wpColorPicker('defaultColor') returns the current default color
|
||||
//$("#input").wpColorPicker('defaultColor', newDefaultColor) to set
|
||||
/**
|
||||
* @summary Returns iris object or sets new default color.
|
||||
*
|
||||
* Returns the iris object if no new default color is provided.
|
||||
* If a new default color is provided, it sets the new default color.
|
||||
*
|
||||
* @param newDefaultColor {string|*} The new default color to use. Can be undefined.
|
||||
*
|
||||
* @since 3.5.0
|
||||
*
|
||||
* @returns {boolean|string} The element's color.
|
||||
*/
|
||||
defaultColor: function( newDefaultColor ) {
|
||||
if ( newDefaultColor === undef ) {
|
||||
return this.options.defaultColor;
|
||||
|
|
@ -185,5 +324,6 @@
|
|||
}
|
||||
};
|
||||
|
||||
// Register the color picker as a widget.
|
||||
$.widget( 'wp.wpColorPicker', ColorPicker );
|
||||
}( jQuery ) );
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '4.9-alpha-41263';
|
||||
$wp_version = '4.9-alpha-41264';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user