Changeset 41264

Timestamp:

08/18/2017 01:09:45 PM (7 years ago)

Author:

adamsilverstein

Message:

Docs: Improve JavaScript documentation in color-picker.js.

Add and improve JSDOC blocks.

Props carolinegeven, jjcomack, jipmoors.
Fixes #41063.

File:

• trunk/src/wp-admin/js/color-picker.js (modified) (18 diffs)

trunk/src/wp-admin/js/color-picker.js

@@ -3 +3 @@
 
     var ColorPicker,
-        // html stuff
         _before = '<a tabindex="0" class="wp-color-result" />',
         _after = '<div class="wp-picker-holder" />',
@@ -9 +8 @@
         _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: {
@@ -22 +27 @@
             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,
@@ -27 +41 @@
                 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',
@@ -37 +52 @@
                 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 ) ) {
@@ -46 +69 @@
             } );
         },
+        /**
+         * @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;
@@ -55 +89 @@
                 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();
@@ -80 +115 @@
             }
 
-            el.wrap( '<span class="wp-picker-input-wrap" />' ).after(self.button);
+            el.wrap( '<span class="wp-picker-input-wrap" />' ).after( self.button );
 
             el.iris( {
@@ -88 +123 @@
                 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 );
@@ -99 +147 @@
             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' ) ) {
@@ -119 +191 @@
             });
 
+            /**
+             * @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 );
@@ -132 +216 @@
             });
 
-            // 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 ) {
@@ -140 +235 @@
             });
 
+            /**
+             * @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 );
@@ -153 +259 @@
             });
         },
+        /**
+         * @summary Opens the color picker dialog.
+         *
+         * @since 3.5.0
+         *
+         * @returns {void}
+         */
         open: function() {
             this.element.show().iris( 'toggle' ).focus();
@@ -160 +273 @@
             $( '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' );
@@ -167 +287 @@
             $( '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 ) {
@@ -175 +304 @@
             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 ) {
@@ -186 +325 @@
     };
 
+    // Register the color picker as a widget.
     $.widget( 'wp.wpColorPicker', ColorPicker );
 }( jQuery ) );