[Summary view] [Print] [Text view]

   1  /**
   2   * @output wp-admin/js/color-picker.js
   3   *
   4   * @since 3.5.0
   5   */
   6  
   7  /**
   8   * Handles the color picker functionality.
   9   *
  10   * @param {JQueryStatic} $     The jQuery object.
  11   * @param {undefined}    undef The undefined value.
  12   */
  13  ( function( $, undef ) {
  14  
  15      var ColorPicker,
  16          _before = '<button type="button" class="button wp-color-result" aria-expanded="false"><span class="wp-color-result-text"></span></button>',
  17          _after = '<div class="wp-picker-holder" />',
  18          _wrap = '<div class="wp-picker-container" />',
  19          _button = '<input type="button" class="button button-small" />',
  20          _wrappingLabel = '<label></label>',
  21          _wrappingLabelText = '<span class="screen-reader-text"></span>',
  22          __ = wp.i18n.__;
  23  
  24      /**
  25       * Creates a jQuery UI color picker that is used in the theme customizer.
  26       *
  27       * @class $.widget.wp.wpColorPicker
  28       *
  29       * @since 3.5.0
  30       */
  31      ColorPicker = /** @lends $.widget.wp.wpColorPicker.prototype */{
  32          options: {
  33              defaultColor: false,
  34              change: false,
  35              clear: false,
  36              hide: true,
  37              palettes: true,
  38              width: 255,
  39              mode: 'hsv',
  40              type: 'full',
  41              slider: 'horizontal'
  42          },
  43          /**
  44           * Creates a color picker that only allows you to adjust the hue.
  45           *
  46           * @since 3.5.0
  47           * @access private
  48           *
  49           * @return {void}
  50           */
  51          _createHueOnly: function() {
  52              var self = this,
  53                  el = self.element,
  54                  color;
  55  
  56              el.hide();
  57  
  58              // Set the saturation to the maximum level.
  59              color = 'hsl(' + el.val() + ', 100, 50)';
  60  
  61              // Create an instance of the color picker, using the hsl mode.
  62              el.iris( {
  63                  mode: 'hsl',
  64                  type: 'hue',
  65                  hide: false,
  66                  color: color,
  67                  /**
  68                   * Handles the onChange event if one has been defined in the options.
  69                   *
  70                   * @ignore
  71                   *
  72                   * @param {Event}       event The event that's being called.
  73                   * @param {HTMLElement} ui    The HTMLElement containing the color picker.
  74                   *
  75                   * @return {void}
  76                   */
  77                  change: function( event, ui ) {
  78                      if ( typeof self.options.change === 'function' ) {
  79                          self.options.change.call( this, event, ui );
  80                      }
  81                  },
  82                  width: self.options.width,
  83                  slider: self.options.slider
  84              } );
  85          },
  86          /**
  87           * Creates the color picker, sets default values, css classes and wraps it all in HTML.
  88           *
  89           * @since 3.5.0
  90           * @access private
  91           *
  92           * @return {void}
  93           */
  94          _create: function() {
  95              // Return early if Iris support is missing.
  96              if ( ! $.support.iris ) {
  97                  return;
  98              }
  99  
 100              var self = this,
 101                  el = self.element;
 102  
 103              // Override default options with options bound to the element.
 104              $.extend( self.options, el.data() );
 105  
 106              // Create a color picker which only allows adjustments to the hue.
 107              if ( self.options.type === 'hue' ) {
 108                  return self._createHueOnly();
 109              }
 110  
 111              // Bind the close event.
 112              self.close = self.close.bind( self );
 113  
 114              self.initialValue = el.val();
 115  
 116              // Add a CSS class to the input field.
 117              el.addClass( 'wp-color-picker' );
 118  
 119              /*
 120               * Check if there's already a wrapping label, e.g. in the Customizer.
 121               * If there's no label, add a default one to match the Customizer template.
 122               */
 123              if ( ! el.parent( 'label' ).length ) {
 124                  // Wrap the input field in the default label.
 125                  el.wrap( _wrappingLabel );
 126                  // Insert the default label text.
 127                  self.wrappingLabelText = $( _wrappingLabelText )
 128                      .insertBefore( el )
 129                      .text( __( 'Color value' ) );
 130              }
 131  
 132              /*
 133               * At this point, either it's the standalone version or the Customizer
 134               * one, we have a wrapping label to use as hook in the DOM, let's store it.
 135               */
 136              self.wrappingLabel = el.parent();
 137  
 138              // Wrap the label in the main wrapper.
 139              self.wrappingLabel.wrap( _wrap );
 140              // Store a reference to the main wrapper.
 141              self.wrap = self.wrappingLabel.parent();
 142              // Set up the toggle button and insert it before the wrapping label.
 143              self.toggler = $( _before )
 144                  .insertBefore( self.wrappingLabel )
 145                  .css( { backgroundColor: self.initialValue } );
 146              // Set the toggle button span element text.
 147              self.toggler.find( '.wp-color-result-text' ).text( __( 'Select Color' ) );
 148              // Set up the Iris container and insert it after the wrapping label.
 149              self.pickerContainer = $( _after ).insertAfter( self.wrappingLabel );
 150              // Store a reference to the Clear/Default button.
 151              self.button = $( _button );
 152  
 153              // Set up the Clear/Default button.
 154              if ( self.options.defaultColor ) {
 155                  self.button
 156                      .addClass( 'wp-picker-default' )
 157                      .val( __( 'Default' ) )
 158                      .attr( 'aria-label', __( 'Select default color' ) );
 159              } else {
 160                  self.button
 161                      .addClass( 'wp-picker-clear' )
 162                      .val( __( 'Clear' ) )
 163                      .attr( 'aria-label', __( 'Clear color' ) );
 164              }
 165  
 166              // Wrap the wrapping label in its wrapper and append the Clear/Default button.
 167              self.wrappingLabel
 168                  .wrap( '<span class="wp-picker-input-wrap hidden" />' )
 169                  .after( self.button );
 170  
 171              /*
 172               * The input wrapper now contains the label+input+Clear/Default button.
 173               * Store a reference to the input wrapper: we'll use this to toggle
 174               * the controls visibility.
 175               */
 176              self.inputWrapper = el.closest( '.wp-picker-input-wrap' );
 177  
 178              el.iris( {
 179                  target: self.pickerContainer,
 180                  hide: self.options.hide,
 181                  width: self.options.width,
 182                  mode: self.options.mode,
 183                  palettes: self.options.palettes,
 184                  /**
 185                   * Handles the onChange event if one has been defined in the options and additionally
 186                   * sets the background color for the toggler element.
 187                   *
 188                   * @since 3.5.0
 189                   *
 190                   * @ignore
 191                   *
 192                   * @param {Event}       event The event that's being called.
 193                   * @param {HTMLElement} ui    The HTMLElement containing the color picker.
 194                   *
 195                   * @return {void}
 196                   */
 197                  change: function( event, ui ) {
 198                      self.toggler.css( { backgroundColor: ui.color.toString() } );
 199  
 200                      if ( typeof self.options.change === 'function' ) {
 201                          self.options.change.call( this, event, ui );
 202                      }
 203                  }
 204              } );
 205  
 206              el.val( self.initialValue );
 207              self._addListeners();
 208  
 209              // Force the color picker to always be closed on initial load.
 210              if ( ! self.options.hide ) {
 211                  self.toggler.click();
 212              }
 213          },
 214          /**
 215           * Binds event listeners to the color picker.
 216           *
 217           * @since 3.5.0
 218           * @access private
 219           *
 220           * @return {void}
 221           */
 222          _addListeners: function() {
 223              var self = this;
 224  
 225              /**
 226               * Prevent any clicks inside this widget from leaking to the top and closing it.
 227               *
 228               * @since 3.5.0
 229               *
 230               * @param {Event} event The event that's being called.
 231               *
 232               * @return {void}
 233               */
 234              self.wrap.on( 'click.wpcolorpicker', function( event ) {
 235                  event.stopPropagation();
 236              });
 237  
 238              /**
 239               * Open or close the color picker depending on the class.
 240               *
 241               * @since 3.5.0
 242               */
 243              self.toggler.on( 'click', function(){
 244                  if ( self.toggler.hasClass( 'wp-picker-open' ) ) {
 245                      self.close();
 246                  } else {
 247                      self.open();
 248                  }
 249              });
 250  
 251              /**
 252               * Checks if value is empty when changing the color in the color picker.
 253               * If so, the background color is cleared.
 254               *
 255               * @since 3.5.0
 256               *
 257               * @param {Event} event The event that's being called.
 258               *
 259               * @return {void}
 260               */
 261              self.element.on( 'change', function( event ) {
 262                  var me = $( this ),
 263                      val = me.val();
 264  
 265                  if ( val === '' || val === '#' ) {
 266                      self.toggler.css( 'backgroundColor', '' );
 267                      // Fire clear callback if we have one.
 268                      if ( typeof self.options.clear === 'function' ) {
 269                          self.options.clear.call( this, event );
 270                      }
 271                  }
 272              });
 273  
 274              /**
 275               * Enables the user to either clear the color in the color picker or revert back to the default color.
 276               *
 277               * @since 3.5.0
 278               *
 279               * @param {Event} event The event that's being called.
 280               *
 281               * @return {void}
 282               */
 283              self.button.on( 'click', function( event ) {
 284                  var me = $( this );
 285                  if ( me.hasClass( 'wp-picker-clear' ) ) {
 286                      self.element.val( '' );
 287                      self.toggler.css( 'backgroundColor', '' );
 288                      if ( typeof self.options.clear === 'function' ) {
 289                          self.options.clear.call( this, event );
 290                      }
 291                  } else if ( me.hasClass( 'wp-picker-default' ) ) {
 292                      self.element.val( self.options.defaultColor ).change();
 293                  }
 294              });
 295          },
 296          /**
 297           * Opens the color picker dialog.
 298           *
 299           * @since 3.5.0
 300           *
 301           * @return {void}
 302           */
 303          open: function() {
 304              this.element.iris( 'toggle' );
 305              this.inputWrapper.removeClass( 'hidden' );
 306              this.wrap.addClass( 'wp-picker-active' );
 307              this.toggler
 308                  .addClass( 'wp-picker-open' )
 309                  .attr( 'aria-expanded', 'true' );
 310              $( 'body' ).trigger( 'click.wpcolorpicker' ).on( 'click.wpcolorpicker', this.close );
 311          },
 312          /**
 313           * Closes the color picker dialog.
 314           *
 315           * @since 3.5.0
 316           *
 317           * @return {void}
 318           */
 319          close: function() {
 320              this.element.iris( 'toggle' );
 321              this.inputWrapper.addClass( 'hidden' );
 322              this.wrap.removeClass( 'wp-picker-active' );
 323              this.toggler
 324                  .removeClass( 'wp-picker-open' )
 325                  .attr( 'aria-expanded', 'false' );
 326              $( 'body' ).off( 'click.wpcolorpicker', this.close );
 327          },
 328          /**
 329           * Returns the iris object if no new color is provided. If a new color is provided, it sets the new color.
 330           *
 331           * @param {string|*} newColor The new color to use. Can be undefined.
 332           *
 333           * @since 3.5.0
 334           *
 335           * @return {string|void} The element's color.
 336           */
 337          color: function( newColor ) {
 338              if ( newColor === undef ) {
 339                  return this.element.iris( 'option', 'color' );
 340              }
 341              this.element.iris( 'option', 'color', newColor );
 342          },
 343  
 344          /**
 345           * Returns the iris object if no new default color is provided.
 346           * If a new default color is provided, it sets the new default color.
 347           *
 348           * @param {string|*} newDefaultColor The new default color to use. Can be undefined.
 349           *
 350           * @since 3.5.0
 351           *
 352           * @return {string|void} The element's default color.
 353           */
 354          defaultColor: function( newDefaultColor ) {
 355              if ( newDefaultColor === undef ) {
 356                  return this.options.defaultColor;
 357              }
 358  
 359              this.options.defaultColor = newDefaultColor;
 360          }
 361      };
 362  
 363      // Register the color picker as a widget.
 364      $.widget( 'wp.wpColorPicker', ColorPicker );
 365  }( jQuery ) );