[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('slider-value-range', function (Y, NAME) {
   9  
  10  /**
  11   * Adds value support for Slider as a range of integers between a configured
  12   * minimum and maximum value.  For use with <code>Y.Base.build(..)</code> to
  13   * add the plumbing to <code>Y.SliderBase</code>.
  14   *
  15   * @module slider
  16   * @submodule slider-value-range
  17   */
  18  
  19  // Constants for compression or performance
  20  var MIN       = 'min',
  21      MAX       = 'max',
  22      VALUE     = 'value',
  23  //     MINORSTEP = 'minorStep',
  24  //     MAJORSTEP = 'majorStep',
  25  
  26      round = Math.round;
  27  
  28  /**
  29   * One class of value algorithm that can be built onto SliderBase.  By default,
  30   * values range between 0 and 100, but you can configure these on the
  31   * built Slider class by setting the <code>min</code> and <code>max</code>
  32   * configurations.  Set the initial value (will cause the thumb to move to the
  33   * appropriate location on the rail) in configuration as well if appropriate.
  34   *
  35   * @class SliderValueRange
  36   */
  37  function SliderValueRange() {
  38      this._initSliderValueRange();
  39  }
  40  
  41  Y.SliderValueRange = Y.mix( SliderValueRange, {
  42  
  43      // Prototype properties and methods that will be added onto host class
  44      prototype: {
  45  
  46          /**
  47           * Factor used to translate value -&gt; position -&gt; value.
  48           *
  49           * @property _factor
  50           * @type {Number}
  51           * @protected
  52           */
  53          _factor: 1,
  54  
  55          /**
  56           * Stub for construction logic.  Override if extending this class and
  57           * you need to set something up during the initializer phase.
  58           *
  59           * @method _initSliderValueRange
  60           * @protected
  61           */
  62          _initSliderValueRange: function () {},
  63  
  64          /**
  65           * Override of stub method in SliderBase that is called at the end of
  66           * its bindUI stage of render().  Subscribes to internal events to
  67           * trigger UI and related state updates.
  68           *
  69           * @method _bindValueLogic
  70           * @protected
  71           */
  72          _bindValueLogic: function () {
  73              this.after( {
  74                  minChange  : this._afterMinChange,
  75                  maxChange  : this._afterMaxChange,
  76                  valueChange: this._afterValueChange
  77              } );
  78          },
  79  
  80          /**
  81           * Move the thumb to appropriate position if necessary.  Also resets
  82           * the cached offsets and recalculates the conversion factor to
  83           * translate position to value.
  84           *
  85           * @method _syncThumbPosition
  86           * @protected
  87           */
  88          _syncThumbPosition: function () {
  89              this._calculateFactor();
  90  
  91              this._setPosition( this.get( VALUE ) );
  92          },
  93  
  94          /**
  95           * Calculates and caches
  96           * (range between max and min) / (rail length)
  97           * for fast runtime calculation of position -&gt; value.
  98           *
  99           * @method _calculateFactor
 100           * @protected
 101           */
 102          _calculateFactor: function () {
 103              var length    = this.get( 'length' ),
 104                  thumbSize = this.thumb.getStyle( this._key.dim ),
 105                  min       = this.get( MIN ),
 106                  max       = this.get( MAX );
 107  
 108              // The default thumb width is based on Sam skin's thumb dimension.
 109              // This attempts to allow for rendering off-DOM, then attaching
 110              // without the need to call syncUI().  It is still recommended
 111              // to call syncUI() in these cases though, just to be sure.
 112              length = parseFloat( length ) || 150;
 113              thumbSize = parseFloat( thumbSize ) || 15;
 114  
 115              this._factor = ( max - min ) / ( length - thumbSize );
 116  
 117              Y.log("Calculating factor(~" + this._factor.toFixed(3) + " = (max(" + max + ") - min(" + min + ")) / (length(" + length + ") - thumb size(" + thumbSize + "))","info","slider");
 118          },
 119  
 120          /**
 121           * Dispatch the new position of the thumb into the value setting
 122           * operations.
 123           *
 124           * @method _defThumbMoveFn
 125           * @param e { EventFacade } The host's thumbMove event
 126           * @protected
 127           */
 128          _defThumbMoveFn: function ( e ) {
 129              // To prevent set('value', x) from looping back around
 130              if (e.source !== 'set') {
 131                  this.set(VALUE, this._offsetToValue(e.offset));
 132              }
 133          },
 134  
 135          /**
 136           * <p>Converts a pixel position into a value.  Calculates current
 137           * thumb offset from the leading edge of the rail multiplied by the
 138           * ratio of <code>(max - min) / (constraining dim)</code>.</p>
 139           *
 140           * <p>Override this if you want to use a different value mapping
 141           * algorithm.</p>
 142           *
 143           * @method _offsetToValue
 144           * @param offset { Number } X or Y pixel offset
 145           * @return { mixed } Value corresponding to the provided pixel offset
 146           * @protected
 147           */
 148          _offsetToValue: function ( offset ) {
 149  
 150              var value = round( offset * this._factor ) + this.get( MIN );
 151  
 152              Y.log("Offset: " + offset + " => Value: " + value, "info", "slider");
 153              return round( this._nearestValue( value ) );
 154          },
 155  
 156          /**
 157           * Converts a value into a pixel offset for use in positioning
 158           * the thumb according to the reverse of the
 159           * <code>_offsetToValue( xy )</code> operation.
 160           *
 161           * @method _valueToOffset
 162           * @param val { Number } The value to map to pixel X or Y position
 163           * @return { Number } The pixel offset
 164           * @protected
 165           */
 166          _valueToOffset: function ( value ) {
 167              var offset = round( ( value - this.get( MIN ) ) / this._factor );
 168  
 169              Y.log("Value: " + value + " => Offset: " + offset, "info", "slider");
 170              return offset;
 171          },
 172  
 173          /**
 174           * Returns the current value.  Override this if you want to introduce
 175           * output formatting. Otherwise equivalent to slider.get( "value" );
 176           *
 177           * @method getValue
 178           * @return {Number}
 179           */
 180          getValue: function () {
 181              return this.get( VALUE );
 182          },
 183  
 184          /**
 185           * Updates the current value.  Override this if you want to introduce
 186           * input value parsing or preprocessing.  Otherwise equivalent to
 187           * slider.set( "value", v );
 188           *
 189           * @method setValue
 190           * @param val {Number} The new value
 191           * @return {Slider}
 192           * @chainable
 193           */
 194          setValue: function ( val ) {
 195              return this.set( VALUE, val );
 196          },
 197  
 198          /**
 199           * Update position according to new min value.  If the new min results
 200           * in the current value being out of range, the value is set to the
 201           * closer of min or max.
 202           *
 203           * @method _afterMinChange
 204           * @param e { EventFacade } The <code>min</code> attribute change event.
 205           * @protected
 206           */
 207          _afterMinChange: function ( e ) {
 208              this._verifyValue();
 209  
 210              this._syncThumbPosition();
 211          },
 212  
 213          /**
 214           * Update position according to new max value.  If the new max results
 215           * in the current value being out of range, the value is set to the
 216           * closer of min or max.
 217           *
 218           * @method _afterMaxChange
 219           * @param e { EventFacade } The <code>max</code> attribute change event.
 220           * @protected
 221           */
 222          _afterMaxChange: function ( e ) {
 223              this._verifyValue();
 224  
 225              this._syncThumbPosition();
 226          },
 227  
 228          /**
 229           * Verifies that the current value is within the min - max range.  If
 230           * not, value is set to either min or max, depending on which is
 231           * closer.
 232           *
 233           * @method _verifyValue
 234           * @protected
 235           */
 236          _verifyValue: function () {
 237              var value   = this.get( VALUE ),
 238                  nearest = this._nearestValue( value );
 239  
 240              if ( value !== nearest ) {
 241                  // @TODO Can/should valueChange, minChange, etc be queued
 242                  // events? To make dd.set( 'min', n ); execute after minChange
 243                  // subscribers before on/after valueChange subscribers.
 244                  this.set( VALUE, nearest );
 245              }
 246          },
 247  
 248          /**
 249           * Propagate change to the thumb position unless the change originated
 250           * from the thumbMove event.
 251           *
 252           * @method _afterValueChange
 253           * @param e { EventFacade } The <code>valueChange</code> event.
 254           * @protected
 255           */
 256          _afterValueChange: function ( e ) {
 257              var val = e.newVal;
 258              Y.log("Positioning thumb after set('value',x)","info","slider");
 259              this._setPosition( val, { source: 'set' } );
 260          },
 261  
 262          /**
 263           * Positions the thumb and its ARIA attributes in accordance with the
 264           * translated value.
 265           *
 266           * @method _setPosition
 267           * @param value {Number} Value to translate to a pixel position
 268           * @param [options] {Object} Details object to pass to `_uiMoveThumb`
 269           * @protected
 270           */
 271          _setPosition: function ( value, options ) {
 272              this._uiMoveThumb( this._valueToOffset( value ), options );
 273              this.thumb.set('aria-valuenow', value);
 274              this.thumb.set('aria-valuetext', value);
 275          },
 276  
 277          /**
 278           * Validates new values assigned to <code>min</code> attribute.  Numbers
 279           * are acceptable.  Override this to enforce different rules.
 280           *
 281           * @method _validateNewMin
 282           * @param value {Any} Value assigned to <code>min</code> attribute.
 283           * @return {Boolean} True for numbers.  False otherwise.
 284           * @protected
 285           */
 286          _validateNewMin: function ( value ) {
 287              return Y.Lang.isNumber( value );
 288          },
 289  
 290          /**
 291           * Validates new values assigned to <code>max</code> attribute.  Numbers
 292           * are acceptable.  Override this to enforce different rules.
 293           *
 294           * @method _validateNewMax
 295           * @param value { mixed } Value assigned to <code>max</code> attribute.
 296           * @return { Boolean } True for numbers.  False otherwise.
 297           * @protected
 298           */
 299          _validateNewMax: function ( value ) {
 300              return Y.Lang.isNumber( value );
 301          },
 302  
 303          /**
 304           * Restricts new values assigned to <code>value</code> attribute to be
 305           * between the configured <code>min</code> and <code>max</code>.
 306           * Rounds to nearest integer value.
 307           *
 308           * @method _setNewValue
 309           * @param value { Number } Value assigned to <code>value</code> attribute
 310           * @return { Number } Normalized and constrained value
 311           * @protected
 312           */
 313          _setNewValue: function ( value ) {
 314              if ( Y.Lang.isNumber( value ) ) {
 315                  return round( this._nearestValue( value ) );
 316              }
 317              return Y.Attribute.INVALID_VALUE;
 318          },
 319  
 320          /**
 321           * Returns the nearest valid value to the value input.  If the provided
 322           * value is outside the min - max range, accounting for min > max
 323           * scenarios, the nearest of either min or max is returned.  Otherwise,
 324           * the provided value is returned.
 325           *
 326           * @method _nearestValue
 327           * @param value { mixed } Value to test against current min - max range
 328           * @return { Number } Current min, max, or value if within range
 329           * @protected
 330           */
 331          _nearestValue: function ( value ) {
 332              var min = this.get( MIN ),
 333                  max = this.get( MAX ),
 334                  tmp;
 335  
 336              // Account for reverse value range (min > max)
 337              tmp = ( max > min ) ? max : min;
 338              min = ( max > min ) ? min : max;
 339              max = tmp;
 340  
 341              return ( value < min ) ?
 342                      min :
 343                      ( value > max ) ?
 344                          max :
 345                          value;
 346          }
 347  
 348      },
 349  
 350      /**
 351       * Attributes that will be added onto host class.
 352       *
 353       * @property ATTRS
 354       * @type {Object}
 355       * @static
 356       * @protected
 357       */
 358      ATTRS: {
 359          /**
 360           * The value associated with the farthest top, left position of the
 361           * rail.  Can be greater than the configured <code>max</code> if you
 362           * want values to increase from right-to-left or bottom-to-top.
 363           *
 364           * @attribute min
 365           * @type { Number }
 366           * @default 0
 367           */
 368          min: {
 369              value    : 0,
 370              validator: '_validateNewMin'
 371          },
 372  
 373          /**
 374           * The value associated with the farthest bottom, right position of
 375           * the rail.  Can be less than the configured <code>min</code> if
 376           * you want values to increase from right-to-left or bottom-to-top.
 377           *
 378           * @attribute max
 379           * @type { Number }
 380           * @default 100
 381           */
 382          max: {
 383              value    : 100,
 384              validator: '_validateNewMax'
 385          },
 386  
 387          /**
 388           * amount to increment/decrement the Slider value
 389           * when the arrow up/down/left/right keys are pressed
 390           *
 391           * @attribute minorStep
 392           * @type {Number}
 393           * @default 1
 394           */
 395          minorStep : {
 396              value: 1
 397          },
 398  
 399          /**
 400           * amount to increment/decrement the Slider value
 401           * when the page up/down keys are pressed
 402           *
 403           * @attribute majorStep
 404           * @type {Number}
 405           * @default 10
 406           */
 407          majorStep : {
 408              value: 10
 409          },
 410  
 411          /**
 412           * The value associated with the thumb's current position on the
 413           * rail. Defaults to the value inferred from the thumb's current
 414           * position. Specifying value in the constructor will move the
 415           * thumb to the position that corresponds to the supplied value.
 416           *
 417           * @attribute value
 418           * @type { Number }
 419           * @default (inferred from current thumb position)
 420           */
 421          value: {
 422              value : 0,
 423              setter: '_setNewValue'
 424          }
 425      }
 426  }, true );
 427  
 428  
 429  }, '3.17.2', {"requires": ["slider-base"]});