From 427cec893ece69e03f02afd553df126aabb00de9 Mon Sep 17 00:00:00 2001 From: Adam Silverstein Date: Fri, 18 Aug 2017 13:09:45 +0000 Subject: [PATCH] Docs: Improve JavaScript documentation in color-picker.js. Add and improve JSDOC blocks. Props carolinegeven, jjcomack, jipmoors. Fixes #41063. git-svn-id: https://develop.svn.wordpress.org/trunk@41264 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/js/color-picker.js | 176 ++++++++++++++++++++++++++++---- 1 file changed, 158 insertions(+), 18 deletions(-) diff --git a/src/wp-admin/js/color-picker.js b/src/wp-admin/js/color-picker.js index 807ff2a14c..0080491a0d 100644 --- a/src/wp-admin/js/color-picker.js +++ b/src/wp-admin/js/color-picker.js @@ -2,13 +2,18 @@ ( function( $, undef ){ var ColorPicker, - // html stuff _before = '', _after = '
', _wrap = '
', _button = ''; - // 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( '' ).after(self.button); + el.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 ) );